知识库 ts-knowledge-base

TypeScript 知识图谱

一、一句话结论

TypeScript 体系分六层看：类型基础 → 类型收窄 → 泛型 → 工具类型 → 声明与互操作 → 工程配置；它的本质是一句话——编译期类型层，运行时全部擦除，所以类型写得好是文档与重构安全网，运行时校验仍要靠校验库（如 zod）。

二、原理与来由（分层依据）

TS = JS + 静态类型层。分层按「一个值的类型知识如何产生与流动」：先有基础类型标注 → 通过控制流分析收窄到更精确的类型 → 泛型让类型随参数流动 → 工具类型在类型层做「运算」→ 声明文件描述外界的 JS 世界 → tsconfig 决定编译器多严格、产物长什么样。全部层都只在编译期存在。排查 TS 问题先分清：是类型报错（编译期）还是运行时行为（JS 层），两者的修法不同。

三、细节与用法

① 类型基础

主题 一句话要点 检索关键词
基础与特殊类型 原始类型小写（string 不是 String）；any 放弃检查、unknown 安全未知（用前必须收窄）、never 不可达、void 无返回 any、unknown、never
数组与元组 T[] / Array<T>；元组 [a: string, b?: number] 固定长度与位置类型，带标签可自文档化 元组、具名元组
枚举 enum 生成运行时对象（有代价）；字符串字面量联合类型 + as const 常是更轻的替代 enum、as const
函数类型 参数与返回类型；可选 / 默认参数；函数重载是签名列表 + 一个实现签名 重载、签名
interface vs type interface 可声明合并、可 extends；type 能做联合、交叉、条件类型；对象形状两者皆可，按团队约定统一 interface、type 区别

② 类型收窄（narrowing）

主题 一句话要点 检索关键词
控制流分析 if/typeof/instanceof/真值检查都会收窄类型；分析沿控制流传播（先判空后用） 收窄、控制流
可辨识联合 `{ kind: "circle" } { kind: "square" }+ switch(kind) 是 TS 建模多态数据的标准姿势；穷尽检查用never` 兜底
类型守卫 自定义守卫 x is Foo；断言 as（骗编译器，慎用）、非空断言 !；satisfies 校验不改变推断 类型守卫、satisfies、as

③ 泛型

主题 一句话要点 检索关键词
类型参数 <T> 让类型随调用流动；泛型约束 T extends Xxx 限定能力范围 泛型、约束
keyof 与索引访问 keyof T 取键联合；T[K] 取值类型；两者组合是类型安全取值的钥匙 keyof、索引访问
条件类型 A extends B ? X : Y 类型层的三元；infer 在匹配中提取类型（如 ReturnType<T> 的实现） 条件类型、infer
映射与内置工具 Partial/Required/Pick/Omit/Record/Readonly/Exclude/Extract/ReturnType/Parameters——映射类型 + keyof 的组合产物 工具类型、映射类型
模板字面量类型 `on${Capitalize<K>}` 在类型层拼接字符串，事件名等字符串模式类型化 模板字面量类型

④ 声明与互操作

主题 一句话要点 检索关键词
声明文件 .d.ts 只描述类型；三方库类型在 DefinitelyTyped（@types/xxx）或包内自带 d.ts、@types
渐进迁移 allowJs 允许 JS/TS 混居；checkJs 选择性检查 JS；// @ts-ignore / @ts-expect-error 局部压制（后者断言下一行真的有错） 渐进迁移、ts-expect-error
运行时边界 接口 / 类型标注在运行时不存在——外部输入（网络、用户）的类型校验不能靠 TS，用 zod / valibot 等运行时校验库 运行时校验、zod

⑤ 工程配置（tsconfig）

主题 一句话要点 检索关键词
strict 全家桶 strict: true 是新项目底线（strictNullChecks 最值）；noUncheckedIndexedAccess 更严（索引访问带 undefined） strict、strictNullChecks
模块解析 moduleResolution: bundler（现代打包器）/ node（CJS）；paths 别名与构建工具的 alias 要同步配 模块解析、paths
编译产物 tsc 只擦类型（isolatedModules 下不做类型级转换）；实际打包交给 esbuild / Vite / swc，tsc 专职类型检查（noEmit） noEmit、tsc vs esbuild
项目引用 大仓拆分：references + composite 分包增量检查 项目引用、增量构建

⑥ 生态与演进

主题 一句话要点 检索关键词
装饰器 旧 experimental decorators（框架在用）与新标准 decorators 装饰器语义不同，迁移看框架版本 装饰器、标准装饰器
类型挑战 type-challenges 仓库是泛型 / 条件类型的系统训练场 type-challenges
版本演进 5.x 主线（satisfies、const 类型参数、装饰器稳定化）；官方 Go 移植编译器（tsgo / Corsa 项目）大幅提速——落地状态待核实 TS 5、tsgo

四、流程图（图谱一页图）

flowchart TD
    subgraph S1["① 类型基础"]
        A1["原始 · 特殊类型"]
        A2["元组 · 枚举"]
        A3["interface vs type"]
    end
    subgraph S2["② 类型收窄"]
        B1["控制流分析"]
        B2["可辨识联合"]
        B3["类型守卫 · satisfies"]
    end
    subgraph S3["③ 泛型"]
        C1["约束 · keyof"]
        C2["条件类型 · infer"]
        C3["映射类型"]
    end
    subgraph S4["④ 工具类型"]
        D1["Partial · Pick · Record"]
        D2["模板字面量类型"]
    end
    subgraph S5["⑤ 声明与互操作"]
        E1["d.ts · @types"]
        E2["渐进迁移"]
        E3["运行时校验边界"]
    end
    subgraph S6["⑥ 工程配置"]
        F1["strict 全家桶"]
        F2["模块解析 · noEmit"]
        F3["项目引用"]
    end
    S1 -->|"标注后收窄"| S2
    S2 ~~~ S3
    S3 ~~~ S4
    S4 ~~~ S5
    S5 ~~~ S6

层间竖排是阅读顺序；所有层都只存在于编译期，运行时全部擦除。

五、边界与关联

六、出处

来源 位置 核实日期
TypeScript 官方手册（Handbook + Release Notes） typescriptlang.org/docs 2026-10-08
TypeScript Wiki（编译选项与迁移指南） github.com/microsoft/TypeScript/wiki 2026-10-08
个人实践（TS 全栈开发经验） 各层一句话要点为经验浓缩 2026-10-08

七、存疑与待办