前言

tsconfig.json 是 TypeScript 项目的配置文件，用于指定编译选项和文件包含规则。以下是所有主要配置参数的中文详解：

核心配置

compilerOptions (编译器选项)

基本选项

• target: 指定编译后的 JavaScript 目标版本 (如"esnext", “es5”, “es6”, “es2015”, “es2020” 等)
• module: 指定模块系统 (如 “commonjs”, “amd”, “es2015”, “esnext” 等)
• lib: 指定要包含的库文件声明 (如 [ “esnext”, “es5”, “es6”, “dom”])
• allowJs: 允许编译 JavaScript 文件 (true/false)
• checkJs: 在 JavaScript 文件中报告错误 (true/false)
• jsx: 指定 JSX 代码生成方式 (“preserve”, “react”, “react-jsx”, “react-jsxdev” 等)
• declaration: 生成对应的 .d.ts 声明文件 (true/false)
• declarationMap: 为声明文件生成 sourcemap (true/false)
• sourceMap: 生成对应的 .map 文件 (true/false)
• outFile: 将所有输出合并为一个文件 (仅适用于 module 为 “amd” 或 “system”)
• outDir: 指定输出目录
• rootDir: 指定输入文件的根目录
• composite: 启用项目编译 (true/false)
• incremental: 启用增量编译 (true/false)
• tsBuildInfoFile: 指定增量编译信息文件的路径

严格类型检查选项

• strict: 启用所有严格类型检查选项 (true/false)
• noImplicitAny: 禁止隐式 any 类型 (true/false)
• strictNullChecks: 启用严格的 null 检查 (true/false)
• strictFunctionTypes: 启用严格的函数类型检查 (true/false)
• strictBindCallApply: 对 bind, call, apply 方法进行严格检查 (true/false)
• strictPropertyInitialization: 确保类的属性已初始化 (true/false)
• noImplicitThis: 禁止隐式 any 类型的 this (true/false)
• alwaysStrict: 以严格模式解析并为每个源文件生成 “use strict” (true/false)

模块解析选项

• moduleResolution: 指定模块解析策略 (“node” 或 “classic”)
• baseUrl: 解析非相对模块名的基准目录
• paths: 设置模块名到基于 baseUrl 的路径映射
• rootDirs: 将多个目录合并为一个虚拟目录
• typeRoots: 指定类型定义文件的目录列表
• types: 指定要包含的类型声明文件包
• allowUmdGlobalAccess: 允许从模块访问 UMD 全局变量 (true/false)
• resolveJsonModule: 允许导入 JSON 模块 (true/false)
• preserveSymlinks: 不解析符号链接的真实路径 (true/false)

Source Map 选项

• sourceRoot: 指定调试器应该定位的 TypeScript 文件位置
• mapRoot: 指定调试器应该定位的 map 文件位置
• inlineSourceMap: 将 sourcemap 嵌入到生成的 JS 文件中 (true/false)
• inlineSources: 将源代码与 sourcemaps 一起嵌入到单个文件中 (true/false)

实验性选项

• experimentalDecorators: 启用实验性装饰器支持 (true/false)
• emitDecoratorMetadata: 为装饰器提供元数据支持 (true/false)

其他选项

• importHelpers: 从 tslib 导入辅助工具函数 (true/false)
• downlevelIteration: 为迭代器提供更准确的降级支持 (true/false)
• isolatedModules: 确保每个文件都可以安全地独立编译 (true/false)
• allowSyntheticDefaultImports: 允许从没有默认导出的模块进行默认导入 (true/false)
• esModuleInterop: 启用更兼容的 CommonJS/AMD/UMD 模块导入导出 (true/false)
• forceConsistentCasingInFileNames: 强制文件名大小写一致 (true/false)
• skipLibCheck: 跳过声明文件的类型检查 (true/false)
• noEmit: 不生成输出文件 (true/false)
• noEmitOnError: 当有错误时不生成输出文件 (true/false)
• noEmitHelpers: 不生成辅助函数，需手动引入 (true/false)
• noImplicitReturns: 函数中所有代码路径必须返回值 (true/false)
• noFallthroughCasesInSwitch: 防止 switch 语句贯穿 (true/false)
• noUnusedLocals: 报告未使用的局部变量 (true/false)
• noUnusedParameters: 报告未使用的函数参数 (true/false)\
• noUncheckedIndexedAccess: 在索引访问中包含 undefined (true/false)
• noPropertyAccessFromIndexSignature: 禁止通过点符号访问索引签名属性 (true/false)
• removeComments: 移除注释 (true/false)
• preserveConstEnums: 保留 const enum 声明 (true/false)
• newLine: 指定换行符 (“crlf” 或 “lf”)
• useDefineForClassFields: 使用现代类字段定义方式 (true/false)
• keyofStringsOnly: 使 keyof 仅返回字符串 (true/false)
• suppressExcessPropertyErrors: 禁止额外属性检查 (true/false)
• suppressImplicitAnyIndexErrors: 禁止隐式索引错误 (true/false)
• noErrorTruncation: 不截短错误消息 (true/false)
• charset: 已弃用，指定输入文件的字符集
• emitBOM: 在输出文件开头写入 BOM (true/false)
• locale: 指定错误消息的语言环境 (如 “en-us”, “zh-cn”)
• disableSizeLimit: 禁用 JavaScript 项目大小限制 (true/false)
• listFiles: 打印编译的文件名 (true/false)
• listEmittedFiles: 打印输出的文件名 (true/false)
• traceResolution: 打印模块解析日志 (true/false)
• diagnostics: 打印诊断信息 (true/false)
• extendedDiagnostics: 打印扩展诊断信息 (true/false)
• generateCpuProfile: 生成 CPU 分析文
• plugins: 指定要运行的编译器插件列表

文件包含/排除选项

• files: 指定要包含的文件列表
• include: 指定要包含的文件模式
• exclude: 指定要排除的文件模式
• extends: 继承另一个 tsconfig.json 文件的配置
• references: 项目引用配置
• compileOnSave: 指示 IDE 在保存时编译 (true/false)
• typeAcquisition: 指定自动类型获取的选项

详细用法示例

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": "./",
    "paths": {
      "@utils/*": ["src/utils/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

最佳实践建议

• 对于新项目，建议启用 strict: true 以获得最严格的类型检查
• 使用 include 和 exclude 替代 files 来管理文件包含
• 对于大型项目，考虑使用项目引用 (references) 来拆分代码库
• 使用 extends 继承共享配置，避免重复配置
• 对于 Node.js 项目，target 设为 es2018 或更高版本可以获得更好的性能
• 启用 esModuleInterop 可以简化 CommonJS 模块的导入