JavaScript / TypeScript / 系统课时
认识 tsconfig.json
认识 tsconfig.json
tsconfig.json 不只是编译参数集合,它还定义哪些文件属于 TypeScript 项目,以及这些文件采用什么检查和输出规则。掌握配置生成、项目边界和 extends 继承后,才能稳定管理单包与多包工程。
学习目标
- 理解
tsconfig.json如何确定项目文件与编译行为 - 使用 TypeScript CLI 生成并验证项目配置
- 使用
extends复用公共配置并正确处理覆盖关系
tsconfig.json 定义一个项目
在目录中直接执行 tsc 时,TypeScript 会查找对应的 tsconfig.json,读取 compilerOptions、files、include、exclude 等配置。compilerOptions 控制类型检查和编译行为,而文件选择字段决定哪些源文件真正进入当前项目。
新项目可以使用 CLI 生成初始配置:
npx tsc --init预期结果:
当前项目目录生成 tsconfig.json;文件中的默认选项和注释可能随 TypeScript 版本不同而变化。生成配置只是起点。生产项目通常应该保留真正需要的选项,而不是因为模板中出现了某个配置就全部启用。
建立一个最小可验证配置
下面的配置适合只做类型检查、由其他构建工具负责产物生成的项目。strict 开启严格类型检查,noEmit 阻止 tsc 写出 JavaScript,include 则把项目边界限制在 src。
{
"compilerOptions": {
"target": "ES2022",
"strict": true,
"noEmit": true
},
"include": ["src/**/*.ts"]
}准备一个 src/index.ts:
const answer: number = 42;
console.log(answer);然后显式指定项目配置运行检查:
npx tsc -p tsconfig.json预期输出:
无类型诊断,进程正常结束。-p 或 --project 很适合仓库中存在多个 tsconfig 时明确选择项目。不要在期望使用项目配置时改成 npx tsc src/index.ts:当命令行直接指定输入文件时,TypeScript 不会按普通项目模式读取 tsconfig.json 中的整套文件配置。
用 extends 复用公共规则
多个应用或包通常需要相同的严格模式、目标 JavaScript 版本和其他编译策略。把这些规则复制到每个 tsconfig.json 会导致配置逐渐漂移,更合适的方式是建立基础配置,然后通过 extends 继承。

例如先创建 tsconfig.base.json:
{
"compilerOptions": {
"target": "ES2022",
"strict": true,
"noEmit": true
}
}应用自己的 tsconfig.json 只保留差异:
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"useDefineForClassFields": true
},
"include": ["src/**/*.ts"]
}最终项目会继承基础配置中的 target、strict 和 noEmit,同时增加当前项目自己的 useDefineForClassFields。子配置中的同名编译选项会覆盖基础配置;如果子配置重新声明 files、include 或 exclude,对应的父级文件选择配置也会被替换,而不是把两个数组简单拼接。
注意路径和继承边界
继承配置时,相对路径按照声明该路径的配置文件所在目录解析,而不是统一按照最末端的 tsconfig.json 解析。这一点对 outDir、typeRoots 或文件匹配路径尤其重要,否则共享配置移动到其他目录后可能得到意外结果。
extends 适合共享编译策略,但不应把所有项目差异都塞进基础文件。应用入口、环境专属类型、输出目录以及 include 范围通常仍应由具体项目控制。项目引用使用的 references 也需要在相应项目配置中单独声明,而不是依赖基础配置继承。
当仓库只有一个项目时,一个清晰的 tsconfig.json 已经足够;只有出现多个应用、库或构建目标后,再引入基础配置和继承层级。配置层数越多,解析来源越难追踪,因此应优先保持继承链短而明确。