TypeScript(tsconfig.json - 全描述)

TypeScript 配置（tsconfig.json）完全指南

本文基于 TypeScript 官方文档（www.typescriptlang.org/tsconfig/）整理，系统梳理 tsconfig.json 的核心配置分类、字段含义、默认值及使用场景，帮助开发者快速理解和配置 TypeScript 项目。

一、TSConfig 核心概念

TSConfig 文件（通常命名为 tsconfig.json）用于标识 TypeScript/JavaScript 项目的根目录，并定义项目的编译选项、文件范围、依赖关系等配置。其核心作用是：

1. 告诉 TypeScript 编译器如何处理项目代码；

2. 统一项目的类型检查、模块解析、输出格式等规则；

3. 支持多项目依赖管理（通过项目引用）和编译优化。

二、顶层配置（Root Fields）

顶层配置直接定义在 tsconfig.json 根节点，用于控制项目的整体结构和文件范围，不包含在 compilerOptions 中。

配置字段	中文含义	功能描述	默认值	生效版本
files	文件列表	指定项目中需包含的具体文件路径（数组形式），文件不存在会报错，适合少量文件场景。	false -（未指定时为空数组）	1.5
extends	继承配置	指定另一个 TSConfig 文件的路径，实现配置继承（基础配置先加载，子配置覆盖冲突项）。⚠️ 注意：references 字段不支持继承。	false	2.1
include	包含文件 / 模式	指定需包含的文件或 glob 模式（如 src/**/*），路径相对于 tsconfig.json 所在目录。	若指定 files 则为 []， 否则为 */	2.0
exclude	排除文件 / 模式	指定需从 include 中排除的文件或模式，仅影响 include 的结果，不阻止通过 import/reference 引入文件。	node_modules、 bower_components、 jspm_packages、 outDir	2.0
references	项目引用	定义多项目依赖关系，将大型项目拆分为子项目，支持隔离编译和依赖复用（需子项目开启 composite: true）。	false（空数组）	3.0

顶层配置示例

{
  "extends": "./configs/base.json", // 继承基础配置
  "files": ["core.ts", "app.ts"],   // 指定核心文件
  "include": ["src/**/*", "tests/**/*"], // 包含src和tests下所有文件
  "exclude": ["node_modules", "src/**/*.test.ts"], // 排除node_modules和测试文件
  "references": [                   // 引用子项目
    { "path": "./packages/utils" },
    { "path": "./packages/components" }
  ]
}

三、编译器选项（compilerOptions）

compilerOptions 是 TSConfig 的核心，包含类型检查、模块处理、输出控制等细分配置，按功能分为 13 大类。

1. 类型检查（Type Checking）

控制 TypeScript 的类型严格性，确保代码类型安全，减少运行时错误。

配置字段	中文含义	功能描述	默认值	生效版本
allowUnreachableCode	允许不可达代码	控制是否忽略 / 报错不可达代码（如 return 后的代码）。 - undefined：编辑器警告； - true：忽略； - false：报错。	undefined	1.8
allowUnusedLabels	允许未使用标签	控制是否忽略 / 报错未使用的标签（如循环标签）。 - 取值逻辑同 allowUnreachableCode。	undefined	1.8
alwaysStrict	始终严格模式	确保代码按 ES 严格模式解析，并在输出 JS 中添加 "use strict"。	true（若 strict: true）；否则 false	2.1
exactOptionalPropertyTypes	严格可选属性类型	禁止可选属性（? 修饰）赋值为 undefined，仅允许声明的类型或不定义该属性。	false	4.4
noFallthroughCasesInSwitch	禁止 switch 贯穿	报错 switch 语句中未加 break/return/throw 的贯穿 case。	false	1.8
noImplicitAny	禁止隐式 any	当变量 / 参数类型隐含为 any 时报错，强制显式声明类型。	true（若 strict: true）；否则 false	1.0
noImplicitOverride	禁止隐式重写	派生类重写父类方法时，必须添加 override 修饰符，避免意外重写。	false	4.3
noImplicitReturns	禁止隐式返回	检查函数所有代码路径是否显式返回值，避免遗漏返回逻辑。	false	1.8
noImplicitThis	禁止隐式 this	当 this 类型隐含为 any 时报错，强制明确 this 类型。	true（若 strict: true）；否则 false	2.0
noPropertyAccessFromIndexSignature	禁止索引签名用点访问	索引签名声明的属性（如 [key: string]: string）必须用 obj["key"] 访问，而非 obj.key。	false	4.2
noUncheckedIndexedAccess	检查索引访问	索引访问时自动添加 undefined 类型（如 arr[0] 为 `T	undefined`），避免越界错误。	false
noUnusedLocals	禁止未使用局部变量	未读取的局部变量报错。	false	2.0
noUnusedParameters	禁止未使用参数	未读取的函数参数报错。	false	2.0
strict	开启所有严格检查	一键启用所有严格模式选项（如 noImplicitAny、strictNullChecks 等），推荐生产环境开启。	false	2.3
strictBindCallApply	严格检查 bind/call/apply	确保 bind/call/apply 的参数与原函数参数类型匹配。	true（若 strict: true）；否则 false	3.2
strictBuiltinIteratorReturn	严格内置迭代器返回值	内置迭代器的 TReturn 类型设为 undefined（而非 any），提升类型安全性。	true（若 strict: true）；否则 false	5.6
strictFunctionTypes	严格函数类型	函数赋值时严格检查参数和返回值的子类型兼容性（仅对函数语法生效，方法语法不生效）。	true（若 strict: true）；否则 false	2.6
strictNullChecks	严格空值检查	区分 null/undefined 与其他类型，禁止直接使用可能为 null/undefined 的值。	true（若 strict: true）；否则 false	2.0
strictPropertyInitialization	严格属性初始化	类属性必须在构造函数中初始化或设为可选（undefined），否则报错。	true（若 strict: true）；否则 false	2.7
useUnknownInCatchVariables	Catch 变量用 unknown	将 catch 语句中异常变量的类型设为 unknown（而非 any），强制显式类型判断。	true（若 strict: true）；否则 false	4.4

2. 模块配置（Modules）

控制模块解析、导入导出语法及模块系统类型，适配不同运行时（如 Node.js、浏览器 bundler）。

配置字段	中文含义	功能描述	默认值	生效版本
allowArbitraryExtensions	允许任意扩展名导入	允许导入非 JS/TS 扩展名的文件（如 .css/.svg），需配合对应 .d.ts 声明文件。	false	5.0
allowImportingTsExtensions	允许导入 TS 扩展名	允许导入时包含 .ts/.tsx/.mts 等 TS 扩展名（需开启 noEmit 或 emitDeclarationOnly）。	true（若 rewriteRelativeImportExtensions: true）；否则 false	5.0
allowUmdGlobalAccess	允许 UMD 全局访问	模块文件中可直接访问 UMD 模块的全局变量（如 jQuery 的 $），无需 import。	false	3.5
baseUrl	基础目录	解析非相对模块名（如 import "utils"）的基础目录，常与 paths 配合使用。	./（若未指定，默认相对于 tsconfig.json）	2.0
customConditions	自定义解析条件	解析 package.json 的 exports/imports 字段时，额外添加自定义条件（如 my-condition）。	[]	5.0
module	模块系统	指定生成的模块代码格式，适配不同运行时： - commonjs：Node.js 传统模块； - node16/nodenext：现代 Node.js（支持 ESM/CJS 自动切换）； - esnext/es2022：浏览器 bundler（如 Webpack）； - preserve：保留输入的导入导出格式。	commonjs（若 target: ES5）；否则 es6	1.0
moduleResolution	模块解析策略	指定模块查找算法： - node10：旧版 Node.js（仅 CJS）； - node16/nodenext：现代 Node.js（ESM/CJS 双支持）； - bundler：适配 bundler（如 Vite/Rollup，无需文件扩展名）； - classic：TS 早期策略（不推荐）。	随 module 自动匹配（如 module: commonjs 对应 node10）	1.6
moduleSuffixes	模块后缀列表	解析模块时优先查找的后缀（如 [".ios", ".native", ""]，适配 React Native 多平台）。	[]	4.7
noResolve	禁止自动解析	禁止 TS 自动解析 import/reference 引入的文件，需手动确保依赖存在。	false	1.0
noUncheckedSideEffectImports	检查副作用导入	副作用导入（如 import "./style.css"）若无法找到文件则报错，避免拼写错误。	false	5.6
paths	模块路径映射	重写模块导入路径（基于 baseUrl），如将 import "jquery" 映射到 ./vendor/jquery。	{}	2.0
resolveJsonModule	解析 JSON 模块	允许导入 .json 文件，并自动生成其类型（基于 JSON 静态结构）。	false	2.9
resolvePackageJsonExports	解析 package.json 的 exports	解析模块时优先使用 package.json 的 exports 字段（控制包的导出入口）。	true（若 moduleResolution: node16/nodenext/bundler）；否则 false	5.0
resolvePackageJsonImports	解析 package.json 的 imports	解析以 # 开头的导入时，使用 package.json 的 imports 字段（包内私有路径映射）。	true（若 moduleResolution: node16/nodenext/bundler）；否则 false	5.0
rewriteRelativeImportExtensions	重写相对导入扩展名	将 TS 扩展名（.ts/.tsx）在输出 JS 中替换为对应 JS 扩展名（如 .js/.jsx）。	false	5.7
rootDir	源代码根目录	指定源代码根目录，确保输出目录（outDir）保留与源代码一致的目录结构。	所有非声明输入文件的最长公共路径（若 composite: true，则为 tsconfig.json 所在目录）	1.5
rootDirs	虚拟根目录列表	将多个目录视为 “虚拟根目录”，允许跨目录的相对导入（如 src/views 和 generated/templates/views 合并为一个根）。	基于输入文件计算	2.0
typeRoots	类型根目录	指定类型声明文件（.d.ts）的目录（默认包含 node_modules/@types），仅加载该目录下的类型包。	["node_modules/@types"]	2.0
types	指定类型包	仅加载指定的 @types 包（如 ["node", "jest"]），其他 @types 包不加载。	加载所有可见 @types 包	2.0

3. 输出控制（Emit）

控制 TypeScript 编译后的文件输出（如 JS 文件、类型声明、源映射等）。

配置字段	中文含义	功能描述	默认值	生效版本
declaration	生成类型声明	为每个 TS/JS 文件生成 .d.ts 类型声明文件（描述模块对外 API）。	true（若 composite: true）；否则 false	1.0
declarationDir	类型声明输出目录	指定 .d.ts 文件的输出根目录（默认与 JS 文件同目录）。	./	2.0
declarationMap	生成类型声明源映射	为 .d.ts 文件生成源映射（.d.ts.map），支持编辑器 “跳转至原 TS 文件”。	false	2.9
downlevelIteration	降级迭代支持	为 ES5 环境生成更兼容的迭代代码（如 for...of、数组展开），依赖 Symbol.iterator。	false	2.3
emitBOM	生成 UTF-8 BOM	输出文件开头添加 UTF-8 字节顺序标记（BOM），适配部分需 BOM 的运行环境。	false	1.0
emitDeclarationOnly	仅生成类型声明	只输出 .d.ts 文件，不输出 JS 文件（适合用其他工具 transpile JS 的场景）。	false	2.8
importHelpers	导入辅助函数	从 tslib 导入编译辅助函数（如 __spreadArray），减少代码重复（需安装 tslib）。	false	2.1
inlineSourceMap	内联源映射	将源映射内容嵌入 JS 文件（而非生成单独 .map 文件），适合不允许 .map 文件的场景。	false	1.5
inlineSources	内联源代码	将原 TS 源代码嵌入到 JS 文件的源映射中，便于调试（需配合 inlineSourceMap 或 sourceMap）。	false	1.5
mapRoot	源映射根目录	指定调试器查找源映射文件的路径（替代默认生成路径）。	""	1.5
newLine	换行符类型	指定输出文件的换行符：crlf（Windows）或 lf（Unix/Linux/Mac）。	跟随操作系统	1.5
noEmit	禁止输出文件	仅执行类型检查，不生成任何 JS/.d.ts/ 源映射文件。	false	1.0
noEmitHelpers	禁止生成辅助函数	不生成编译辅助函数（需手动提供或通过 importHelpers 导入）。	false	1.8
noEmitOnError	报错时禁止输出	若存在类型检查错误，不生成任何输出文件，避免错误代码上线。	false	1.5
outDir	输出目录	指定所有编译产物（JS/.d.ts/ 源映射）的输出目录。	与源文件同目录	1.5
outFile	合并输出文件	将所有输出打包为单个 JS 文件（仅支持 amd/system 模块系统），若开启 declaration 则同时打包 .d.ts。	""	1.5
preserveConstEnums	保留 const 枚举	不删除 const enum 声明（默认会将枚举值直接替换为常量，保留后便于调试）。	false	1.5
removeComments	移除注释	输出文件中不保留注释（减少文件体积）。	false	1.5
sourceMap	生成源映射	为 JS 文件生成单独的源映射文件（.map），便于调试原 TS 代码。	false	1.5
sourceRoot	源代码根路径	指定调试器查找原 TS 代码的根路径（用于远程调试）。	""	1.5
stripInternal	移除内部声明	不输出 JSDoc 中包含 @internal 的类型声明（隐藏内部 API）。	false	1.8

4. JavaScript 支持（JavaScript Support）

控制 TypeScript 对 JavaScript 文件的处理能力（如类型检查、包含 JS 文件）。

配置字段	中文含义	功能描述	默认值	生效版本
allowJs	允许 JS 文件	将 JS 文件纳入项目编译范围（配合 checkJs 可对 JS 进行类型检查）。	false	1.8
checkJs	检查 JS 文件	对 JS 文件进行类型检查（需配合 allowJs: true），报错 JS 中的类型问题。	false	1.8
maxNodeModuleJsDepth	Node 模块 JS 检查深度	检查 node_modules 中 JS 文件的最大目录深度（仅 allowJs: true 时生效）。	0（不检查）	2.0

5. 编辑器支持（Editor Support）

优化编辑器（如 VS Code）对 TypeScript 项目的支持，如插件、性能限制。

配置字段	中文含义	功能描述	默认值	生效版本
disableSizeLimit	禁用大小限制	取消 TypeScript 对项目大小的限制（适合超大型项目）。	false	-
plugins	编辑器插件	配置 TypeScript 语言服务插件（如 typescript-eslint、prettier）。	[]	-

6. 互操作约束（Interop Constraints）

控制不同模块系统（如 ESM、CommonJS）之间的互操作行为，避免兼容问题。

配置字段	中文含义	功能描述	默认值	生效版本
allowSyntheticDefaultImports	允许合成默认导入	允许对无默认导出的模块使用 import x from "module"（生成合成默认导入）。	true（若 esModuleInterop: true）；否则 false	1.8
erasableSyntaxOnly	仅可擦除语法	仅保留可被擦除的 TypeScript 语法（如类型注解），不保留其他非标准语法。	false	5.0
esModuleInterop	ESM 与 CJS 互操作	生成额外代码适配 ESM 导入 CommonJS 模块（自动开启 allowSyntheticDefaultImports）。	false	2.7
forceConsistentCasingInFileNames	强制文件名大小写一致	确保导入路径的大小写与实际文件一致（避免跨系统运行问题，如 Windows 不区分大小写）。	false	2.0
isolatedDeclarations	隔离声明文件	确保每个声明文件（.d.ts）可独立编译，不依赖其他声明文件。	false	5.0
isolatedModules	隔离模块	确保每个文件可独立转译（不依赖其他文件），适配 bundler（如 Babel、SWC）。	false	1.8
preserveSymlinks	保留符号链接	不将符号链接（symlink）解析为真实路径（与 Node.js --preserve-symlinks 一致）。	false	2.0
verbatimModuleSyntax	原样保留模块语法	不转换 / 省略非 “仅类型”（type-only）的导入导出，按 module 配置原样输出。	false	4.7

7. 向后兼容（Backwards Compatibility）

兼容旧版 TypeScript 或 JavaScript 代码，避免升级后报错。

配置字段	中文含义	功能描述	默认值	生效版本
charset	文件编码	指定输入文件的编码格式（如 utf8、utf16）。	utf8	1.0
importsNotUsedAsValues	未使用导入处理	控制仅用于类型的导入（import type）的输出 / 检查行为： - remove：移除未使用的类型导入； - preserve：保留导入语句； - error：未使用则报错。	remove	3.8
keyofStringsOnly	keyof 仅字符串	限制 keyof 操作符仅返回字符串类型（而非字符串 / 数字 / 符号，兼容旧代码）。	false	2.9
noImplicitUseStrict	禁止隐式严格模式	不在输出 JS 中添加 "use strict"（即使 alwaysStrict: true，用于兼容旧环境）。	false	1.7
noStrictGenericChecks	宽松泛型检查	关闭严格的泛型类型检查（兼容旧版 TS 中不严格的泛型匹配）。	false	2.3
out	旧版输出路径	（已废弃）同 outFile，仅用于兼容旧配置。	""	1.0
preserveValueImports	保留未使用值导入	保留未使用的非类型导入（避免 bundler 误删有副作用的导入）。	false	3.8
suppressExcessPropertyErrors	抑制多余属性错误	不报错对象字面量的多余属性（如 { a: 1, b: 2 } 赋值给 { a: number }）。	false	1.6
suppressImplicitAnyIndexErrors	抑制隐式 any 索引错误	不报错通过索引访问隐式 any 类型的属性（如 obj[key] 中 obj 为 any）。	false	1.8

8. 语言与环境（Language and Environment）

指定 TypeScript 支持的语言特性和目标运行时环境（如 ES 版本、DOM API）。

配置字段	中文含义	功能描述	默认值	生效版本
emitDecoratorMetadata	生成装饰器元数据	为装饰器声明生成设计时类型元数据（如 Reflect.getMetadata 可访问），需配合 experimentalDecorators: true。	false	1.5
experimentalDecorators	启用实验性装饰器	支持旧版实验性装饰器语法（如类装饰器、属性装饰器）。	false	1.5
jsx	JSX 处理模式	指定 JSX 代码的生成方式： - preserve：保留 JSX（用于 React 17+ 或自定义 transpiler）； - react：生成 React.createElement； - react-jsx：生成 jsx 函数（React 17+ 推荐）。	preserve	1.6
jsxFactory	JSX 工厂函数	指定生成 JSX 时使用的工厂函数（如 React.createElement 或 h，仅 jsx: react 时生效）。	"React.createElement"	1.6
jsxFragmentFactory	JSX 片段工厂函数	指定生成 JSX 片段（<>）时使用的函数（如 React.Fragment，仅 jsx: react 时生效）。	"React.Fragment"	4.0
jsxImportSource	JSX 导入源	指定导入 JSX 工厂函数的模块（如 import { jsx } from "preact/jsx-runtime"，仅 jsx: react-jsx* 时生效）。	"react"	4.1
lib	内置库声明	指定项目依赖的内置库声明文件（如 ES2020、DOM、WebWorker），控制可用的 API 类型。	随 target 自动匹配（如 target: ES2015 对应 ES2015、DOM 等）	1.5
libReplacement	库声明替换	替换默认的库声明文件（如用自定义 DOM 声明替换默认 lib.dom.d.ts）。	{}	5.0
moduleDetection	模块检测方式	控制如何检测文件是否为模块： - auto：自动检测（有 import/export 则为模块）； - force：强制所有文件视为模块； - legacy：旧版检测逻辑。	auto	4.7
noLib	禁用内置库	不包含任何内置库声明文件（包括默认 lib.d.ts），需手动提供所有类型声明。	false	1.5
reactNamespace	React 命名空间	指定调用 createElement 时的命名空间（如 React，仅 jsx: react 时生效）。	"React"	1.6
target	目标 JS 版本	指定生成 JS 的目标 ES 版本（如 ES5、ES2020、ESNext），影响语法降级程度。	ES3（旧版）/ ES5（新版）	1.0
useDefineForClassFields	类字段用 define	生成符合 ES 标准的类字段（使用 Object.defineProperty），而非赋值语法。	false（若 target < ES2022）；否则 true	3.7

9. 编译器诊断（Compiler Diagnostics）

控制编译器输出的诊断信息（如错误详情、文件列表），用于调试编译问题。

配置字段	中文含义	功能描述	默认值	生效版本
diagnostics	输出诊断信息	编译时输出详细的诊断信息（如类型检查时间、文件数量）。	false	2.0
explainFiles	解释文件包含原因	输出每个文件被纳入编译的原因（如通过 include、import 或 reference）。	false	2.0
extendedDiagnostics	扩展诊断信息	输出更详细的诊断信息（如内存使用、模块解析过程）。	false	2.3
generateCpuProfile	生成 CPU 分析报告	编译时生成 CPU 分析报告（.cpuprofile 文件），用于优化编译性能。	""（不生成）	3.0
generateTrace	生成编译追踪	生成编译过程的追踪文件（.trace），用于调试编译错误或性能问题。	""（不生成）	4.0
listEmittedFiles	列出输出文件	编译后列出所有生成的输出文件（JS/.d.ts/ 源映射）。	false	1.5
listFiles	列出输入文件	编译前列出所有纳入编译的输入文件（TS/JS/.d.ts）。	false	1.5
noCheck	禁止类型检查	完全跳过类型检查，仅执行文件转译（不推荐，用于快速编译）。	false	3.7
traceResolution	追踪模块解析	输出模块解析的详细过程（如查找路径、匹配结果），用于调试模块找不到问题。	false	1.6

10. 项目配置（Projects）

控制多项目引用（references）相关的编译行为，优化多项目构建效率。

配置字段	中文含义	功能描述	默认值	生效版本
composite	复合项目	启用复合项目模式（允许被其他项目引用），需配合 rootDir、outDir 使用。	false	3.0
disableReferencedProjectLoad	禁用引用项目加载	减少自动加载的引用项目数量，提升编辑性能（适合超大型多项目）。	false	3.0
disableSolutionSearching	禁用解决方案搜索	编辑时不参与多项目引用检查，提升大型解决方案的编辑性能。	false	3.0
disableSourceOfProjectReferenceRedirect	禁用源文件重定向	引用复合项目时，优先使用声明文件（.d.ts）而非源文件（TS）。	false	3.0
incremental	增量编译	生成 .tsbuildinfo 文件缓存编译状态，仅重新编译修改的文件，提升编译速度。	false	3.4
tsBuildInfoFile	增量编译文件路径	指定 .tsbuildinfo 文件的路径（存储增量编译缓存）。	./.tsbuildinfo	3.4

11. 输出格式化（Output Formatting）

控制编译器输出信息（如错误提示、日志）的格式，提升可读性。

配置字段	中文含义	功能描述	默认值	生效版本
noErrorTruncation	不截断错误信息	完整输出错误信息（默认会截断过长的错误描述）。	false	2.1
preserveWatchOutput	保留监听输出	tsc --watch 模式下，不清除之前的输出日志，便于查看历史编译结果。	false	2.7
pretty	美化输出格式	格式化编译器输出（如错误信息着色、缩进），提升可读性。	true（终端环境）；false（非终端）	2.5

12. 完整性检查（Completeness）

控制是否跳过类型声明文件的检查，优化编译速度（代价是可能遗漏声明文件错误）。

配置字段	中文含义	功能描述	默认值	生效版本
skipDefaultLibCheck	跳过默认库检查	跳过 TypeScript 自带的默认库声明文件（如 lib.es2015.d.ts）的类型检查。	false	2.0
skipLibCheck	跳过所有库检查	跳过所有 .d.ts 文件（包括默认库和第三方依赖）的类型检查，大幅提升编译速度。	false	2.0

13. 命令行与监听选项（Command Line & Watch Options）

控制 tsc 命令行（如 tsc --watch）的行为，优化开发体验。

配置字段	中文含义	功能描述	默认值	生效版本
assumeChangesOnlyAffectDirectDependencies	假设变更仅影响直接依赖	tsc --watch 模式下，仅重新编译变更文件的直接依赖，提升监听性能。	false	3.8
watchFile	文件监听方式	指定监听文件变化的方式（如 useFsEvents、dynamicPriorityPolling），适配不同系统。	随系统自动匹配	2.7
watchDirectory	目录监听方式	指定监听目录变化的方式（如 useFsEvents、fixedPollingInterval）。	随系统自动匹配	2.7
fallbackPolling	降级轮询方式	当文件系统监听不可用时，使用的轮询方式（如 interval、dynamicPriority）。	dynamicPriority	2.7
synchronousWatchDirectory	同步目录监听	同步处理目录监听事件（避免异步导致的竞态问题，适合特定场景）。	false	2.7
excludeDirectories	监听排除目录	tsc --watch 模式下，不监听的目录（如 node_modules）。	["node_modules", "bower_components"]	2.7
excludeFiles	监听排除文件	tsc --watch 模式下，不监听的文件（如日志文件）。	[]	2.7

14. 类型获取（typeAcquisition）

控制 TypeScript 自动获取 JavaScript 项目的类型声明文件（如从 @types 下载）。

配置字段	中文含义	功能描述	默认值	生效版本
enable	启用自动类型获取	自动为 JS 文件获取对应的 @types 类型声明（如为 jquery.js 获取 @types/jquery）。	false（JS 项目）；true（TS 项目）	2.1
include	包含类型获取文件	指定自动获取类型的文件 / 模式（如 ["jquery", "react"]）。	[]	2.1
exclude	排除类型获取文件	指定不自动获取类型的文件 / 模式（如 ["lodash"]）。	[]	2.1
disableFilenameBasedTypeAcquisition	禁用文件名类型获取	不根据文件名自动匹配类型声明（如 vue.js 不自动获取 @types/vue）。	false	3.3

四、常见场景配置示例

1. 现代 Node.js 项目（ESM/CJS 兼容）

{
  "compilerOptions": {
    "target": "ES2022",                // 目标 ES 版本
    "module": "nodenext",              // 适配现代 Node.js 模块系统
    "moduleResolution": "nodenext",    // 匹配模块系统的解析策略
    "outDir": "./dist",                // 输出目录
    "rootDir": "./src",                // 源代码根目录
    "strict": true,                    // 开启所有严格检查
    "esModuleInterop": true,           // ESM 与 CJS 互操作
    "skipLibCheck": true,              // 跳过库声明检查（提升速度）
    "forceConsistentCasingInFileNames": true, // 强制文件名大小写一致
    "resolveJsonModule": true          // 支持导入 JSON
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "src/**/*.test.ts"]
}

2. React 前端项目（Vite/Rollup bundler）

{
  "compilerOptions": {
    "target": "ES2020",                // 适配现代浏览器
    "module": "esnext",                // 保留 ESM 语法（bundler 处理）
    "moduleResolution": "bundler",     // 适配 bundler 解析策略
    "jsx": "react-jsx",                // React 17+ JSX 模式
    "jsxImportSource": "react",        // JSX 工厂函数导入源
    "outDir": "./dist",                // 输出目录
    "rootDir": "./src",                // 源代码根目录
    "strict": true,                    // 开启严格检查
    "skipLibCheck": true,              // 跳过库声明检查
    "allowArbitraryExtensions": true,  // 允许导入 CSS/SVG 等文件
    "resolveJsonModule": true,         // 支持 JSON 导入
    "isolatedModules": true            // 确保文件可独立转译（bundler 要求）
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

3. 多项目引用（Monorepo）

// 根项目 tsconfig.json
{
  "files": [],                         // 根项目无源代码
  "references": [                     // 引用子项目
    { "path": "./packages/utils" },    // 工具库子项目
    { "path": "./packages/components"  // UI组件子项目
  ]
}
// 子项目 packages/utils/tsconfig.json
{
  "compilerOptions": {
    "composite": true,                 // 启用复合项目（允许被引用）
    "target": "ES2020",
    "module": "esnext",
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,               // 生成类型声明（供其他项目使用）
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

五、总结

TSConfig 配置覆盖了 TypeScript 项目的全生命周期需求，从文件范围控制到类型检查、模块处理、输出优化，再到多项目管理。核心建议：

1. 优先开启 strict: true：生产环境项目建议开启所有严格检查，减少运行时错误；

2. 适配目标运行时：根据项目场景（Node.js/ 浏览器 /bundler）选择 module、moduleResolution、target 等核心配置；

3. 优化编译速度：大型项目可开启 incremental、skipLibCheck、composite 等配置，提升编译和编辑效率；

4. 多项目拆分：复杂项目通过 references 拆分为子项目，实现隔离编译和依赖复用。

如需更细节的配置说明，可参考 TypeScript 官方文档：www.typescriptlang.org/tsconfig/