15. tsconfig.json 配置详解

15. tsconfig.json 配置详解1. 概述tsconfig.json是 TypeScript 项目的核心配置文件用于指定编译选项、文件包含/排除规则、项目引用等。正确配置 tsconfig.json 是 TypeScript 项目工程化的基础。┌─────────────────────────────────────────────────────────────┐ │ tsconfig.json 配置体系 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 顶层配置 │ │ ├── compilerOptions编译选项 │ │ ├── include包含的文件模式 │ │ ├── exclude排除的文件模式 │ │ ├── files显式指定的文件列表 │ │ ├──extends继承其他配置文件 │ │ ├── references项目引用 │ │ └── watchOptions监听选项 │ │ │ │ 编译选项分类 │ │ ├── 基本选项target、module、lib │ │ ├── 严格模式strict、noImplicitAny 等 │ │ ├── 模块解析moduleResolution、paths、baseUrl │ │ ├── 输出控制outDir、rootDir、declaration │ │ ├── 互操作性esModuleInterop、allowSyntheticDefaultImports│ │ ├── 类型检查noUnusedLocals、noUnusedParameters │ │ └── 源映射sourceMap、inlineSourceMap │ │ │ └─────────────────────────────────────────────────────────────┘2. 生成 tsconfig.json# 生成默认配置tsc--init# 生成带注释的配置文件tsc--init--showConfig# 使用特定模板tsc--init--targetes2020--modulecommonjs3. 顶层配置3.1 基础结构{compilerOptions:{// 编译选项},include:[src/**/*],exclude:[node_modules,dist],files:[],extends:./base.json,references:[],watchOptions:{}}3.2 include 和 exclude{// 包含所有 src 下的 TypeScript 文件include:[src/**/*],// 排除 node_modules 和 dist 目录exclude:[node_modules,dist,**/*.test.ts],// 显式指定文件优先级最高files:[src/index.ts,src/types/global.d.ts]}3.3 extends 继承// base.json{compilerOptions:{strict:true,target:ES2020,module:ESNext}}// tsconfig.json{extends:./base.json,compilerOptions:{outDir:./dist,rootDir:./src},include:[src/**/*]}3.4 watchOptions 监听选项{watchOptions:{// 监听文件变化的方式watchFile:useFsEvents,watchDirectory:useFsEvents,fallbackPolling:dynamicPriority,synchronousWatchDirectory:true,excludeDirectories:[**/node_modules,**/dist]}}4. 基本编译选项4.1 target目标版本{compilerOptions:{// 编译目标 JS 版本// 可选ES3、ES5、ES6/ES2015、ES2016、ES2017、ES2018、ES2019、ES2020、ES2021、ES2022、ESNexttarget:ES2020}}4.2 module模块系统{compilerOptions:{// 模块系统// 可选none、commonjs、amd、umd、system、es6/es2015、es2020、es2022、esnext、node16、nodenextmodule:commonjs,// Node.js 项目// module: ESNext, // 前端项目// 模块解析策略moduleResolution:node,// 输出目录outDir:./dist,// 源码目录rootDir:./src,// 基础路径baseUrl:.,// 路径映射paths:{/*:[src/*],components/*:[src/components/*]}}}4.3 lib库文件{compilerOptions:{// 包含的库文件lib:[ES2020,DOM,DOM.Iterable]// 常用组合// 前端项目[ESNext, DOM, DOM.Iterable]// Node.js[ESNext]// 仅 ES[ES2020]}}5. 严格模式配置5.1 strict 家族{compilerOptions:{// 开启所有严格检查推荐strict:true,// 禁止隐式 anynoImplicitAny:true,// 严格 null 检查strictNullChecks:true,// 严格函数类型strictFunctionTypes:true,// 严格 bind/call/applystrictBindCallApply:true,// 严格属性初始化strictPropertyInitialization:true,// 禁止隐式 thisnoImplicitThis:true,// catch 变量类型为 unknownuseUnknownInCatchVariables:true,// 始终严格检查alwaysStrict:true}}5.2 单独配置示例{compilerOptions:{// 不开启全局严格模式strict:false,// 只开启部分检查noImplicitAny:true,strictNullChecks:true,noImplicitThis:true}}6. 输出控制6.1 基本输出配置{compilerOptions:{// 输出目录outDir:./dist,// 源码目录rootDir:./src,// 单个输出文件outFile:./dist/bundle.js,// 删除注释removeComments:true,// 不生成输出只做类型检查noEmit:false,// 错误时仍输出noEmitOnError:false,// 生成声明文件declaration:true,// 声明文件输出目录declarationDir:./types,// 生成声明映射文件declarationMap:true,// 生成源映射sourceMap:true,// 内联源映射inlineSourceMap:false,// 内联源码inlineSources:true}}6.2 增量编译{compilerOptions:{// 启用增量编译incremental:true,// 增量编译信息文件tsBuildInfoFile:./.tsbuildinfo,// 诊断信息diagnostics:true,// 扩展诊断信息extendedDiagnostics:false}}7. 模块解析配置7.1 路径映射{compilerOptions:{// 基础路径baseUrl:.,// 路径映射paths:{/*:[src/*],components/*:[src/components/*],utils/*:[src/utils/*],services/*:[src/services/*],types/*:[src/types/*]},// 允许默认导入allowSyntheticDefaultImports:true,// ES 模块互操作esModuleInterop:true,// 解析 JSON 模块resolveJsonModule:true,// 允许导入 JS 文件allowJs:true,// 检查 JS 文件类型checkJs:false}}7.2 模块解析策略{compilerOptions:{// 模块解析策略// classic传统 TypeScript 解析// nodeNode.js 解析// bundler打包器解析TS 5.0// nodenextNode.js 最新解析moduleResolution:node,// 解析非相对模块的基础路径baseUrl:.,// 路径映射paths:{*:[node_modules/*,src/types/*]},// 根路径rootDirs:[src,generated],// 类型根路径typeRoots:[./node_modules/types,./src/types],// 类型包名types:[node,jest,express]}}8. 类型检查选项8.1 代码质量检查{compilerOptions:{// 未使用的局部变量报错noUnusedLocals:true,// 未使用的参数报错noUnusedParameters:true,// 检查函数是否有隐含返回值noImplicitReturns:true,// 检查 switch 语句是否遗漏 casenoFallthroughCasesInSwitch:true,// 检查未使用的标签noUnusedLabels:true}}8.2 其他检查选项{compilerOptions:{// 禁止使用 anynoImplicitAny:true,// 禁止使用 any[]需要明确类型noImplicitAny:true,// 强制文件名大小写一致forceConsistentCasingInFileNames:true,// 跳过库类型检查skipLibCheck:true,// 跳过类型检查skipDefaultLibCheck:false}}9. 项目引用9.1 配置项目引用// tsconfig.base.json基础配置{compilerOptions:{composite:true,declaration:true,declarationMap:true,incremental:true}}// tsconfig.json根配置{files:[],references:[{path:./packages/core},{path:./packages/utils},{path:./packages/api},{path:./apps/web},{path:./apps/admin}]}// packages/core/tsconfig.json{extends:../../tsconfig.base.json,compilerOptions:{outDir:./dist,rootDir:./src},include:[src/**/*]}9.2 构建项目引用# 构建所有项目tsc--build# 构建特定项目tsc--buildpackages/core# 清理构建tsc--build--clean# 强制构建tsc--build--force10. 完整配置示例10.1 Node.js 项目配置{compilerOptions:{// 基本配置target:ES2020,module:commonjs,lib:[ES2020],outDir:./dist,rootDir:./src,// 严格模式strict:true,noImplicitAny:true,strictNullChecks:true,// 模块解析moduleResolution:node,esModuleInterop:true,allowSyntheticDefaultImports:true,resolveJsonModule:true,// 输出declaration:true,declarationMap:true,sourceMap:true,removeComments:true,// 检查noUnusedLocals:true,noUnusedParameters:true,noImplicitReturns:true,forceConsistentCasingInFileNames:true,// 其他skipLibCheck:true,incremental:true},include:[src/**/*],exclude:[node_modules,dist,**/*.test.ts]}10.2 React 项目配置{compilerOptions:{// 基本配置target:ES2020,module:ESNext,lib:[ES2020,DOM,DOM.Iterable],jsx:react-jsx,outDir:./dist,rootDir:./src,// 严格模式strict:true,// 模块解析moduleResolution:bundler,allowSyntheticDefaultImports:true,esModuleInterop:true,resolveJsonModule:true,// 路径映射baseUrl:.,paths:{/*:[src/*],components/*:[src/components/*],hooks/*:[src/hooks/*],utils/*:[src/utils/*]},// 输出sourceMap:true,// 检查noUnusedLocals:true,noUnusedParameters:true,forceConsistentCasingInFileNames:true,// 其他skipLibCheck:true},include:[src/**/*],exclude:[node_modules,dist]}10.3 库项目配置{compilerOptions:{// 基本配置target:ES2020,module:ESNext,lib:[ES2020],declaration:true,declarationMap:true,outDir:./dist,rootDir:./src,// 严格模式strict:true,// 模块解析moduleResolution:node,esModuleInterop:true,// 输出sourceMap:true,removeComments:false,// 检查noUnusedLocals:true,noUnusedParameters:true,forceConsistentCasingInFileNames:true,// 其他skipLibCheck:true},include:[src/**/*],exclude:[node_modules,dist,**/*.test.ts]}11. 常用配置组合项目类型targetmodulelib其他关键配置Node.jsES2020commonjsES2020esModuleInteropReactES2020ESNextES2020, DOMjsx: react-jsxVueES2020ESNextES2020, DOM使用 vue-tsc库ES2020ESNextES2020declaration: true浏览器ES2020ESNextES2020, DOMmoduleResolution: bundler12. 总结配置分类关键选项用途基本target, module, lib语言版本和运行环境严格strict, noImplicitAny类型安全输出outDir, declaration, sourceMap编译产物模块moduleResolution, paths, baseUrl模块解析检查noUnusedLocals, noImplicitReturns代码质量项目references, composite多项目构建