联合类型与类型断言实战：TypeScript-New-Handbook 帮你消灭 80% 类型报错

联合类型与类型断言实战：TypeScript-New-Handbook 帮你消灭 80% 类型报错

【免费下载链接】TypeScript-New-HandbookIncubation repository for the new TypeScript handbook 🐣项目地址: https://gitcode.com/gh_mirrors/ty/TypeScript-New-Handbook

如果你正在被 TypeScript 联合类型和类型断言相关的报错折磨，那么这份基于 TypeScript-New-Handbook 的实战指南就是为你准备的。TypeScript-New-Handbook 是新一代 TypeScript 官方手册的孵化仓库，在chapters/目录下系统收录了联合类型、类型收窄、类型断言等核心章节。跟着这份手册的脉络学习，配合少量代码示例，你可以快速理解类型系统的底层逻辑，消灭日常开发中大约 80% 的类型报错。📘

为什么 80% 的类型报错都源于"类型不清"

在真实项目中，类型报错往往不是因为你不会写 TypeScript，而是因为值到底属于哪个类型这件事没有说清楚。最常见的两类场景是：

• 一个变量可能是多种类型之一，比如接口返回的id可能是数字也可能是字符串；
• 你比 TypeScript 更清楚某个值的真实类型，但编译器却"不相信"你。

这两类问题对应的正是联合类型（Union Types）与类型断言（Type Assertions）。把这两个概念吃透，就等于掌握了解决大多数类型报错的钥匙。🧩

联合类型入门：一个参数，多种可能

联合类型允许一个值属于多种类型中的任意一种，语法上使用|分隔。手册在 Everyday Types.md 的 "Union Types" 一节给出了经典示例：

function printId(id: number | string) { console.log("Your ID is: " + id); } printId(101); // OK printId("202"); // OK printId([1, 2]); // Error

这里number | string就是联合类型，它的每个成员称为 union 的 member。联合类型的核心规则是：你只能对联合类型执行对所有成员都有效的操作。例如id.toUpperCase()会报错，因为number没有这个方法。

联合类型使用技巧：类型收窄是消灭报错的关键

既然不能直接调用成员专属方法，该怎么处理联合类型呢？答案是类型收窄（Narrowing）。TypeScript 会根据代码结构自动推断出更具体的类型，这正是 Narrowing.md 整章讲解的内容。常用的收窄手段包括：

• typeof类型守卫：判断基本类型最直接的方式，typeof id === "string"之后，分支内id自动变成string；
• Array.isArray判断：区分数组与其他类型；
• 真值收窄（Truthiness Narrowing）：利用if (strs)排除null和undefined；
• in与instanceof收窄：判断对象属性或实例归属；
• 等式收窄：通过===、!==、switch精确锁定类型。

来看一个典型例子：

function printId(id: number | string) { if (typeof id === "string") { // 这里 id 是 string console.log(id.toUpperCase()); } else { // 这里 id 是 number console.log(id); } }

你不需要写任何额外的类型标注，TypeScript 会自动完成收窄。这就是消灭 80% 类型报错的第一把钥匙：用类型守卫代替any，让类型跟着逻辑走。🗝️

高级技巧：用可辨识联合管理复杂状态

当联合类型的每个成员都包含一个字面量类型的公共属性时，就构成了可辨识联合（Discriminated Union）。这是手册 Narrowing.md 中最实用的进阶技巧，非常适合表达加载状态、消息事件等场景：

type Shape = | { kind: "circle"; radius: number } | { kind: "square"; sideLength: number };

只要公共属性kind是字面量类型，TypeScript 就能在每个分支中精确收窄出对应的成员，配合never类型做穷尽性检查（Exhaustiveness Checking），新增分支漏处理时编译器会直接报错，从源头杜绝状态遗漏。✨

类型断言实战：正确的时机与正确的姿势

有些场景下，你比 TypeScript 更了解真相。比如从 DOM 中取元素，getElementById返回类型偏宽泛，此时可以用类型断言指定更具体的类型：

const myCanvas = document.getElementById("main_canvas") as HTMLCanvasElement;

Everyday Types.md 的 "Type Assertions" 一节明确指出两个关键点：

1. 断言只影响编译期，不会改变运行时行为，也不会做任何运行时检查，断言错误不会抛出异常；
2. TypeScript 只允许更具体或更宽泛的转换，直接"hello" as number会报错。如果确有需要，可以先用any或unknown过渡：

const a = expr as any as T;

类型断言 vs 类型守卫：什么时候该用哪个

很多新手分不清两者的边界，这里给你一张决策清单：

一句话总结：能用收窄就用收窄，断言是最后手段。类型断言是"告诉编译器相信我"，而类型守卫是"让编译器自己证明"。配合 More on Functions.md 中关于函数重载与泛型的章节，你就能在绝大多数场景下写出既安全又简洁的代码。🛡️

学习路线：用 TypeScript-New-Handbook 从入门到实战

如果你想让这套能力真正内化，建议按下面的顺序阅读手册源码，每一步都有配套的实战案例：

1. 打基础：从 Basics.md 理解类型系统设计初衷，再精读 Everyday Types.md 掌握联合类型、类型别名与类型断言的完整语法；
2. 学收窄：完整过一遍 Narrowing.md，重点练习typeof、真值、等式、in、instanceof六种收窄手段与可辨识联合；
3. 拓边界：结合 Object Types.md 与 More on Functions.md，把联合类型应用到对象和函数场景；
4. 读报错：遇到看不懂的错误时，翻一翻 Understanding Errors.md，学会从错误信息反推类型问题。

💡 小提示：仓库的docs/chapters/目录下还有已编译好的 HTML 版本（如docs/chapters/narrowing/index.html），不想看 Markdown 源码时可以直接在浏览器里阅读，体验更流畅。

总结

联合类型负责"表达多种可能"，类型收窄负责"在分支中锁定真相"，类型断言负责"在确信时跳过检查"——三者配合，足以覆盖日常开发中绝大部分类型报错场景。TypeScript-New-Handbook 把这套知识体系讲得循序渐进、示例清晰，堪称新手消灭类型报错的最快路径。现在就打开 Narrowing.md 开始实战吧，你的 80% 类型报错，将从这一页开始消失！🚀

【免费下载链接】TypeScript-New-HandbookIncubation repository for the new TypeScript handbook 🐣项目地址: https://gitcode.com/gh_mirrors/ty/TypeScript-New-Handbook