10.TypeScript tsconfig.json 配置文件详解

10.TypeScript tsconfig.json 配置文件详解

1. 什么是 tsconfig.json

tsconfig.json 是 TypeScript 项目的配置文件，用于指定编译项目所需的根文件和编译器选项。当运行 tsc 命令时，TypeScript 编译器会自动查找并使用该配置文件。

2. 生成 tsconfig.json

可以通过以下命令生成默认的 tsconfig.json 文件：

npx tsc --init

该命令会在项目根目录下生成一个带有大量注释的 tsconfig.json 文件，其中包含了所有可用的编译器选项及其默认值。

3. 常见字段含义

3.1. 文件包含选项

• files: 指定要编译的文件列表。如果指定了 files，则只有列出的文件及其依赖会被编译。
• include: 指定要包含在编译过程中的文件或目录。支持 glob 模式匹配。
• exclude: 指定要排除在编译过程之外的文件或目录。默认排除 node_modules、bower_components、jspm_packages 和 <outDir> 目录。

3.2. 编译选项 (compilerOptions)

• target: 指定编译后的 JavaScript 版本。常用值包括 ES5、ES6/ES2015、ES2016、ES2017、ES2018、ES2019、ES2020、ESNext。
• module: 指定生成的模块代码。常用值包括 CommonJS（Node.js 默认）、AMD、UMD、System、ES6/ES2015、ES2020、ESNext、None。
• lib: 指定编译过程中需要包含的库文件。例如 ES5、ES6、DOM、DOM.Iterable 等。
• outDir: 指定编译后 JavaScript 文件的输出目录。
• rootDir: 指定 TypeScript 源文件的根目录。用于控制输出目录结构。
• allowJs: 允许编译 JavaScript 文件。
• checkJs: 报告 JavaScript 文件中的错误。需要 allowJs 为 true。
• jsx: 指定 JSX 代码生成方式。常用值包括 preserve、react-native、react。
• declaration: 生成相应的 .d.ts 声明文件。
• sourceMap: 生成相应的 .map 文件，用于调试。
• outFile: 将所有输出打包到一个文件中。仅在 module 为 AMD 或 System 时可用。
• removeComments: 删除所有注释。
• noEmit: 不生成输出文件。
• importHelpers: 从 tslib 导入辅助工具函数，以减少代码重复。
• downlevelIteration: 当 target 为 ES5 或 ES3 时，提供更完整的迭代器支持。
• strict: 启用所有严格的类型检查选项。这是一个总开关，启用后会自动启用以下所有 strict 相关选项。
• noImplicitAny: 禁止隐式的 any 类型。
• strictNullChecks: 启用严格的 null 检查。
• strictFunctionTypes: 启用严格的函数类型检查。
• strictBindCallApply: 启用严格的 bind、call 和 apply 方法。
• strictPropertyInitialization: 启用类属性初始化的严格检查。
• noImplicitThis: 禁止 this 的隐式类型为 any。
• alwaysStrict: 以严格模式解析并为每个源文件生成 "use strict" 语句。
• noUnusedLocals: 报告未使用的局部变量错误。
• noUnusedParameters: 报告未使用的函数参数错误。
• noImplicitReturns: 报告函数所有代码路径都未明确返回值的错误。
• noFallthroughCasesInSwitch: 报告 switch 语句中 fallthrough 的错误。
• moduleResolution: 指定模块解析策略。常用值包括 node（Node.js）和 classic（TypeScript 1.6 之前）。
• baseUrl: 解析非相对模块名的基准目录。
• paths: 设置模块名到基于 baseUrl 的路径映射。
• rootDirs: 虚拟地将多个目录合并成一个源目录。
• typeRoots: 指定要包含的类型定义包的根目录。
• types: 指定要包含的类型定义包名称列表。
• allowSyntheticDefaultImports: 允许从没有设置默认导出的模块中默认导入。
• esModuleInterop: 启用 CommonJS 和 ES 模块之间的互操作性。会自动设置 allowSyntheticDefaultImports 为 true。
• skipLibCheck: 跳过声明文件的类型检查。
• forceConsistentCasingInFileNames: 禁止对同一文件使用大小写不一致的引用。

4. 常用配置示例

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "CommonJS",
    "lib": ["ES2015", "DOM"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

这个配置示例定义了一个典型的 TypeScript 项目设置，它将 src 目录下的 TypeScript 文件编译为 ES2015 目标的 JavaScript 代码，并输出到 dist 目录。同时启用了严格的类型检查和模块互操作性支持。