TypeScript 写久了你会发现真正决定一个项目代码质量上限的往往不是泛型玩得有多花而是类型守卫和类型缩小这两件事做得够不够细。我见过不少项目接口定义写得很全但一到业务分支里就全是as any、as SomeType把编译器的保护全扔了。不是开发者不想写好而是没搞清楚类型守卫和类型缩小的运作机制遇到联合类型就只会用断言硬掰。这篇文章不谈泛型、不聊装饰器就聚焦一个事怎么用类型守卫让 TypeScript 编译器在分支里自动帮你缩小类型让你少写废话、少出运行时错误。适合写过一段时间 TypeScript、被联合类型和null判断折磨过的同学看完能直接拿到项目里用。1. 类型守卫和类型缩小看着是一对其实是一条链路1.1 先从一次真实报错说起有一次我接了个数据解析模块接口返回结构大概是这样的type ServiceResponse | { status: ok; data: User } | { status: error; message: string };业务代码里我写了个判断function onResponse(res: ServiceResponse) { if (res.status ok) { // 这里顺畅访问 res.data编译器没有报错 console.log(res.data.name); } }这段代码没有任何问题因为res.status ok是一个等值判断TypeScript 会顺着这个判断把res收窄成{ status: ok; data: User }这个成员。可一旦把逻辑拆到回调里情况就变了function onResponse(res: ServiceResponse, onDone: (user: User) void) { if (res.status ok) { // 报错类型“ServiceResponse”上不存在属性“data” queueMicrotask(() onDone(res.data)); } }这就是一个很典型的类型缩小失效场景。编译器在上一个分支里明明已经确认了res.status ok为什么进了回调反而把收窄丢掉了因为 TypeScript 的控制流分析是分作用域的它不认为回调函数的执行时机和当前判断是同一步所以回调体内的res会被重新放回联合类型。这类报错见得多了你自然就会去想类型守卫到底是什么它凭什么能缩小类型又为什么会在某些边界上失灵把这层机制搞明白你写的 TypeScript 才算真正入门。1.2 类型的“缩小”机制控制流分析在做什么类型缩小是结果类型守卫是手段。编译器在逐行分析代码时会根据判断条件、赋值操作、函数调用不断更新变量的“当前类型”这个过程叫控制流分析Control Flow Analysis。打个比方变量类型就相当于你兜里揣的会员卡。你刚进门时门卫只知道你有“某种卡”可能是普通卡、VIP卡、也可能是员工卡。你走到VIP通道口刷了一下卡门卫看到卡片上写着VIP后面几十米的路程他就默认你是VIP。这就是缩小。到了分岔路口你又换了一条普通通道门卫又重新认为你是普通卡。这就是窄化复位。对应到代码是这样的declare const item: string | number; if (typeof item string) { // item: string console.log(item.toUpperCase()); } else { // item: number console.log(item.toFixed(2)); } // 出了 if 之后item 又变回 string | number重点来了typeof就是类型守卫它产生一个布尔条件编译器根据这个条件里对item的约束来收窄类型。item在if分支内被缩成string在else分支内被缩成number离开这段判断后恢复原状。这套机制里的关键点是窄化跟随语法结构变化不跟随业务语义。你在一个if块里判断了这个块和它的else块才享受收窄结果。一旦进入别的函数、别的回调、别的模块编译器就必须重新从函数签名里拿到类型。这是很多新手费解的根源。1.3 类型守卫的家族谱系类型守卫粗分有四类类别写法典型场景内置运算符守卫typeof、instanceof、in判断基础类型、类实例、对象属性内置函数守卫Array.isArray()数组类型收窄真值性与等值守卫if (x)、if (x a)、switch联合类型成员判别、null/undefined 排除自定义守卫function isUser(u: unknown): u is User业务自定义类型校验断言守卫function assertUser(u: unknown): asserts u is User校验失败直接抛错收窄后续代码后面的内容我会按这个谱系一个个讲透再配合几个高频误区。顺序是从基础到进阶最后给一个可以直接抄走的速查表。2. 内置类型守卫最常用的四种坑也最多的四种2.1 typeof 守卫第一大坑是 nulltypeof是最基础的类型守卫它能识别string、number、boolean、symbol、bigint、undefined、object、function这几种运行时类型。语法很简单function printLen(input: string | number) { if (typeof input string) { return input.length; } return input.toFixed(2); }但你很快会撞上第一个坑——typeof null的结果是object。这是 ECMAScript 从第一天起就存在的历史遗留官方也承认是 bug但为了兼容性一直没改。所以下面这段代码value并不会被可靠地排除nulldeclare const value: { name: string } | null; if (typeof value object) { // value 在这仍然是 { name: string } | null // 报错value 可能为 null console.log(value.name); }正确做法是显式加上value ! null判断或者用真值性判断if (typeof value object value ! null) { console.log(value.name); // 收窄为 { name: string } }另一个容易忽略的点是typeof只能把类型收窄到“基础类型”这一层它无法把一个object收窄成具体的接口或类。比如typeof x object之后编译器只知道x是非 null 的 object但不知道它是User还是Order。想要进一步收窄要么用in判断属性要么用自定义类型谓词。2.2 instanceof 守卫注意原型链上的父子关系instanceof是针对类对象的守卫它基于 JavaScript 原型链做判断。TypeScript 会根据构造函数的继承关系来收窄类型。class Animal { speak() {} } class Dog extends Animal { bark() {} } function play(obj: Animal | Dog) { if (obj instanceof Dog) { obj.bark(); // obj: Dog } else { obj.speak(); // obj: Animal } }这条规则本身没问题但有两个使用细节要留心。第一个是判断顺序。如果父类在前子类在后子类的专属方法在父类分支里会报错反过来如果先判断子类父类分支里拿到的就是排除子类后的父类实例。如果你有个Cat也是Animal的子类判断完Dog之后else里得到的类型会是Animal而不是Cat或其他。从业务上讲这可能没问题但它反映了 TS 对else分支的处理是“排除已知类型”不是“自动定位到剩余具体类型”。第二个是原型链跨层级的问题。instanceof收窄出的类型范围以构造函数本身为准。如果某个类的实例是从子类构造出来的用父类做instanceof判断也能够通过此时 TS 会把它收窄成父类类型但运行时对象可能还带着子类的方法。这在多态场景里要格外注意——类型守卫帮你把“静态类型”缩小了但不代表“运行时真实类型”就等于那个缩小后的类型你需要对业务有把握。2.3 in 守卫处理“可能会有”的属性in操作用于判断对象是否包含某个属性。它在联合类型中的作用是检查属性名是否存在从而剔除掉没有这个属性的联合成员。type Fish { swim: () void }; type Bird { fly: () void }; function move(animal: Fish | Bird) { if (swim in animal) { animal.swim(); // animal: Fish } else { animal.fly(); // animal: Bird } }这条规则执行得很聪明swim in animal为 true 时TS 会把animal收窄为所有包含swim属性的联合成员。注意如果联合类型里有多个成员都包含swim那么收窄结果是这些成员的联合不是说有一个就叫 Fish。实际开发中我建议大家把in用在“结构上区分明显”的联合类型上——比如一个类型有kind字段另一个类型完全没有kind。如果两个类型都有kind字段但类型不同in判断针对的是属性存在性而不是属性值此时应该用等值判断或switch而不是in。2.4 真值性缩小与 Array.isArray隐式收窄的全过程真值性缩小是最容易忽略的一种守卫。它的规则是if (value)会把value从联合类型中排除null、undefined、0、、NaN、false这些 falsy 值。但关键在于它对number、string这类“有 falsy 值的基础类型”很特殊——不会把它们从联合里剔除只是在分支内保留原类型declare const val: string | number | null; if (val) { // val: string | number不是去除 null 后继续判断类型 console.log(val); }因为0和都是 falsyTS 不能保证在if (val)分支里 val 不是0或所以它宁可保持string | number不变。这一点和很多人的直觉不一样。如果你希望空字符串时走另一个分支需要显式与、0比较而不是依赖真值性。Array.isArray是内置函数守卫的常见代表它能把unknown或联合类型收窄为数组类型function process(input: string | string[]) { if (Array.isArray(input)) { input.map((item) item.toUpperCase()); // input: string[] } else { input.trim(); // input: string } }但它有个衍生坑filter(Boolean)并不会把元素的类型从T | null | undefined收窄成T。你写了const list [1, null, 2, undefined].filter(Boolean); // list 的类型还是 (number | null | undefined)[]因为filter(Boolean)在 TypeScript 的 lib 声明里只接收unknown返回值保持原元素类型它没法理解Boolean是“排除 falsy”的特殊谓词。正确的做法是用自定义守卫const list [1, null, 2, undefined].filter((x): x is number x ! null); // list: number[]这个例子已经顺势引出下一章的核心内容了。3. 自定义类型守卫把业务规则真正写进编译器3.1 类型谓词基础写法x is T 的语法与注意事项内置守卫覆盖不了业务类型比如你怎么用typeof判断一个对象是User而不是Admin没法直接判断。这时你需要写一个自定义类型守卫语法上叫“类型谓词”。interface User { id: number; name: string; email?: string; } function isUser(value: unknown): value is User { if (typeof value ! object || value null) return false; const obj value as Recordstring, unknown; return typeof obj.id number typeof obj.name string; }之后你的代码里就可以用if (isUser(input)) { input.name }编译器会在分支内无条件相信input是User。这是自定义守卫最大的优势把校验逻辑封装成函数一处写校验处处得类型。但这里有个极其重要的警告类型谓词是一个“断言”你告诉编译器一个规则编译器不会去验证你这个规则是否正确。它直接选择信任你。所以你在谓词函数里写出的运行时逻辑必须和你要确定的类型严格匹配。网上最常见的反面教材是function isUser(value: unknown): value is User { return true; // 千万不能这么写 }这么写之后所有unknown都会被当成User调用isUser后访问不存在的属性运行时必炸。自定义守卫的精髓就一句话先写校验再谈类型。谓词里的运行时逻辑式是要保护你的不是用来骗编译器的。3.2 可辨识联合项目里最高频的窄化模式可辨识联合Discriminated Union是自定义守卫的“前置姿势”也是绝大多数业务场景里最实用的一招。它靠一个统一的判别字段来区分联合成员。type ApiState | { status: idle } | { status: loading } | { status: success; data: string } | { status: error; message: string };这里的status就是“可辨识属性”。有了它写判断时 TypeScript 能精确收窄到每个成员function render(state: ApiState) { switch (state.status) { case idle: return 等待中; case loading: return 加载中; case success: // state 被收窄为 { status: success; data: string } return 数据${state.data}; case error: // 这里只剩 error 成员 return 错误${state.message}; } }这种模式的威力在于判别字段的值类型必须是字面量类型。如果你写成status: string编译器就没法通过success把状态收窄到具体成员。所以定义可辨识联合时要么直接写具体字符串要么在变量声明处加as consttype Item | { kind: text; content: string } | { kind: image; url: string }; const item { kind: text, content: hello } as const;我在项目里会把可辨识联合当成定义接口响应的首选方案后端返回的数据先用一个联合类型表达“有哪些可能”再配一个谓词函数做一次出口校验之后的业务代码全是干净的switch没有一行as。这个方法我用在很多数据解析模块里效果非常稳定。3.3 never 与断言函数让“不可能”变成编译错误可辨识联合配合switch已经很好用了但还有个隐藏技能用never做穷尽性检查。function assertNever(x: never): never { throw new Error(Unexpected value: ${JSON.stringify(x)}); } function render(state: ApiState) { switch (state.status) { case idle: return 等待中; case loading: return 加载中; case success: return 数据${state.data}; case error: return 错误${state.message}; default: return assertNever(state); } }当你给ApiState增加新的成员比如{ status: cancelled }编译时default分支里的state不再满足never编译器直接报错提醒你还有分支没处理。这相当于把“遗漏 case”从运行时炸弹变成了编译期提示。assertNever常见于两种写法一种是像上面这样声明一个返回never的函数另一种是用条件语句抛错if (state) { // 穷尽成员判断... }还有一种和never配合的进阶工具叫“断言函数”语法是asserts x is T。它和value is T的关键区别在于value is T返回布尔值适合if分支asserts x is T在失败时抛异常如果成功后面的代码立即收窄不需要if包裹function assertUser(value: unknown): asserts value is User { if (!isUser(value)) { throw new Error(无效的 User 数据); } } declare const data: unknown; assertUser(data); // 走到这一行data 已经被收窄为 User console.log(data.name);这个模式在“数据入口校验”场景里非常舒服比如解析接口返回的 JSON 之后先断言一把后续整段业务代码都享受类型安全。我个人倾向的用法是对外部数据用asserts或is做边界校验对内部状态机用可辨识联合加switch。4. 注意这些边界守卫不是万能的窄化有时会失效4.1 闭包与回调窄化不会跨进函数体这是实际开发中踩坑最多的一类。前面提过判断之后把变量传给回调/定时器/事件监听回调里访问该变量编译器往往还是会按原始联合类型处理。function register(handler: () void, data: { name: string } | null) { if (data) { // 捕获了一个“当时确定非空”的 data handler(() { // 报错data 可能为 null console.log(data.name); }); } }原因在于回调函数的执行时机不在当前判断的“窄化窗口”内。编译器没法保证handler执行的时候data没有被外部修改。要解决这个问题最简单的办法是用const捕获不可变量if (data) { const snapshot data; handler(() { console.log(snapshot.name); // 收窄成功 }); }const snapshot一旦赋值它的类型就不再跟随data变化窄化窗口也就固定了。这个模式我在所有回调场景都推荐优先使用。4.2 let 变量被函数调用重置的坑比闭包更隐蔽的是一个let变量你在if里判断完类型之后只要后续有任何函数调用TS 就会“重置”收窄结果。let result: string | null getResult(); if (result) { console.log(result.toUpperCase()); // 正常result: string } someOperation(); // 可能修改 result console.log(result.toUpperCase()); // 报错result 可能为 null为什么因为 TS 采用了保守策略它不知道someOperation内部会不会修改result所以宁可把result恢复到原始的string | null。这不是猜测这是保护。应对方案有三种判断之后立刻使用别隔太远。存到constconst snapshot result;对第二次使用再做一次判断。我见过有些人嫌麻烦直接as string结果运行时result真的变了页面崩得莫名其妙。老老实实存快照是最稳的。4.3 类型谓词的“高频误用”过度断言和错误实现自定义谓词虽然强大但用不好会带来比as更隐蔽的问题——因为as至少还有明显的符号让你警觉而is函数看起来“很正规”你容易放松警惕。比较常见的误用有两类。第一类是谓词实现过松。比如function isUser(value: unknown): value is User { return typeof value object value ! null; }任何非空对象都返回 true。isUser({ foo: 1 })也是 true然后业务代码访问user.name拿到的就是 undefined不报错但数据不对。这类 bug 特别难排查因为类型检查全通过运行也不崩就是结果错误。第二类是只做“存在性”校验不验证字段类型。正确做法是在谓词里对关键字段一个个做typeof检查别图省事只查一个字段就下结论。尤其是从接口、存储、用户输入等不可信源拿到的数据谓词就是你的防线防线越松后面的坑越深。另外有个细节在数组filter里使用谓词时类型参数写法是const users rawList.filter((item): item is User isUser(item)); // users: User[]注意箭头函数内部要写item is User而不是isUser(item)。后者只是返回布尔值起不到收窄数组元素类型的作用。4.4 可辨识联合的判别属性必须“可控”可辨识联合看着美好但有一个先决条件判别属性必须是字面量类型而且最好用as const或者直接定义在类型里。如果你从接口拿回的数据里status字段类型被声明成了string那 switch 分支里的收窄照样失效。interface RawState { status: string; // 这里必须是字面量联合类型 }一个实用的习惯是在定义接口响应时把状态字段收窄成显式字面量联合type State { status: idle | loading | success | error; data?: string };写类型时不偷懒写判断时才会顺利。5. 高频问题排查手册与实用建议5.1 一张表总结常见坑我把自己踩过的坑和同事常问的问题整理成一张表方便你直接对照。现象本质原因解决办法typeof value object后value还是nulltypeof null object的历史遗留加 value ! null显式判断if (data)之后回调里访问data报“可能为空”窄化不跨函数作用域用const snapshot data捕获快照filter(Boolean)之后数组元素类型没变Boolean不是类型谓词TS 无法理解自定义(x): x is T ...谓词switch分支里联合成员无法收窄判别字段被声明成宽泛string用as const或字面量联合类型定义自定义谓词返回true后运行时数据异常谓词实现与类型声明不匹配在谓词里逐字段做typeof校验let变量判断完类型调用函数后又恢复原状TS 假设函数可能修改变量用const或在使用前重新判断in判断后联合成员没有按预期收窄多个成员都拥有该属性无法区分改用可辨识联合的等值/switch 判断这张表不一定覆盖所有场景但基本覆盖了 80% 的日常报错。遇到新问题先想想“窄化窗口”是否存在再想想你的数据是否真的是字面量联合。5.2 我自己的两条实战心得第一条项目里 90% 的联合类型应该设计成可辨识联合。不管是对接口响应、状态还是一组业务实体只要它们有可能出现在同一个变量里我第一件事就是给它们加一个type、kind、status之类的判别字段然后所有判断都走switch。这个习惯让代码的可读性和可维护性提升非常明显——新增一个分支时编译器会逼着你去补齐所有遗漏。相比之下用多个if (typeof ...)串联的代码看半天都不知道到底有多少种状态。第二条类型缩小写不出来的地方往往不是 TS 笨而是你的数据流设计有问题。比如一个值在函数 A 里判断过了传进函数 B 又成了联合类型——这多半说明函数 B 的入参类型定义得太宽了。把函数签名改精确比在函数体内做十次窄化划算得多。我把这种思路叫“让类型边界更靠近数据入口”整体下来as的数量能少一个量级。5.3 一段可以直接抄走的组合方案最后给一套我在新项目里固定使用的模式覆盖从外部数据到内部状态处理的完整链路// 1. 定义可辨识联合 type Views | { kind: list; items: string[] } | { kind: detail; id: string }; // 2. 写一个自定义守卫做入口校验 function isViews(value: unknown): value is Views { if (typeof value ! object || value null) return false; const v value as Recordstring, unknown; if (v.kind list) { return Array.isArray(v.items) v.items.every((i) typeof i string); } if (v.kind detail) { return typeof v.id string; } return false; } // 3. 入口断言 function parse(raw: unknown) { if (!isViews(raw)) throw new Error(非法视图数据); return raw; } // 4. 业务里直接 switch function render(view: Views) { switch (view.kind) { case list: return view.items.join(, ); case detail: return 详情${view.id}; } }这套组合的价值在于链路最前端把所有类型不确定性问题全解决掉后面的业务代码既不需要as也不需要反复if判状态类型提示本身就像一份实时文档。我在实际项目中把这种模式用在各种解析模块里从前端过滤接口响应到处理 WebSocket 推送消息效果都很好。最后再分享一个小技巧给自定义守卫函数命名时统一用isXxx的动词形式然后在开发模式下故意传几个反例调用一遍确认它真的能拦下来。别看这步简单它能帮你省掉不下一半的线上排查时间。
