一、配置文件基礎(chǔ)結(jié)構(gòu)
| ??配置項?? | ??作用?? | ??示例值?? | ??說明?? |
|---|
include | 指定編譯文件范圍 | ["src/**/*.ts"] | 支持 glob 模式（** 任意目錄，* 任意文件） |
exclude | 排除編譯目錄 | ["node_modules", "dist"] | 默認(rèn)排除 node_modules 等目錄 |
extends | 繼承其他配置文件 | "extends": "./configs/base" | 復(fù)用基礎(chǔ)配置，減少重復(fù) |
files | 顯式指定編譯文件列表 | ["core.ts", "utils.ts"] | 僅需編譯少量文件時使用 |
二、核心編譯選項（compilerOptions）
1. ??目標(biāo)與環(huán)境配置??
| ??選項?? | ??作用?? | ??常用值?? | ??場景說明?? |
|---|
target | 編譯輸出的 JS 版本 | ES2020、ESNext | 現(xiàn)代項目選 ESNext，兼容舊瀏覽器選 ES5 |
lib | 指定運(yùn)行時庫支持 | ["ES2020", "DOM"] | 缺省時根據(jù) target 自動選擇，需 DOM 操作時顯式添加 |
module | 設(shè)置模塊化規(guī)范 | ESNext（前端）、CommonJS（Node） | 前端項目推薦 ESNext 以支持 Tree Shaking |
2. ??輸入輸出控制??
| ??選項?? | ??作用?? | ??示例值?? | ??注意事項?? |
|---|
outDir | 編譯輸出目錄 | "dist" | 輸出目錄自動創(chuàng)建 |
outFile | 合并為單一文件 | "dist/app.js" | 需配合 module: "AMD" 或 System |
rootDir | 源碼根目錄 | "src" | 控制輸出目錄結(jié)構(gòu) |
3. ??嚴(yán)格類型檢查??
| ??選項?? | ??作用?? | ??推薦值?? | ??觸發(fā)錯誤示例?? |
|---|
strict | 啟用所有嚴(yán)格檢查（總開關(guān)） | true | 等效開啟以下所有選項 |
noImplicitAny | 禁止隱式 any 類型 | true | function fn(a) {} → 參數(shù) a 需顯式類型 |
strictNullChecks | 強(qiáng)制 null/undefined 檢查 | true | const el = document.getElementById("box"); el.value → 需 el?.value |
strictFunctionTypes | 嚴(yán)格校驗函數(shù)參數(shù)類型 | true | 防止逆變參數(shù)錯誤 |
三、工程化進(jìn)階配置
1. ??路徑別名（Path Mapping）??
{"compilerOptions": {"baseUrl": "./","paths": {"@components/*": ["src/components/*"],"@utils/*": ["src/libs/utils/*"]}}
}
- ??作用??：避免
../../../ 路徑混亂，提升可維護(hù)性 - ??需配合構(gòu)建工具??：Webpack/Vite 需同步配置別名解析
2. ??JavaScript 兼容??
| ??選項?? | ??作用?? | ??場景?? |
|---|
allowJs | 允許編譯 .js 文件 | 舊項目遷移至 TS |
checkJs | 對 .js 文件進(jìn)行類型檢查 | 漸進(jìn)增強(qiáng) JS 代碼安全性 |
3. ??源碼映射與調(diào)試??
{"sourceMap": true, // 生成 .map 文件"inlineSources": true, // 將源碼嵌入 SourceMap"declaration": true, // 生成 .d.ts 類型聲明"declarationMap": true // 類型聲明 SourceMap
}
- ??調(diào)試支持??：瀏覽器中直接調(diào)試 TS 源碼
四、優(yōu)化與高級特性
1. ??增量編譯（Incremental Builds）??
{"incremental": true,"tsBuildInfoFile": "./build/.tsbuildinfo"
}
- ??作用??：緩存編譯信息，大幅提升后續(xù)編譯速度
- ??文件位置??：默認(rèn)存儲在
node_modules/.cache 中
2. ??類型檢查優(yōu)化??
| ??選項?? | ??作用?? |
|---|
skipLibCheck | 跳過第三方庫類型檢查（提升編譯速度） |
esModuleInterop | 改善 CommonJS/ESM 互操作性 |
3. ??裝飾器與元數(shù)據(jù)??
{"experimentalDecorators": true, // 啟用裝飾器"emitDecoratorMetadata": true // 生成元數(shù)據(jù)（NestJS 必需）
}
- ??應(yīng)用場景??：類驗證、依賴注入框架（如 NestJS）
五、配置示例與最佳實(shí)踐
??React + Vite 配置??
{"compilerOptions": {"target": "ESNext","module": "ESNext","lib": ["DOM", "ESNext"],"strict": true,"jsx": "react-jsx", // React 17+ JSX 轉(zhuǎn)換"baseUrl": "src","paths": {"@/*": ["./*"]},"skipLibCheck": true},"include": ["src"]
}
??Node.js 服務(wù)端配置??
{"compilerOptions": {"target": "ES2020","module": "CommonJS","outDir": "dist","rootDir": "src","strict": true,"esModuleInterop": true,"resolveJsonModule": true // 允許導(dǎo)入 JSON}
}
💡 ??最佳實(shí)踐總結(jié)??：
- ??開啟
strict 模式??：保障類型安全底線； - ??按環(huán)境選
target 和 module??：前端用 ESNext，Node 用 CommonJS； - ??路徑別名 +
baseUrl??：提升項目可維護(hù)性； - ??增量編譯 +
skipLibCheck??：優(yōu)化大型項目構(gòu)建速度。
完整選項參考 TypeScript 官方文檔。
