TSConfig 是 TypeScript 项目的核心配置文件，通过 tsconfig.json 可定制编译行为、类型检查策略和模块解析规则。本文将系统解析 TSConfig 的五大配置类别，重点标注 TypeScript 5.x 新增特性，并提供三大场景的配置模板，帮助开发者快速搭建符合项目需求的 TypeScript 环境。
一、基础配置
基础配置决定 TypeScript 编译的输出格式、目标环境和代码结构，是项目构建的基础框架。
| 配置项 | 作用 | 取值范围 | 默认值 | 示例 |
|---|---|---|---|---|
| target | 指定编译后的 JavaScript 版本 | ES3、ES5、ES2015-ES2022、ESNext、DOM、ES2023 等 | ES3 | "target": "ES2020" |
| module | 指定模块系统 | CommonJS、AMD、UMD、ES6/ES2015、ESNext、NodeNext、System | CommonJS | "module": "ESNext" |
| lib | 指定编译时依赖的库文件 | ES5、ES6、DOM、WebWorker、ES2020.Promise 等 | 自动推断 | "lib": [[2](ES2020)][[3](DOM)] |
| outDir | 指定编译输出目录 | 相对路径或绝对路径 | 无 | "outDir": "./dist" |
| rootDir | 指定源代码根目录 | 相对路径或绝对路径 | 包含入口文件的目录 | "rootDir": "./src" |
注意：target 和 module 的取值需匹配项目运行环境。例如，前端项目通常使用 "ESNext" 配合打包工具，而 Node.js 项目可指定 "NodeNext" 以支持最新的 Node.js 模块系统。
二、类型检查
类型检查配置控制 TypeScript 的类型严格程度，直接影响代码质量和开发体验。strict 选项是类型检查的总开关，启用后会强制开启一系列严格检查规则。
| 配置项 | 作用 | 取值范围 | 默认值 | 示例 |
|---|---|---|---|---|
| strict | 启用所有严格类型检查选项（推荐生产环境开启） | boolean | false | "strict": true |
| strictNullChecks | 禁止 null/undefined 隐式赋值给非空类型 |
boolean | false | "strictNullChecks": true |
| noImplicitAny | 禁止隐式 any 类型（未声明类型的变量/参数会报错） |
boolean | false | "noImplicitAny": true |
| strictFunctionTypes | 严格检查函数参数和返回值类型的协变性与逆变性 | boolean | false | "strictFunctionTypes": true |
| strictBindCallApply | 严格检查 bind/call/apply 方法的参数类型 |
boolean | false | "strictBindCallApply": true |
最佳实践：新项目建议直接开启 "strict": true，通过严格的类型检查提前规避潜在错误。老项目可逐步开启子选项（如先启用 noImplicitAny 和 strictNullChecks），降低迁移成本。
三、模块解析
模块解析配置控制 TypeScript 如何查找和解析模块，尤其影响路径别名、第三方库引入和跨项目依赖管理。TypeScript 5.x 新增 bundler 解析策略，专门适配 Vite、Webpack 等打包工具的模块解析逻辑。
| 配置项 | 作用 | 取值范围 | 默认值 | 示例 |
|---|---|---|---|---|
| moduleResolution | 指定模块解析策略 | classic、node、node16、nodenext、bundler（TS 5.x 新增） |
node |
"moduleResolution": "bundler"（前端项目推荐） |
| baseUrl | 设置模块解析的基础路径，用于简化相对路径导入 | 相对路径或绝对路径 | 无 | "baseUrl": "./src" |
| paths | 配置路径别名（需配合 baseUrl 使用） |
对象（键为别名，值为路径数组） | 无 | "paths": { "@/*": [[19](components/*)] } |
| allowImportingTsExtensions | 允许导入 .ts/.tsx 文件时保留扩展名（TS 5.x 新增，适配打包工具） |
boolean | false | "allowImportingTsExtensions": true |
TypeScript 5.x 新特性：moduleResolution: "bundler" 解决了传统 node 解析策略与打包工具（如 Vite）路径解析规则不一致的问题，避免手动配置 paths 或安装 @types/node 的繁琐步骤。
四、高级特性
高级特性配置用于启用实验性功能或特定场景的语法支持，如装饰器、元数据发射等，需根据项目框架和需求选择性开启。
| 配置项 | 作用 | 取值范围 | 默认值 | 示例 |
|---|---|---|---|---|
| experimentalDecorators | 启用装饰器语法（如 React 类组件、NestJS 装饰器） | boolean | false | "experimentalDecorators": true |
| emitDecoratorMetadata | 为装饰器发射元数据（需配合 reflect-metadata 库使用） |
boolean | false | "emitDecoratorMetadata": true |
| verbatimModuleSyntax | 严格保留模块语法（禁止自动转换 import 为 require） |
boolean | false | "verbatimModuleSyntax": true |
| useDefineForClassFields | 遵循 ES 标准，使用 defineProperty 定义类字段（TS 3.7+） |
boolean | false | "useDefineForClassFields": true |
五、其他选项
其他选项用于控制文件包含/排除规则、配置继承等，帮助管理复杂项目的多环境配置。TypeScript 5.x 支持通过 extends 继承多个配置文件，实现配置复用和分层管理。
| 配置项 | 作用 | 取值范围 | 默认值 | 示例 |
|---|---|---|---|---|
| include | 指定需要编译的文件/目录（支持 glob 模式） | 字符串数组 | [[20](**/*)] |
"include": [[17](src/**/*)][[21](types/**/*)] |
| exclude | 指定排除编译的文件/目录（优先级低于 include） |
字符串数组 | [[22](node_modules)] |
"exclude": [[22](node_modules)][[23](dist)][[24](**/*.test.ts)] |
| extends | 继承其他配置文件（TS 5.x 支持多配置继承） | 字符串或字符串数组 | 无 | "extends": [[25](@tsconfig/react-native/tsconfig.json)][[26](./base.json)] |
| files | 指定具体编译文件（优先级高于 include，适合小型项目） |
字符串数组 | 无 | "files": [[27](src/index.ts)][[28](src/app.tsx)] |
TypeScript 5.x 新特性：extends 支持多配置继承，例如同时继承社区标准配置（如 @tsconfig/react-native）和项目自定义配置，实现 "基础配置+场景配置" 的分层管理模式。
六、场景配置模板
以下提供三大主流场景的 TSConfig 模板，可直接复制使用或根据项目需求调整。
1. React 前端项目（适配 Vite/Webpack）
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler", // TS 5.x 新特性，适配打包工具
"lib": [[2](ES2020)][[3](DOM)][[4](DOM.Iterable)],
"jsx": "react-jsx", // 支持 React 17+ JSX 转换
"strict": true,
"allowImportingTsExtensions": true, // 允许导入 .tsx 扩展名
"baseUrl": ".",
"paths": { "@/*": [[29](src/*)] }, // 路径别名
"outDir": "./dist",
"rootDir": "./src",
"skipLibCheck": true // 跳过第三方库类型检查，提升编译速度
},
"include": [[17](src/**/*)],
"exclude": [[22](node_modules)][[23](dist)]
}2. Node.js 后端项目（Node.js 18+）
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext", // 匹配 Node.js 原生模块系统
"moduleResolution": "NodeNext",
"lib": [[30](ES2022)],
"strict": true,
"outDir": "./dist",
"rootDir": "./src",
"resolveJsonModule": true, // 允许导入 JSON 文件
"esModuleInterop": true, // 兼容 CommonJS 和 ES 模块
"forceConsistentCasingInFileNames": true
},
"include": [[17](src/**/*)],
"exclude": [[22](node_modules)][[23](dist)][[24](**/*.test.ts)]
}3. TypeScript 库项目（发布到 npm）
{
"compilerOptions": {
"target": "ES2020", // 兼容主流环境
"module": "ESNext", // 输出 ES 模块
"moduleResolution": "node",
"lib": [[2](ES2020)],
"strict": true,
"declaration": true, // 生成类型声明文件
"declarationDir": "./types", // 类型声明输出目录
"outDir": "./dist",
"rootDir": "./src",
"verbatimModuleSyntax": true, // 严格保留模块语法
"noUnusedLocals": true, // 禁止未使用的变量
"noUnusedParameters": true // 禁止未使用的函数参数
},
"include": [[17](src/**/*)],
"exclude": [[22](node_modules)][[23](dist)][[24](**/*.test.ts)],
"extends": [[31](@tsconfig/strictest/tsconfig.json)] // 继承严格配置
}通过合理配置 TSConfig，可充分发挥 TypeScript 的类型优势，同时兼顾项目的构建效率和兼容性。建议结合项目框架（如 React、Node.js）、打包工具（如 Vite、Webpack）和运行环境选择合适的配置模板，并逐步优化严格检查规则，实现 "类型安全" 与 "开发效率" 的平衡。