写TypeScript类型系统总结的文章太多了但大部分都是照着官方文档抄一遍看完就忘。这次我把这些年实际项目里用到的、面试里问到的、源码里见到的类型知识全部串了一遍整理成一份可以直接复制使用的手册。不管你是刚接触TS的新手还是写了好几年类型的老手这份总结里应该都有你能直接拿去用的东西。1. 类型体系的全貌先看清整张地图再出发很多人学TypeScript最大的问题是零散地记语法今天学个interface明天学个泛型结果遇到复杂类型就卡壳。我个人建议先花半小时把TS类型体系的整体结构摸清楚后面所有细节都能挂到这张地图上。1.1 类型的本质编译期的约束与集合论TypeScript的类型系统本质上是一套“集合系统”。每个类型描述的是一组可能的值的集合比如string是所有字符串的集合number是所有数字的集合而string | number是这两者的并集。这套集合论思维极其重要因为后面所有高级玩法——交叉类型、联合类型、条件类型——本质上都是集合运算。我把类型之间的关系概括为下面几个层次顶层类型unknown和any。unknown是所有类型的父类型any则直接关闭了类型检查。底部类型never。空集没有任何值可以赋值给它。基础类型string、number、boolean、null、undefined、symbol、bigint。复合类型数组、元组、对象、函数、class实例。字面量类型click、42、true这种具体值本身作为类型。泛型系统把类型参数化相当于“类型的函数”。高级类型工具映射类型、条件类型、模板字面量类型这些用类型操作类型的语法。1.2 类型推导与类型推断TS编译器会在绝大多数场景自动推断类型不需要我们手动标注。看这个简单例子let count 42; // 推导为 number const name Alice; // 推导为 Alice字面量类型因为const不可变 let items [1, 2, 3]; // 推导为 number[]不过有几类场景必须显式标注。第一是函数参数TS不会根据函数内部逻辑反推参数类型第二是函数返回类型虽然TS能推断但为了可读性和防止意外改变我建议复杂函数都写返回类型第三是那些“初始化为空”的变量比如let config {};后面再给对象添加属性就会报错这种应该先定义接口再标注。2. 基础类型与字面量类型地基里的隐藏细节这一节看起来基础但我敢说很多人对unknown和any的区别、字面量类型拓宽的坑、以及symbol类型的特殊用法并没有完全吃透。实际项目中这些细节出问题的频率非常高。2.1 unknown vs any安全派和躺平派any意味着“不做任何检查”可以把任意值赋给任意类型也能调用任意方法。这相当于把TS降级成了JS。unknown则是“未知但安全”的类型它同样能接收任意值但在你确认类型之前不能使用它。let data: unknown fetchData(); // data.name; // 报错对象的类型为 unknown。 // 需要先收窄 if (typeof data object data ! null) { // 再经过一些断言才能访问属性 }我接手过的老项目里很多any滥用后来规范改为“能用unknown就不用any”凡是从外部API拿来的数据一律标成unknown强制在入口处做类型收窄。实测这个改动让运行时错误明显减少原因很简单类型收窄的过程强迫你思考数据真实结构。2.2 字面量类型与拓宽Literal Widening字符串字面量类型是TS里使用频率极高的特性三种写法效果完全不同let event1: click click; // 明确标注类型就是 click const event2 click; // const推导为 click let event3 click; // let推导为 string拓宽了如果你希望let声明的变量保持字面量类型必须显式标注类型。这个细节在做配置对象时极其常用let mode: development | production; mode development; // OK mode test; // 报错2.3 never类型不是“永不执行”而是“空集合”never最常见的使用场景有两个。第一是穷尽性检查在switch的default分支里声明变量为never一旦有人给联合类型新增成员忘了添加对应case编译器就会报错。type Action { type: INCREMENT } | { type: DECREMENT }; function reducer(action: Action) { switch (action.type) { case INCREMENT: return 1; case DECREMENT: return -1; default: { const exhaustiveCheck: never action; return 0; } } }第二个场景是条件类型的“否则分支”后面讲条件类型时会重点展开。3. 对象类型与接口interface和type到底怎么选这是一个没有标准答案但每个团队都要面对的问题。先说结论我个人的统一规范是“公开API用interface复杂组合和工具类型用type”。但这个结论背后是有具体理由的。3.1 interface的核心能力声明合并与继承interface有两个type没有的特性声明合并和天然的继承语法。声明合并的意思是同名的interface会自动合并这在扩展第三方库类型时特别好用interface Window { myCustomField: string; } // 不报错自动合并到了全局Window上继承语法比交叉类型更直观报错信息也更友好interface Animal { name: string; } interface Dog extends Animal { breed: string; }3.2 type别名的独有本领联合与映射type可以通过模拟继承但它的真正优势在于能表示interface无法表示的东西——联合类型、元组、基本类型别名、条件类型等type ID string | number; type Point [number, number]; type ResultT { success: boolean; data: T }; type Handler (event: MouseEvent) void;3.3 可选属性、readonly与索引签名对象类型里三个高频细节值得单独说。第一个是可选属性attr?: string它的类型实际上是string | undefined检查时要用??而不是||去兜底否则空字符串也会被错误替换。第二个是readonly修饰符注意它只约束编译期运行时不生效无法阻止对象引用内部被修改深冻结还是要用Object.freeze配合递归。第三是索引签名写动态对象的隐患很多interface StringArray { [index: number]: string; } interface Dict { [key: string]: number; }如果对象里既要有明确属性又要允许额外键最好这样写interface Config { mode: dev | prod; [key: string]: unknown; // 明确索引签名的值为unknown }4. 函数类型与this容易被忽略的“调用上下文”函数类型不仅是(args) return这么简单重载、参数类型收窄、this参数这些细节在实际工程中都是硬骨头。这里我把函数相关的类型体系完整过一遍。4.1 函数类型表达式、调用签名与构造签名三种表达函数类型的方式// 方式一函数类型表达式 type Fn (x: number, y: number) number; // 方式二对象内的调用签名可以附带属性 interface FnWithProps { (x: number): number; version: string; } // 方式三构造签名表示可new interface DateConstructor { new (): Date; }4.2 函数重载重载列表在前实现签名在后TS的重载本质上是“声明多个调用方式”而不是像Java那样写多个函数体。拿实际例子说话function pickT(obj: T, key: keyof T): T[keyof T]; function pick(obj: Recordstring, unknown, key: string): unknown; function pick(obj: any, key: string) { return obj[key]; }重载顺序需要注意越具体的重载放在越前面否则后面的会被前面的覆盖或者被TS忽略。这个坑我踩过把string类型的重载放在a | b字面量重载前面结果调用传入a时匹配到了宽泛的签名返回类型就丢了精度。4.3 剩余参数与元组类型剩余参数配上元组类型能写出很精确的debounce和curry类型function debounceArgs extends any[], F extends (...args: Args) void( fn: F, delay: number ) { let timer: number; return function (...args: Args) { clearTimeout(timer); timer setTimeout(() fn(...args), delay); }; }这里的Args extends any[]是唯一需要允许任意参数列表的方法虽然any[]看起来不优雅但在泛型约束中它是合法且常用的。4.4 this的显式标注在class里我们靠this推断就够了但独立函数里的this经常出问题。TS允许在参数列表第一个位置声明this的类型interface User { id: number; name: string; } function getUserInfo(this: User) { return ${this.id}: ${this.name}; } const u { id: 1, name: Alice }; getUserInfo.call(u); // OK getUserInfo.call({ id: 2, name: Bob }); // OK注意this不是一个真实参数它只用于编译期检查运行时JS会忽略它。在写Vue Options API、事件监听器回调时这个特性格外有用。5. 泛型系统TS类型体系中的“引擎”如果只能选一个主题深入学我建议把泛型吃透。泛型用好了复杂类型工具信手拈来用不好写出来的类型全是any和重复代码。5.1 泛型的基本约束与默认值泛型可以看作“类型层面的函数”用定义参数用extends做约束用给默认值function cloneT extends object(source: T): T { return { ...source }; } type ResponseT unknown { code: number; data: T; };5.2 keyof、索引访问类型与类型映射keyof返回一个类型的键组成的联合类型配合索引访问类型T[K]可以做很多有用的工具type User { id: number; name: string; email: string }; type UserKeys keyof User; // id | name | email type IdType User[id]; // number // 把对象所有属性值改成布尔值 type BooleanifyT { [K in keyof T]: boolean; }; type UserFlags BooleanifyUser; // { id: boolean; name: boolean; email: boolean }5.3 泛型中的隐含问题联合类型会分布式执行条件类型遇到裸类型参数没有包装在元组或数组里时会自动拆解联合类型逐个判断这个叫分布式条件类型。很多“为什么结果和我想的注释不一样”的问题都源于此type IsStringT T extends string ? true : false; type A IsStringstring | number; // 结果是 boolean因为 TS 先分拆成 IsStringstring | IsStringnumber // 也就是 true | false等价于 boolean如果不希望分布式行为把泛型参数用元组包一层type IsStringDistributedAvoidedT [T] extends [string] ? true : false; type B IsStringDistributedAvoidedstring | number; // false6. 高级类型工具映射、条件、推断一套组合拳从TS 4.1开始官方内置的工具类型基本覆盖了大部分场景但在源码阅读和库开发中自己写高级类型是躲不开的。我把最核心的三个“元能力”拆开讲清楚。6.1 映射类型与键的重映射映射类型就是遍历联合类型生成新对象类型。键重映射靠as关键字可以过滤和改名type GettersT { [K in keyof T as get${Capitalizestring K}]: () T[K]; }; type User { id: number; name: string }; type GettersUser GettersUser; // { getId: () number; getName: () string; }注意这里Capitalizestring K的写法因为K在映射过程中可能是string | number | symbol而Capitalize只接受string需要先用string K做类型收窄。6.2 条件类型与 infer类型版的模式匹配infer是在条件类型里“声明一个待推断的类型变量”配合extends做模式匹配。数组、函数、Promise的解包都靠它type ElementTypeT T extends (infer U)[] ? U : T; type A ElementTypestring[]; // string type GetReturnTypeT T extends (...args: any[]) infer R ? R : never; type B GetReturnType() number; // number type UnwrapPromiseT T extends Promiseinfer U ? U : T; type C UnwrapPromisePromiseboolean; // boolean这三行代码已经能解决前端日常80%的“取内部类型”需求。再往上走一层infer配合递归可以解析出更复杂的结构type DeepUnwrapT T extends Promiseinfer U ? DeepUnwrapU : T; type D DeepUnwrapPromisePromisePromisestring; // string6.3 模板字面量类型字符串层面的类型计算TS 4.1引入了模板字面量类型可以在类型层面操作字符串type EventName on${Capitalize${string}}; type E onClick; // 满足 EventName实际项目里我用它做过事件映射表和API路径推导。再配合条件类型可以写一个路径参数解析器type ParsePathT extends string T extends ${infer Start}/${infer Rest} ? Start extends :${infer Param} ? { [K in Param]: string } ParsePathRest : ParsePathRest : T extends :${infer Param} ? { [K in Param]: string } : {}; type PathParams ParsePath/users/:id/posts/:postId; // { id: string; postId: string }6.4 完整工具类型速查表内置工具类型最好反推一遍源码比背文档牢记得多。我把高频的几个做了一个表建议直接抄走工具类型作用典型场景PartialT所有属性可选更新操作的入参RequiredT所有属性必填表单全量提交ReadonlyT所有属性只读配置冻结PickT, K挑选一组属性按需透传字段OmitT, K剔除一组属性去掉敏感字段RecordK, V构造键值对象字典映射ExcludeT, U从联合类型剔除过滤事件类型ExtractT, U从联合类型提取筛选特定类型NonNullableT去掉null和undefined清理可选值ReturnTypeT取函数返回类型解包业务函数ParametersT取函数参数元组透传参数InstanceTypeT取class实例类型实例化工厂7. 类型编程的实战套路从“看得懂”到“写得出来”这一节是全文最有操作价值的部分把我从真实项目里提炼出来的几个高频模式分享出来。这些模式几乎每天都能用到直接复制改改就能适配你的业务。7.1 类型守卫让收窄逻辑可复用typeof、instanceof、in这些操作符都能做类型收窄但把它们封装成自定义类型守卫函数可以让收窄逻辑复用配合unknown类数据尤其好用function isRecord(value: unknown): value is Recordstring, unknown { return typeof value object value ! null !Array.isArray(value); } function isStringArray(value: unknown): value is string[] { return Array.isArray(value) value.every((item) typeof item string); }注意返回值类型是value is Xxx这种断言语法它和布尔返回值不同TS会把这个函数视为可信的收窄工具。7.2 从数据常量推导联合类型TS推荐用as constkeyof typeof从常量对象反向推导联合类型我是这套写法的重度用户const ROUTES { home: /, about: /about, contact: /contact, } as const; type RoutePath typeof ROUTES[keyof typeof ROUTES]; // /home | /about | /contact type RouteKey keyof typeof ROUTES; // home | about | contact这比手动写一遍联合类型要好维护得多新增路由时自动生效不会出现两边不同步的问题。7.3 类型体操的经典例题DeepPartial与DeepReadonly面试和源码里经常见到递归映射类型的实现核心是判断属性值是否是对象是就递归处理type DeepPartialT { [K in keyof T]?: T[K] extends object ? DeepPartialT[K] : T[K]; }; type DeepReadonlyT { readonly [K in keyof T]: T[K] extends object ? DeepReadonlyT[K] : T[K]; };需要特别注意的是T[K] extends object ? ... : ...这个判断对函数类型也成立但函数不应该被递归展开。所以更严谨的写法要加T[K] extends (...args: any[]) any ? T[K] : ...这个分支这个坑我补了好几次才想起来。7.4 条件类型infer组合从复杂嵌套API中提取类型在对接第三方SDK时经常遇到深嵌套的响应结构用类型工具一次性把内部类型提取出来interface ApiResponseT { code: number; data: T; message: string; } type UnwrapApiT T extends ApiResponseinfer D ? D : never; // 假设某接口返回的是用户列表 type UserListResp ApiResponse{ items: User[]; total: number }; type UserListData UnwrapApiUserListResp; // { items: User[]; total: number }7.5 用泛型约束防止过度耦合泛型的约束不仅能做类型检查还能减少调用方不必要的传参负担。我常用的一种模式是“默认推断可覆盖”interface PaginationOptionsT { items: T[]; current: number; pageSize: number; } function paginateT(options: PaginationOptionsT): T[] { const { items, current, pageSize } options; return items.slice((current - 1) * pageSize, current * pageSize); }8. 声明文件、模块解析与编码规范让类型体系融入工程类型体系的终点不只是写几个类型工具而是把它融入工程规范保证团队协作时类型不被随意绕过。8.1 declare的三种高频用法declare module 通配符给非JS资源声明类型比如CSS模块和图片资源。declare global往全局作用域补充类型用于扩展Window、String接口。declare function/declare const描述一段已存在的JS实现类型。一个覆盖导入CSS模块的声明文件示例// env.d.ts declare module *.module.css { const classes: { readonly [key: string]: string }; export default classes; }8.2 三斜线指令与types字段/// reference typesnode /在底部类型声明文件里会让依赖关系更明确。同时tsconfig.json里的types字段建议显式列出需要加载的包避免所有types/*包全部自动加载拖慢编译。我一般这样配置{ compilerOptions: { types: [node, jest, vite/client] } }8.3 tsconfig的几个关键严格选项strict模式全家桶里我建议以下选项必须开{ compilerOptions: { strict: true, noImplicitAny: true, strictNullChecks: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true } }这里重点说noUncheckedIndexedAccess它会对索引签名、数组下标的读取结果自动加undefined。很多人一开始不习惯因为arr[0]变成了string | undefined强制你处理越界问题但上线后减少的空引用错误是实打实的。8.4 团队类型规范速查清单我整理了一份项目里实际执行过的类型编写规范分享出来供参考禁止滥用any外部输入统一走unknown 类型守卫收窄。公开API的入参和返回值必须显式标注类型不依赖推断。对象结构优先用interface联合类型、映射类型、工具类型组合用type。枚举类型尽量用as const对象替代运行时行为更可控。复杂嵌套的响应数据提供对应的提取工具类型不让外部直接面对深层泛型。catch的异常对象默认是unknown先判错再处理。注释只写“为什么”不写“是什么”因为类型本身就是文档。9. 常见类型错误与排查实录最后这部分全是我和团队在实际开发中踩过的坑每个都有真实的报错现场按频率从高到低罗列。9.1 类型报错“Type undefined is not assignable to type string”几乎所有刚开严格模式的人都会遇到。原因在于可选属性、数组越界、Map.get()等API只要严格Null检查开启undefined就显式存在。解决办法不是关闭strictNullChecks而是把对这个值的处理路径显式写出来。我曾经在一个老项目里把strictNullChecks关掉结果运行时空引用bug集中爆发后来老老实实全开再通过??兜底逐层修掉。9.2 回调函数的参数类型被误解逆变与协变TS对函数参数类型在赋值时采用的是“双向逆变检查”bivariant这在一部分场景会放过错误代码。一个典型例子是事件回调的参数类型宽窄不匹配可能不报错但运行时又确实会出问题。遇到这类疑难杂症建议给回调显式标注参数类型不要依赖上下文推断。9.3 “Object is possibly null” 频繁出现document.getElementById返回的类型就是HTMLElement | null访问属性前先判空const el document.getElementById(app); if (el) { el.innerHTML hello; }另一种更优雅的方式是使用!非空断言但只在确实确定不可能为null时使用我一般给自己写的函数保证非空返回时才用。9.4 泛型函数“could be instantiated with a different subtype”这个报错通常出现在泛型参数没有正确约束时。比如function getLengthT(obj: T): number { return obj.length; // 报错 }报错原因在于T可以是被传入的任何类型TS无法假设它有length属性。解决办法是给T加上extends { length: number }约束。9.5 声明合并意外污染全局类型interface同名自动合并很方便但它也会导致“以为在声明局部类型实际却改了全局”的问题。我在一个模块的.d.ts里声明interface Config结果项目里所有Config都被污染成了一份类型。后来团队规定全局声明文件里只允许声明全局变量和扩展第三方接口业务类型一律通过export导出再引入。10. 最后一轮小测验看看这份类型体系你掌握了多少把一篇长文的干货变成自己的东西最好的方式就是做题。我留了五道小练习先自己思考再看答案思路。实现一个ToReadonly工具类型把对象所有属性变为readonly但嵌套对象不变。实现一个MergeA, B类型让B的属性覆盖A的同名属性其余保留。写一个类型守卫判断一个值是Recordstring, string。定义一个泛型函数接收一个Promise并返回其解包后的内部值类型。实现PartialByKeysT, K只让指定的键变为可选。简要参考思路第一题用{ readonly [P in keyof T]: T[P] }即可第二题可用OmitA, keyof B B第三题参考value is Recordstring, string的守卫声明第四题用T extends Promiseinfer U ? U : T第五题用OmitT, K PartialPickT, K。我在带团队的时候最喜欢用这五道题检验候选人的类型功底能顺畅写出前四道的基本上可以放心让写业务类型第五道能秒出的属于类型编程已经形成直觉了。这些类型能力看起来多但核心思想浓缩起来就三句话一切类型皆集合infer就是类型版模式匹配映射加条件就是类型编程的组合子。把这三句话刻在脑子里再遇到任何复杂类型问题拆开看总能用已知的工具组合出来。