TypeScript编译选项使用及说明

一、前言

在开发 TypeScript 项目时，一个非常关键的文件就是 tsconfig.json。它不仅定义了项目的根目录、模块解析方式，还控制着 TypeScript 编译器的行为。

本文将带你全面了解：

• ✅ tsconfig.json 的作用
• ✅ 常用编译选项（compilerOptions）详解
• ✅ 不同环境下的配置建议（开发 / 生产）
• ✅ 配置继承与共享设置
• ✅ 实际开发中的常见问题与解决方法

并通过完整的代码示例帮助你掌握如何正确配置 TypeScript 项目。

二、什么是tsconfig.json？

定义：

tsconfig.json 是 TypeScript 项目的配置文件，用于指定项目的编译选项和行为。

当你在项目根目录下添加该文件后，TypeScript 编译器会自动识别并应用这些配置。

作用：

• 指定编译目标（ES 版本、模块系统等）
• 控制类型检查严格程度
• 设置输出目录
• 支持路径别名、装饰器等功能

三、基本结构示例

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    },
    "sourceMap": true,
    "declaration": false,
    "removeComments": true,
    "noEmit": false,
    "watch": false
  },
  "include": ["src/**/*"]
}

四、常用编译选项详解

1.target：指定编译目标版本

"target": "ES2020"

常见值：

• "ES3"（默认）
• "ES5"
• "ES2015"（ES6）
• "ES2020"
• "ESNext"

2.module：指定模块系统

"module": "ESNext"

常见值：

• "CommonJS"（Node.js 默认）
• "ESNext"（推荐用于现代浏览器）
• "UMD"、"AMD" 等

3.lib：指定编译过程中使用的库

"lib": ["ES2020", "DOM"]

示例组合：

• 浏览器环境：["ES2020", "DOM"]
• Node.js 环境：["ES2020", "ES2021.Promise", "ES2021.String"]

4.strict：启用所有严格类型检查选项

"strict": true

包含以下子选项（开启后不可单独关闭）：

• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• strictPropertyInitialization
• noImplicitThis
• alwaysStrict

5.moduleResolution：模块解析策略

"moduleResolution": "node"

常见值：

• "classic"（旧版）
• "node"（推荐用于 Node.js 或 Webpack 项目）

6.esModuleInterop：允许 CommonJS 和 ES 模块互操作

"esModuleInterop": true

推荐开启，避免导入时出现 .default 问题。

7.skipLibCheck：跳过类型声明文件的检查

"skipLibCheck": true

推荐开启以加快编译速度。

8.outDir：指定输出目录

"outDir": "./dist"

9.rootDir：指定源码目录

"rootDir": "./src"

10.baseUrl与paths：配置路径别名

"baseUrl": ".",
"paths": {
  "@/*": ["./*"]
}

使用方式：

import utils from '@/utils/index';

11.sourceMap：生成 source map 文件

"sourceMap": true

用于调试，生产环境可设为 false。

12.declaration：是否生成.d.ts类型声明文件

"declaration": true

适用于库项目，方便别人使用你的包。

13.removeComments：是否移除注释

"removeComments": true

14.noEmit：是否生成编译后的文件

"noEmit": false

开发阶段可设为 true，只进行类型检查。

15.watch：监听文件变化并重新编译

"watch": true

五、不同环境的配置建议

六、配置继承与复用

你可以通过 extends 属性继承其他配置文件，便于多个项目共用配置。

{
  "extends": "@myorg/tsconfig-base",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

常见基础配置包：

• @tsconfig/recommended
• @tsconfig/node18
• 自定义 npm 包（如团队内部统一配置）

七、常见问题与解决方案

八、总结对比表：常用 compilerOptions 对比

九、总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。