1 / 4概念
Toolchain: Declarations and Config
类型从哪来、编译器怎么找到它、项目怎么串起来,这三件事决定了类型检查是否可信。判断标准不是会不会改 tsconfig,而是能否说清一次 import 走了哪条解析路径,以及结果为什么与运行时一致。
1 概念
1.1 一句话定义
类型来源只有三种:源码、声明文件、推断。编译器按模块解析规则找到声明,按 tsconfig 决定检查强度与输出。.d.ts 只描述形状,不产生任何运行时代码。
1.2 它解决什么问题
- 给无类型代码补类型:老包、全局脚本、动态加载的模块都能有声明。
- 让三方一致:编辑器、CI 和打包器读同一份配置,结论一致。
- 多包增量构建:
references让子包只重编改动的部分。 - 发布类型:库把
.d.ts一起发布,使用者获得补全与检查。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 收窄、可赋值性 | Types and Narrowing |
| 泛型与类型运算 | Generics and Operators |
| 打包器与包管理器的运行时配置 | Toolchain |
Node 的模块加载与 require 语义 | Runtime Environment |
| 发布流水线 | 仓库运维章节 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 声明文件 | .d.ts,只含类型 | 不产生运行时代码 |
| 环境声明 | 用 declare 描述已存在的值 | 不创建值 |
| 模块扩充 | declare module 在已有模块上加成员 | 文件必须先是模块才生效 |
| 全局扩充 | declare global | 只能写在模块文件里 |
| 模块解析 | 从导入路径找到文件 | 与运行时解析可能不同 |
exports 条件 | 按 import/require 分支导出 | 顺序决定命中 |
paths | 编译期路径别名 | 运行时要另配 |
| 项目引用 | 包之间的依赖声明 | 需要 composite |
isolatedModules | 每个文件独立转译 | 类型导入必须显式 |
| 装饰器 | 类与成员的元编程语法 | 有两套不兼容的语义 |
2 机制
2.1 心智模型
一次导入走三步:按解析规则找到文件,读它的声明,把声明并入当前程序。tsconfig 决定这三步的细节;references 决定多个程序之间谁依赖谁。
2.2 机制拆解
- 来源优先级:同目录下
.ts优先于.d.ts;包内先看types字段,再看@types。 - 生成声明:
declaration打开后,编译器为每个源文件生成.d.ts;declarationMap让跳转回到源码。 - 环境声明:不写导入导出的文件是脚本,
declare module 'x'会成为全局的模块声明;写了导入导出的文件是模块,同样的语句变成扩充。 - 模块扩充:先
import 'pkg',再declare module 'pkg',新成员才会并入原模块。 - 解析模式:
node10按目录与package.json的main;node16与nodenext按exports且要求显式后缀;bundler按打包器语义。 - 条件导出:
exports里types条件必须排在最前,否则解析会落到 JavaScript 文件上。 - 项目引用:子包
composite: true并产出声明,父包通过references引用,构建可增量。 - 两套装饰器:旧版需要
experimentalDecorators与元数据,支持参数装饰器;标准版不需要开关,不支持参数装饰器,也没有元数据。
2.3 完整枚举
常用编译选项按类别,这是常改的集合:
| 类别 | 选项 | 作用 |
|---|---|---|
| 严格性 | strict、noUncheckedIndexedAccess、exactOptionalPropertyTypes | 检查强度 |
| 语言 | target、lib | 输出语法与内建类型 |
| 模块 | module、moduleResolution | 输出格式与解析规则 |
| 路径 | baseUrl、paths、rootDirs | 别名与根目录 |
| 输出 | outDir、declaration、declarationMap、sourceMap | 产物 |
| 互操作 | esModuleInterop、allowSyntheticDefaultImports、verbatimModuleSyntax | 默认导入与类型导入 |
| JS 支持 | allowJs、checkJs | 迁移期 |
| 隔离 | isolatedModules | 逐文件转译 |
| 构建 | composite、incremental、references | 增量与多包 |
| 性能 | skipLibCheck、skipDefaultLibCheck | 跳过声明检查 |
五种模块解析模式:
| 模式 | 依据 | 相对导入后缀 | 典型场景 |
|---|---|---|---|
classic | 相对路径查找 | 不需要 | 早期项目 |
node10 | main 与目录索引 | 不需要 | 老工具链 |
node16 | exports,按 type 分支 | 必须写 .js | Node 原生 ESM |
nodenext | 同上,跟随最新 Node | 必须写 .js | 新 Node 项目 |
bundler | 打包器语义,读 exports | 不需要 | Vite、Webpack |
两套装饰器的差异:
| 维度 | 旧版 | 标准版 |
|---|---|---|
| 开关 | experimentalDecorators | 默认启用 |
| 支持位置 | 类、方法、属性、访问器、参数 | 类、方法、字段、访问器 |
| 元数据 | emitDecoratorMetadata | 没有 |
| 运行时依赖 | 常配 reflect-metadata | 不需要 |
| 适用 | Angular、NestJS 等 | 新代码 |
四种声明合并:
| 形式 | 写法 | 前提 |
|---|---|---|
| 接口合并 | 同名 interface 两次 | 同作用域 |
| 命名空间合并 | namespace 与函数、类、枚举同名 | 同作用域 |
| 模块扩充 | declare module 'pkg' | 文件是模块 |
| 全局扩充 | declare global | 文件是模块 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
skipLibCheck 收益 | 类型检查时间的两三成 | 大项目更明显 |
.d.ts 体积 | 源码的十分之一到一半 | 影响编辑器加载 |
| 增量构建 | 秒级 | 依赖 composite 与缓存 |
| 后缀要求 | node16 下相对导入必须带 .js | 最容易踩的坑 |
| 装饰器元数据 | 每个装饰成员若干字节 | 反射库解析成本 |
3 实践
3.1 最小示例
先给一个没有类型的包写声明,再给一个已有模块加字段。两个文件的关键差别是:前者是脚本,后者是模块。
// types/legacy-widget.d.ts
declare module 'legacy-widget' {
export interface Options {
width: number;
height?: number;
}
export function mount(target: string, options: Options): {destroy(): void};
}
// types/fastify-user.d.ts
import 'fastify';
declare module 'fastify' {
interface FastifyRequest {
user?: {id: string; role: 'admin' | 'member'};
}
}
追踪第一个文件:它没有顶层导入导出,所以是脚本,declare module 声明了一个全局可见的外部模块。第二个文件有 import 'fastify',因此是模块,declare module 'fastify' 变成扩充,把 user 并进 FastifyRequest,请求处理器里可以直接读 request.user。
追踪失败情形:删掉 import 'fastify',文件退回脚本,扩充失效,request.user 变成未知属性。这是本页最常见的错误。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 只看类型 | tsc --noEmit | 不产出文件 |
| 生成声明 | declaration: true | 库发布必开 |
| 定位源码 | declarationMap: true | 跳转到 .ts |
| 强制类型导入 | verbatimModuleSyntax: true | 类型必须 import type |
| 逐文件转译 | isolatedModules: true | 与 esbuild、SWC 对齐 |
| 多包构建 | composite: true + references | 增量 |
| 跳过声明检查 | skipLibCheck: true | 提速,但掩盖冲突 |
| 别名 | paths: {"@/*": ["src/*"]} | 运行时另配 |
| 环境变量类型 | declare const __BUILD__: string | 打包器注入 |
| 抑制单行 | // @ts-expect-error | 必须紧跟下一行 |
3.3 标准流程
- 先确定目标运行时:浏览器、Node ESM、还是打包器,据此选
module与moduleResolution。 - 打开
strict与noUncheckedIndexedAccess,迁移期先关部分选项。 - 库代码打开
declaration与declarationMap。 - 单仓库用
composite加references,让构建走增量。 - 三方包缺类型时,先找
@types,再找自带类型,最后才手写声明。 - 手写声明放在
types/下并纳入include,每个文件加一行注释说明用途。
3.4 与相邻技术的组合
- 打包器:
bundler解析与 Vite 一致;别名要在两边同时配置。 - 测试:Vitest 复用
tsconfig路径,但运行时不走类型。 - 发布:
package.json的types与exports.types决定使用者能否拿到类型。 - Node 运行时:
node16模式与package.json的type字段共同决定是 ESM 还是 CJS。 - 装饰器框架:NestJS 依赖旧版装饰器与元数据,新项目要显式打开开关。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 解析模式 | node16 / bundler / node10 | 后缀与条件导出行为 |
| 模块输出 | ESM / CJS / 双格式 | 互操作与双包危害 |
| 检查范围 | 全量 / skipLibCheck | 时间与冲突可见性 |
| 多包组织 | 单 tsconfig / references | 增量与耦合 |
| 装饰器 | 旧版 / 标准版 | 框架兼容与元数据 |
3.6 决策规则
- 新项目用
bundler;直接跑在 Node 上的包用node16。 node16下相对导入一律写.js后缀,即使源文件是.ts。- 发布库必须开
declaration,并在exports里把types放第一位。 - 迁移中的 JavaScript 先开
allowJs与checkJs,再逐目录加strict。 skipLibCheck可在 CI 打开提速,但要定期关掉跑一次,暴露三方冲突。- 装饰器只在框架要求时使用;新代码优先标准版。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
源码 .ts | 完整检查 | 需要构建 | 自有代码 |
自带 .d.ts | 与实现同步 | 依赖发布方 | 现代包 |
@types 包 | 无需改动 | 版本可能滞后 | 老包 |
手写 .d.ts | 兜底 | 会漂移 | 无类型依赖 |
paths 别名 | 路径短 | 运行时另配 | 单仓库 |
| 项目引用 | 增量 | 配置复杂 | 多包仓库 |
3.8 何时不该用
- 不要手写声明去替代自己有源码的模块,双份必然漂移。
- 不要长期依赖
skipLibCheck掩盖三方类型冲突。 - 不要在全局
declare里放业务类型,会污染所有文件。 - 不要用
paths制造运行时无法解析的别名。 - 不要为了一个类型偷偷打开
noImplicitAny: false,那会连带放松其他检查。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 找不到模块 | 解析模式或后缀不对 | 换 moduleResolution,补 .js |
| 扩充不生效 | 文件不是模块 | 加 import 'pkg' |
| 两份同名类型冲突 | 装了多个 @types 版本 | 去重或 skipLibCheck |
| 声明与实现不符 | 手写 .d.ts 漂移 | 改用源码或生成 |
composite 引用报错 | 子包未构建 | 先 tsc -b |
| 装饰器元数据为空 | 未开 emitDecoratorMetadata 或未引入反射库 | 补配置与依赖 |
isolatedModules 报错 | 重新导出类型未加 type | 改 export type |
| 生产环境导入失败 | paths 只在编译期生效 | 打包器同步配别名 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 手写声明替代源码 | 双份漂移 | 用源码 |
全局 declare 放业务类型 | 全局污染 | 模块内导出 |
paths 与运行时不一致 | 编译过、运行挂 | 两边同配 |
长期 skipLibCheck | 冲突不可见 | 定期全量检查 |
关掉 strict 止血 | 问题延后 | 按目录逐步开 |
4.3 可观测信号
tsc 全量与增量耗时、解析失败次数、.d.ts 文件数量与总体积、声明与源码不一致的告警、编辑器跳转是否落到源码。
4.4 安全 / 性能 / 一致性边界
- 执行边界:
.d.ts不产生代码,也不执行,恶意声明不会直接运行,但会把错误类型带进编译期。 - 性能边界:解析与声明检查占类型检查的大头,
skipLibCheck与项目引用是最有效的两个开关。 - 一致性边界:编译期解析与运行时解析必须是同一套规则,否则会出现「编译通过、运行失败」。
- 发布边界:
exports的types条件缺失时,使用者在node16下拿不到类型,只能看到any。