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--modulecommonjs

3. 顶层配置

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、ESNext"target":"ES2020"}}

4.2 module（模块系统）

{"compilerOptions":{// 模块系统// 可选：none、commonjs、amd、umd、system、es6/es2015、es2020、es2022、esnext、node16、nodenext"module":"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,// 禁止隐式 any"noImplicitAny":true,// 严格 null 检查"strictNullChecks":true,// 严格函数类型"strictFunctionTypes":true,// 严格 bind/call/apply"strictBindCallApply":true,// 严格属性初始化"strictPropertyInitialization":true,// 禁止隐式 this"noImplicitThis":true,// catch 变量类型为 unknown"useUnknownInCatchVariables":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 解析// node：Node.js 解析// bundler：打包器解析（TS 5.0+）// nodenext：Node.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 语句是否遗漏 case"noFallthroughCasesInSwitch":true,// 检查未使用的标签"noUnusedLabels":true}}

8.2 其他检查选项

{"compilerOptions":{// 禁止使用 any"noImplicitAny":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--force

10. 完整配置示例

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. 常用配置组合

12. 总结