tsconfig.json配置选项说明 -岩石教程

配置示例

{
  "compileOnSave": false,          // 在保存文件时自动编译项目
  "compilerOptions": {             // 编译选项
    "target": "es5",               // ECMAScript 目标版本
    "module": "commonjs",          // 模块系统
    "lib": ["es2015", "dom"],      // 编译中包含的库文件
    "allowJs": true,               // 允许编译 JavaScript 文件
    "checkJs": false,              // 检查 JavaScript 文件中的错误
    "jsx": "react",                // JSX 代码生成
    "declaration": true,           // 生成相应的 .d.ts 文件
    "declarationMap": true,        // 为每个 .d.ts 文件生成源映射
    "sourceMap": true,             // 生成对应的 .map 文件
    "outFile": "./dist/app.js",    // 输出文件（仅用于 AMD 和 System 模块）
    "outDir": "./dist",            // 输出目录
    "rootDir": "./src",            // 输入文件的根目录
    "composite": true,             // 启用项目引用
    "incremental": true,           // 启用增量编译
    "tsBuildInfoFile": "./.tsbuildinfo", // 增量编译信息文件的位置
    "removeComments": true,        // 删除编译后的所有注释
    "noEmit": false,               // 不生成输出文件
    "noEmitOnError": true,         // 发生错误时不生成输出文件
    "strict": true,                // 启用所有严格类型检查选项
    "noImplicitAny": true,         // 禁止隐式 any 类型
    "strictNullChecks": true,      // 启用严格的 null 检查
    "strictFunctionTypes": true,   // 启用严格函数类型检查
    "strictBindCallApply": true,   // 启用严格的 bind、call 和 apply 方法检查
    "strictPropertyInitialization": true, // 启用严格的属性初始化检查
    "noImplicitThis": true,        // 禁止隐式 this 类型
    "alwaysStrict": true,          // 启用严格模式
    "noUnusedLocals": true,        // 禁止未使用的局部变量
    "noUnusedParameters": true,    // 禁止未使用的参数
    "noImplicitReturns": true,     // 禁止函数中缺少返回值
    "noFallthroughCasesInSwitch": true, // 禁止 switch 语句的 fallthrough 情况
    "moduleResolution": "node",    // 模块解析策略
    "baseUrl": "./",               // 非相对模块的基准目录
    "paths": {                     // 模块名到路径映射
      "module/*": ["module/src/*"]
    },
    "rootDirs": ["src", "generated"], // 多个目录放在一个虚拟目录下
    "typeRoots": ["./node_modules/@types"], // 包含类型声明的目录列表
    "types": ["node", "jest"],     // 需要包含的类型声明包
    "allowSyntheticDefaultImports": true, // 允许默认导入非模块文件
    "esModuleInterop": true,       // 启用 ECMAScript 模块的默认导入
    "preserveSymlinks": true,      // 不解析符号链接
    "allowUmdGlobalAccess": true,  // 允许在模块中访问 UMD 全局变量
    "isolatedModules": true,       // 启用每个文件的单独编译
    "preserveConstEnums": true,    // 不删除 const enum 定义
    "declarationDir": "./types",   // 声明文件输出目录
    "noEmitHelpers": true,         // 不生成辅助代码
    "importHelpers": true,         // 从 tslib 中导入辅助工具函数
    "downlevelIteration": true     // 启用降级迭代
  },
  "include": ["src/**/*"],         // 需要编译的文件或目录
  "exclude": ["node_modules", "dist"], // 不需要编译的文件或目录
  "files": ["src/index.ts"],       // 需要编译的具体文件
  "references": [                  // 项目引用
    { "path": "./core" },
    { "path": "./utils" }
  ],
  "extends": "./base.tsconfig.json" // 继承另一个 tsconfig.json 文件
}

基本选项

配置项	类型	默认值	可选参数	说明
`compileOnSave`	`boolean`	`false`	`true`, `false`	在保存文件时自动编译项目
`extends`	`string`	`undefined`	字符串	继承另一个 `tsconfig.json` 文件
`files`	`array`	`[]`	-	指定需要编译的具体文件
`include`	`array`	`[]`	-	指定需要编译的文件或目录
`exclude`	`array`	`[]`	-	指定不需要编译的文件或目录

compilerOptions详细配置

编译选项

配置项	类型	默认值	可选参数	说明
`target`	`string`	`ES3`	`ES3`, `ES5`, `ES6/ES2015`, `ES2016`, `ES2017`, `ES2018`, `ES2019`, `ES2020`, `ES2021`, `ES2022`, `ESNext`	指定 ECMAScript 的目标版本
`module`	`string`	`None`	`CommonJS`, `AMD`, `System`, `UMD`, `ES6/ES2015`, `ES2020`, `ES2022`, `ESNext`, `None`	指定模块代码生成
`lib`	`array`	`[]`	`es5`, `es6`, `es7`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `dom`, `dom.iterable`, `webworker`, `scripthost`, `esnext`	指定要包含在编译中的库文件
`allowJs`	`boolean`	`false`	`true`, `false`	允许编译 JavaScript 文件
`checkJs`	`boolean`	`false`	`true`, `false`	报告 JavaScript 文件中的错误
`jsx`	`string`	`preserve`	`preserve`, `react-native`, `react`	指定 JSX 代码生成
`declaration`	`boolean`	`false`	`true`, `false`	生成相应的 `.d.ts` 文件
`declarationMap`	`boolean`	`false`	`true`, `false`	为每个 `.d.ts` 文件生成源映射
`sourceMap`	`boolean`	`false`	`true`, `false`	生成对应的 `.map` 文件
`outFile`	`string`	`undefined`	路径字符串	将输出文件合并为一个文件（仅适用于 `AMD` 和 `System` 模块）
`outDir`	`string`	`undefined`	路径字符串	指定输出目录
`rootDir`	`string`	`undefined`	路径字符串	指定输入文件的根目录（用于相对路径计算）
`composite`	`boolean`	`false`	`true`, `false`	启用项目引用
`incremental`	`boolean`	`false`	`true`, `false`	启用增量编译
`tsBuildInfoFile`	`string`	`.tsbuildinfo`	路径字符串	指定 TypeScript 增量编译信息文件的位置
`removeComments`	`boolean`	`false`	`true`, `false`	删除编译后的所有注释
`noEmit`	`boolean`	`false`	`true`, `false`	不生成输出文件
`noEmitOnError`	`boolean`	`false`	`true`, `false`	发生错误时不生成输出文件

严格类型检查选项

配置项	类型	默认值	可选参数	说明
`strict`	`boolean`	`false`	`true`, `false`	启用所有严格类型检查选项
`noImplicitAny`	`boolean`	`false`	`true`, `false`	在表达式和声明上有隐含的 `any` 类型时报错
`strictNullChecks`	`boolean`	`false`	`true`, `false`	启用严格的 null 检查
`strictFunctionTypes`	`boolean`	`false`	`true`, `false`	启用严格函数类型检查
`strictBindCallApply`	`boolean`	`false`	`true`, `false`	启用严格的 `bind`, `call` 和 `apply` 方法检查
`strictPropertyInitialization`	`boolean`	`false`	`true`, `false`	在构造函数中强制属性初始化
`noImplicitThis`	`boolean`	`false`	`true`, `false`	在 `this` 表达式上有隐含的 `any` 类型时报错
`alwaysStrict`	`boolean`	`false`	`true`, `false`	以严格模式解析并为每个文件生成 `'use strict';`

代码质量检查选项

配置项	类型	默认值	可选参数	说明
`noUnusedLocals`	`boolean`	`false`	`true`, `false`	有未使用的局部变量时抛出错误
`noUnusedParameters`	`boolean`	`false`	`true`, `false`	有未使用的参数时抛出错误
`noImplicitReturns`	`boolean`	`false`	`true`, `false`	并非所有函数都有返回值时抛出错误
`noFallthroughCasesInSwitch`	`boolean`	`false`	`true`, `false`	报告 switch 语句的 fallthrough 错误

模块解析选项

配置项	类型	默认值	可选参数	说明
`moduleResolution`	`string`	`classic`	`node`, `classic`	选择模块解析策略
`baseUrl`	`string`	`undefined`	路径字符串	解析非相对模块的基准目录
`paths`	`object`	`{}`	-	模块名到基于 baseUrl 的路径映射
`rootDirs`	`array`	`[]`	-	将多个目录放在一个虚拟目录下
`typeRoots`	`array`	`[]`	-	包含类型声明的目录列表
`types`	`array`	`[]`	-	需要包含的类型声明包
`allowSyntheticDefaultImports`	`boolean`	`false`	`true`, `false`	允许默认导入非模块的文件
`esModuleInterop`	`boolean`	`false`	`true`, `false`	启用 ECMAScript 模块的默认导入
`preserveSymlinks`	`boolean`	`false`	`true`, `false`	不将符号链接解析为其真实路径
`allowUmdGlobalAccess`	`boolean`	`false`	`true`, `false`	允许在模块中访问 UMD 全局变量

高级选项

配置项	类型	默认值	可选参数	说明
`isolatedModules`	`boolean`	`false`	`true`, `false`	启用每个文件的单独编译
`preserveConstEnums`	`boolean`	`false`	`true`, `false`	不删除 `const enum` 定义
`declarationDir`	`string`	`undefined`	路径字符串	指定声明文件输出目录
`noEmitHelpers`	`boolean`	`false`	`true`, `false`	不生成辅助代码
`importHelpers`	`boolean`	`false`	`true`, `false`	从 `tslib` 中导入辅助工具函数
`downlevelIteration`	`boolean`	`false`	`true`, `false`	启用降级迭代
`references`	`array`	`[]`	-	设置项目引用，每个引用是一个对象，包含一个 `path` 属性