---

前言

tsconfig.json 是 TypeScript 項目的配置文件，用于指定編譯選項和文件包含規則。以下是所有主要配置參數的中文詳解：

---

核心配置

compilerOptions (編譯器選項)

基本選項

• target: 指定編譯后的 JavaScript 目標版本 (如"esnext", “es5”, “es6”, “es2015”, “es2020” 等)
• module: 指定模塊系統 (如 “commonjs”, “amd”, “es2015”, “esnext” 等)
• lib: 指定要包含的庫文件聲明 (如 [ “esnext”, “es5”, “es6”, “dom”])
• allowJs: 允許編譯 JavaScript 文件 (true/false)
• checkJs: 在 JavaScript 文件中報告錯誤 (true/false)
• jsx: 指定 JSX 代碼生成方式 (“preserve”, “react”, “react-jsx”, “react-jsxdev” 等)
• declaration: 生成對應的 .d.ts 聲明文件 (true/false)
• declarationMap: 為聲明文件生成 sourcemap (true/false)
• sourceMap: 生成對應的 .map 文件 (true/false)
• outFile: 將所有輸出合并為一個文件 (僅適用于 module 為 “amd” 或 “system”)
• outDir: 指定輸出目錄
• rootDir: 指定輸入文件的根目錄
• composite: 啟用項目編譯 (true/false)
• incremental: 啟用增量編譯 (true/false)
• tsBuildInfoFile: 指定增量編譯信息文件的路徑

嚴格類型檢查選項

• strict: 啟用所有嚴格類型檢查選項 (true/false)
• noImplicitAny: 禁止隱式 any 類型 (true/false)
• strictNullChecks: 啟用嚴格的 null 檢查 (true/false)
• strictFunctionTypes: 啟用嚴格的函數類型檢查 (true/false)
• strictBindCallApply: 對 bind, call, apply 方法進行嚴格檢查 (true/false)
• strictPropertyInitialization: 確保類的屬性已初始化 (true/false)
• noImplicitThis: 禁止隱式 any 類型的 this (true/false)
• alwaysStrict: 以嚴格模式解析并為每個源文件生成 “use strict” (true/false)

模塊解析選項

• moduleResolution: 指定模塊解析策略 (“node” 或 “classic”)
• baseUrl: 解析非相對模塊名的基準目錄
• paths: 設置模塊名到基于 baseUrl 的路徑映射
• rootDirs: 將多個目錄合并為一個虛擬目錄
• typeRoots: 指定類型定義文件的目錄列表
• types: 指定要包含的類型聲明文件包
• allowUmdGlobalAccess: 允許從模塊訪問 UMD 全局變量 (true/false)
• resolveJsonModule: 允許導入 JSON 模塊 (true/false)
• preserveSymlinks: 不解析符號鏈接的真實路徑 (true/false)

Source Map 選項

• sourceRoot: 指定調試器應該定位的 TypeScript 文件位置
• mapRoot: 指定調試器應該定位的 map 文件位置
• inlineSourceMap: 將 sourcemap 嵌入到生成的 JS 文件中 (true/false)
• inlineSources: 將源代碼與 sourcemaps 一起嵌入到單個文件中 (true/false)

實驗性選項

• experimentalDecorators: 啟用實驗性裝飾器支持 (true/false)
• emitDecoratorMetadata: 為裝飾器提供元數據支持 (true/false)

其他選項

• importHelpers: 從 tslib 導入輔助工具函數 (true/false)
• downlevelIteration: 為迭代器提供更準確的降級支持 (true/false)
• isolatedModules: 確保每個文件都可以安全地獨立編譯 (true/false)
• allowSyntheticDefaultImports: 允許從沒有默認導出的模塊進行默認導入 (true/false)
• esModuleInterop: 啟用更兼容的 CommonJS/AMD/UMD 模塊導入導出 (true/false)
• forceConsistentCasingInFileNames: 強制文件名大小寫一致 (true/false)
• skipLibCheck: 跳過聲明文件的類型檢查 (true/false)
• noEmit: 不生成輸出文件 (true/false)
• noEmitOnError: 當有錯誤時不生成輸出文件 (true/false)
• noEmitHelpers: 不生成輔助函數，需手動引入 (true/false)
• noImplicitReturns: 函數中所有代碼路徑必須返回值 (true/false)
• noFallthroughCasesInSwitch: 防止 switch 語句貫穿 (true/false)
• noUnusedLocals: 報告未使用的局部變量 (true/false)
• noUnusedParameters: 報告未使用的函數參數 (true/false)\
• noUncheckedIndexedAccess: 在索引訪問中包含 undefined (true/false)
• noPropertyAccessFromIndexSignature: 禁止通過點符號訪問索引簽名屬性 (true/false)
• removeComments: 移除注釋 (true/false)
• preserveConstEnums: 保留 const enum 聲明 (true/false)
• newLine: 指定換行符 (“crlf” 或 “lf”)
• useDefineForClassFields: 使用現代類字段定義方式 (true/false)
• keyofStringsOnly: 使 keyof 僅返回字符串 (true/false)
• suppressExcessPropertyErrors: 禁止額外屬性檢查 (true/false)
• suppressImplicitAnyIndexErrors: 禁止隱式索引錯誤 (true/false)
• noErrorTruncation: 不截短錯誤消息 (true/false)
• charset: 已棄用，指定輸入文件的字符集
• emitBOM: 在輸出文件開頭寫入 BOM (true/false)
• locale: 指定錯誤消息的語言環境 (如 “en-us”, “zh-cn”)
• disableSizeLimit: 禁用 JavaScript 項目大小限制 (true/false)
• listFiles: 打印編譯的文件名 (true/false)
• listEmittedFiles: 打印輸出的文件名 (true/false)
• traceResolution: 打印模塊解析日志 (true/false)
• diagnostics: 打印診斷信息 (true/false)
• extendedDiagnostics: 打印擴展診斷信息 (true/false)
• generateCpuProfile: 生成 CPU 分析文
• plugins: 指定要運行的編譯器插件列表

文件包含/排除選項

• files: 指定要包含的文件列表
• include: 指定要包含的文件模式
• exclude: 指定要排除的文件模式
• extends: 繼承另一個 tsconfig.json 文件的配置
• references: 項目引用配置
• compileOnSave: 指示 IDE 在保存時編譯 (true/false)
• typeAcquisition: 指定自動類型獲取的選項

詳細用法示例

{"compilerOptions": {"target": "es6","module": "commonjs","strict": true,"esModuleInterop": true,"skipLibCheck": true,"forceConsistentCasingInFileNames": true,"outDir": "./dist","rootDir": "./src","baseUrl": "./","paths": {"@utils/*": ["src/utils/*"]}},"include": ["src/**/*"],"exclude": ["node_modules", "**/*.spec.ts"]
}

最佳實踐建議

• 對于新項目，建議啟用 strict: true 以獲得最嚴格的類型檢查
• 使用 include 和 exclude 替代 files 來管理文件包含
• 對于大型項目，考慮使用項目引用 (references) 來拆分代碼庫
• 使用 extends 繼承共享配置，避免重復配置
• 對于 Node.js 項目，target 設為 es2018 或更高版本可以獲得更好的性能
• 啟用 esModuleInterop 可以簡化 CommonJS 模塊的導入