tsconfig.json常用配置详解
1. 创建基础配置
bash
npx tsc --init # 生成默认 tsconfig.json
2. 主要配置分类
2.1 编译目标相关
json
{
"compilerOptions": {
/* 语言和环境 */
"target": "es2020", // 编译目标 ES 版本
// 可选值: "es3", "es5", "es6"/"es2015", "es2020", "es2022", "esnext"
"lib": ["es2020", "dom"], // 要包含的库文件声明
// 常用: ["es6", "dom"] / ["es2020", "dom", "dom.iterable"]
"module": "commonjs", // 模块系统
// 可选值: "commonjs", "amd", "umd", "system", "es6"/"es2015", "es2020", "esnext"
"rootDir": "./src", // 源文件根目录
"outDir": "./dist", // 输出目录
"declaration": true, // 生成 .d.ts 声明文件
"declarationDir": "./types", // 声明文件输出目录
"sourceMap": true, // 生成 source map
"sourceRoot": "./src", // source map 中源文件根目录
/* 模块解析 */
"moduleResolution": "node", // 模块解析策略
"baseUrl": "./", // 解析非相对模块的基础目录
"paths": { // 路径别名映射
"@/*": ["src/*"],
"@utils/*": ["src/utils/*"]
},
"resolveJsonModule": true, // 允许导入 JSON 文件
"allowSyntheticDefaultImports": true // 允许默认导入
}
}
2.2 严格模式相关
json
{
"compilerOptions": {
/* 严格类型检查选项 */
"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 语句穿透
"noUncheckedIndexedAccess": true, // 索引访问时包含 undefined
"exactOptionalPropertyTypes": true // 精确的可选属性类型
}
}
2.3 实验性/高级功能
json
{
"compilerOptions": {
/* 实验性选项 */
"experimentalDecorators": true, // 启用装饰器
"emitDecoratorMetadata": true, // 为装饰器生成元数据
/* 高级选项 */
"allowUnreachableCode": false, // 不允许不可达代码
"allowUnusedLabels": false, // 不允许未使用标签
"noImplicitOverride": true, // 要求显式 override 修饰符
/* 模块互操作 */
"esModuleInterop": true, // 改进 CommonJS/ES6 模块互操作
"forceConsistentCasingInFileNames": true, // 强制文件名大小写一致
/* 编辑器集成 */
"skipLibCheck": true, // 跳过库类型检查（加快编译）
"isolatedModules": true // 确保每个文件可独立编译
}
}
3. 文件包含/排除
json
{
"include": [
"src/**/*", // 包含 src 目录下所有文件
"types/**/*.d.ts", // 包含自定义类型声明
"test/**/*.ts" // 包含测试文件
],
"exclude": [
"node_modules", // 排除 node_modules
"dist", // 排除输出目录
"**/*.test.ts", // 排除测试文件（如果需要）
"**/*.spec.ts" // 排除测试文件
],
"files": [ // 明确指定要编译的文件（优先级高于 include）
"src/core.ts",
"src/main.ts"
]
}
4. 扩展配置
json
{
"extends": "./tsconfig.base.json", // 继承基础配置
"references": [ // 项目引用（用于 monorepo）
{ "path": "./shared" },
{ "path": "./packages/core" }
]
}
-
前端项目（React/Vue）
json
{
"compilerOptions": {
"target": "es2015",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": true,
"module": "esnext",
"moduleResolution": "node",
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true, // 与打包工具配合时设为 true
"jsx": "react-jsx" // React 17+ JSX 转换
},
"include": ["src"]
}
-
检查配置有效性
bash
npx tsc --showConfig # 显示最终配置
npx tsc --dry-run # 检查而不编译
npx tsc --noEmit # 只进行类型检查
-
watch 模式
bash
tsc --watch # 监听文件变化
tsc --project tsconfig.dev.json --watch # 指定配置文件
compilerOptions
即编译选项，主要告诉TS编译器：
- 如何编译：目标语言版本，模块系统等
- 编译什么：文件包含、排除规则
- 编译到哪里: 输出目录和格式
- 编译规则：类型检查严格程度
目标相关
{
"compilerOptions": {
"target": "es2020", // 输出什么版本的 JS
"module": "commonjs", // 使用什么模块系统
"lib": ["es2020", "dom"] // 包含哪些内置 API 定义
}
输出控制
{
"compilerOptions": {
"outDir": "./dist", // 输出目录
"outFile": "./bundle.js", // 打包成单个文件
"declaration": true, // 生成 .d.ts 声明文件
"sourceMap": true // 生成 source map
}
}
类型检查
{
"compilerOptions": {
"strict": true, // 启用所有严格检查
"noImplicitAny": true, // 禁止隐式 any
"strictNullChecks": true // 严格空值检查
}
}
模块解析
baseUrl 定义了非相对模块导入时的基础查找路径。
{
"compilerOptions": {
"baseUrl": "./", // 模块解析基础路径
"paths": { // 路径别名
"@/*": ["src/*"]
},
"moduleResolution": "node" // 使用 Node.js 解析策略
}
}
编译选项作用的时机
编译流程图解
源代码 (.ts)
↓
TypeScript 编译器 (tsc)
↓ (根据 compilerOptions 处理)
编译过程
├── 类型检查 (type checking)
├── 语法转换 (transpile)
├── 模块解析 (module resolution)
└── 代码生成 (code generation)
↓
输出文件 (.js, .d.ts, .map)
重要选项详解
1. strict 家族
json
{
"compilerOptions": {
"strict": true, // 相当于同时开启以下所有：
// "noImplicitAny": true,
// "strictNullChecks": true,
// "strictFunctionTypes": true,
// "strictBindCallApply": true,
// "strictPropertyInitialization": true,
// "noImplicitThis": true,
// "alwaysStrict": true
}
}
2. 模块相关
json
{
"compilerOptions": {
"esModuleInterop": true, // 解决 CommonJS/ES6 互操作
"allowSyntheticDefaultImports": true, // 允许默认导入
"resolveJsonModule": true // 允许导入 JSON
}
}
3. 性能优化
json
{
"compilerOptions": {
"skipLibCheck": true, // 跳过库文件检查（加快编译）
"incremental": true, // 增量编译
"tsBuildInfoFile": ".tsbuildinfo" // 增量编译信息文件
}
}
调试技巧：
bash
# 查看编译过程
tsc --listFiles # 列出所有编译文件
tsc --diagnostics # 输出诊断信息
tsc --extendedDiagnostics # 详细诊断信息
