一、配置文件基础结构
| 配置项 | 作用 | 示例值 | 说明 |
|---|
include | 指定编译文件范围 | ["src/**/*.ts"] | 支持 glob 模式（** 任意目录，* 任意文件） |
exclude | 排除编译目录 | ["node_modules", "dist"] | 默认排除 node_modules 等目录 |
extends | 继承其他配置文件 | "extends": "./configs/base" | 复用基础配置，减少重复 |
files | 显式指定编译文件列表 | ["core.ts", "utils.ts"] | 仅需编译少量文件时使用 |
二、核心编译选项（compilerOptions）
1. 目标与环境配置
| 选项 | 作用 | 常用值 | 场景说明 |
|---|
target | 编译输出的 JS 版本 | ES2020、ESNext | 现代项目选 ESNext，兼容旧浏览器选 ES5 |
lib | 指定运行时库支持 | ["ES2020", "DOM"] | 缺省时根据 target 自动选择，需 DOM 操作时显式添加 |
module | 设置模块化规范 | ESNext（前端）、CommonJS（Node） | 前端项目推荐 ESNext 以支持 Tree Shaking |
2. 输入输出控制
| 选项 | 作用 | 示例值 | 注意事项 |
|---|
outDir | 编译输出目录 | "dist" | 输出目录自动创建 |
outFile | 合并为单一文件 | "dist/app.js" | 需配合 module: "AMD" 或 System |
rootDir | 源码根目录 | "src" | 控制输出目录结构 |
3. 严格类型检查
| 选项 | 作用 | 推荐值 | 触发错误示例 |
|---|
strict | 启用所有严格检查（总开关） | true | 等效开启以下所有选项 |
noImplicitAny | 禁止隐式 any 类型 | true | function fn(a) {} → 参数 a 需显式类型 |
strictNullChecks | 强制 null/undefined 检查 | true | const el = document.getElementById("box"); el.value → 需 el?.value |
strictFunctionTypes | 严格校验函数参数类型 | true | 防止逆变参数错误 |
三、工程化进阶配置
1. 路径别名（Path Mapping）
{"compilerOptions": {"baseUrl": "./","paths": {"@components/*": ["src/components/*"],"@utils/*": ["src/libs/utils/*"]}}
}
- 作用：避免
../../../ 路径混乱，提升可维护性 - 需配合构建工具：Webpack/Vite 需同步配置别名解析
2. JavaScript 兼容
| 选项 | 作用 | 场景 |
|---|
allowJs | 允许编译 .js 文件 | 旧项目迁移至 TS |
checkJs | 对 .js 文件进行类型检查 | 渐进增强 JS 代码安全性 |
3. 源码映射与调试
{"sourceMap": true, // 生成 .map 文件"inlineSources": true, // 将源码嵌入 SourceMap"declaration": true, // 生成 .d.ts 类型声明"declarationMap": true // 类型声明 SourceMap
}
四、优化与高级特性
1. 增量编译（Incremental Builds）
{"incremental": true,"tsBuildInfoFile": "./build/.tsbuildinfo"
}
- 作用：缓存编译信息，大幅提升后续编译速度
- 文件位置：默认存储在
node_modules/.cache 中
2. 类型检查优化
| 选项 | 作用 |
|---|
skipLibCheck | 跳过第三方库类型检查（提升编译速度） |
esModuleInterop | 改善 CommonJS/ESM 互操作性 |
3. 装饰器与元数据
{"experimentalDecorators": true, // 启用装饰器"emitDecoratorMetadata": true // 生成元数据（NestJS 必需）
}
- 应用场景：类验证、依赖注入框架（如 NestJS）
五、配置示例与最佳实践
React + Vite 配置
{"compilerOptions": {"target": "ESNext","module": "ESNext","lib": ["DOM", "ESNext"],"strict": true,"jsx": "react-jsx", // React 17+ JSX 转换"baseUrl": "src","paths": {"@/*": ["./*"]},"skipLibCheck": true},"include": ["src"]
}
Node.js 服务端配置
{"compilerOptions": {"target": "ES2020","module": "CommonJS","outDir": "dist","rootDir": "src","strict": true,"esModuleInterop": true,"resolveJsonModule": true // 允许导入 JSON}
}
💡 最佳实践总结：
- 开启
strict 模式：保障类型安全底线； - 按环境选
target 和 module：前端用 ESNext，Node 用 CommonJS； - 路径别名 +
baseUrl：提升项目可维护性； - 增量编译 +
skipLibCheck：优化大型项目构建速度。
完整选项参考 TypeScript 官方文档。
