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 生成初始配置:

bash
npx tsc --init

预期结果:

text
当前项目目录生成 tsconfig.json;文件中的默认选项和注释可能随 TypeScript 版本不同而变化。

生成配置只是起点。生产项目通常应该保留真正需要的选项,而不是因为模板中出现了某个配置就全部启用。

建立一个最小可验证配置

下面的配置适合只做类型检查、由其他构建工具负责产物生成的项目。strict 开启严格类型检查,noEmit 阻止 tsc 写出 JavaScript,include 则把项目边界限制在 src。

json
{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "noEmit": true
  },
  "include": ["src/**/*.ts"]
}

准备一个 src/index.ts:

ts
const answer: number = 42;
console.log(answer);

然后显式指定项目配置运行检查:

bash
npx tsc -p tsconfig.json

预期输出:

text
无类型诊断,进程正常结束。

-p 或 --project 很适合仓库中存在多个 tsconfig 时明确选择项目。不要在期望使用项目配置时改成 npx tsc src/index.ts:当命令行直接指定输入文件时,TypeScript 不会按普通项目模式读取 tsconfig.json 中的整套文件配置。

用 extends 复用公共规则

多个应用或包通常需要相同的严格模式、目标 JavaScript 版本和其他编译策略。把这些规则复制到每个 tsconfig.json 会导致配置逐渐漂移,更合适的方式是建立基础配置,然后通过 extends 继承。

tsconfig 配置继承关系

例如先创建 tsconfig.base.json:

json
{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "noEmit": true
  }
}

应用自己的 tsconfig.json 只保留差异:

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 已经足够;只有出现多个应用、库或构建目标后,再引入基础配置和继承层级。配置层数越多,解析来源越难追踪,因此应优先保持继承链短而明确。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识 tsconfig.json

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通