先讲一个我亲身踩过的场景。当时我在维护一个数据查询接口，前端会把筛选条件传过来，早期代码把所有筛选条件当成同一种固定结构处理，类型定义也只写了其中一个形态。结果线上告警直接炸了，代码里trim()方法报了 TypeError——因为实际传进来的根本不是对象，而是一个字符串。排查到最后才发现，这个参数既可能是字符串，也可能是解析后的对象，甚至还可能是 null，但类型定义里只声明了其中一种情况，TypeScript 完全没拦住。
这个事之后，我开始认真梳理 TypeScript 的高级类型，其中联合类型和类型别名是绕不开的两个基础能力。如果你已经会写 interface 和普通函数签名，但面对"一个值可能有多种形态"这种需求时，只能靠any或者一堆运行时 if 硬扛，那这篇内容就是给你准备的。我会从为什么需要这两个语法说起，讲到类型收窄、可辨识联合、泛型别名、递归别名这些进阶用法，最后复盘我在真实项目里踩过的坑。全程使用 TypeScript，代码可以直接复制到项目里跑。
1. 一次线上事故引发的思考：多个可能值到底怎么建模
1.1 当时的代码与事故现场
先还原一下出错的那段逻辑。模拟项目X 的接口层有一个函数，接收参数 rawFilter，本意是"用户提交的筛选条件"。我早期写的类型是这样的：
function parseFilter(rawFilter: FilterObject) { // 直接假设 rawFilter 一定是 FilterObject return rawFilter.keywords.trim(); }但实际调用方有时候传的是已经序列化好的字符串，有时候传的是 null，只有一部分情况真的传了 FilterObject 对象。于是当传进来的是字符串时，trim()方法根本不存在，运行时直接抛错。
这里最值得注意的一点是：这个函数在本地联调阶段从来没有出过问题，因为本地测试数据永远是"正确"的。测试时候填的都是对象，自然一切正常。上线之后真实流量一进来，各种形态的数据全冒出来了，类型检查又没拦住，问题才暴露。这也是很多前端和全栈项目里最常见的一类线上事故：类型定义没写全，编译期安然无恙，运行期措手不及。
1.2 问题的本质：类型世界与运行时世界的落差
这个事故的本质，不是代码逻辑写错了，而是类型定义没有如实描述"参数可能是什么"。一句话解释就是：TypeScript 在编译期提供的类型检查，本质上是在帮你模拟运行时的可能性空间。如果类型定义只描述了其中一种情况，那编译器就只会按照这一种情况去检查，其他情况全部成为漏网之鱼。
JavaScript 的运行时世界里，一个变量在生命周期的不同时刻，完全可能从字符串变成对象再变成 null，这在动态语言里是常态。TypeScript 的联合类型就是为了解决这个落差而设计的：它允许你在类型层面诚实地声明"这个值可能是 A，也可能是 B，还可能是 C"。这样一来，编译器就会强制你在使用值之前先搞清楚它的具体形态，从而把很多运行时错误提前到编译期暴露。
2. 联合类型与类型别名的语法解剖
2.1 联合类型：用 | 表达“可能之一是”
联合类型的语法非常直观，用竖线|把多个类型连接起来：
type Input = string | number | null;读作：Input 这个类型，可能是 string，可能是 number，也可能是 null。这里需要注意，它和日常语言里的"或者"不太一样，它不是运行时的二选一逻辑，而是编译期的"可能性集合声明"。类型本身是集合，string | number意味着这个值的实际运行时形态一定落在集合里的某个成员上。
联合类型的成员可以是任意类型，包括对象类型、数组类型、字面量类型，甚至是别的联合类型。当两个联合类型再组合成新的联合类型时，TypeScript 会自动去重：
type A = string | number; type B = number | boolean; type C = A | B; // string | number | boolean这里 C 不会出现两个 number，因为重复的成员在集合里没有意义。这个自动去重的行为看起来简单，但理解它有助于后面理解条件类型、Exclude这些更复杂的工具类型。
2.2 类型别名：给复杂类型一个名字
单纯写string | number | null确实不长，没问题。但一旦联合的成员变多，或者某个联合类型要在几十个函数里反复使用，每次都展开写一遍就很容易出错。这时候就需要类型别名：
type UserId = string | number; type RequestState = "idle" | "loading" | "success" | "error";类型别名本质上就是给一个类型"起名字"，后续任何地方都可以直接引用。它有四个直接收益：一是可读性，函数签名里看到UserId比看string | number直观得多；二是可维护性，如果以后 UserId 要改成只允许 UUID 字符串，只需要改一处；三是自文档化，类型名本身就在表达业务语义；四是复用性，同一个别名可以被 import 到任意模块。
关于类型别名和 interface 怎么选，我个人的经验是：定义对象的形状优先用 interface，定义联合类型、函数签名、元组、以及需要泛型组合的复杂类型时用 type 别名。两者可以混用，interface 也可以通过继承来组合，不必把它们当成水火不容的对立关系。
2.3 字面量类型联合：让字符串不再“放飞自我”
联合类型最常见的落地场景，是和字面量类型配合。字面量类型就是把具体值当作类型来用：
type Status = "pending" | "processing" | "done";一旦声明了 Status，你就不可以随便赋一个"finished"或者"Pending"，编译器会直接报错。很多团队早期会把所有状态字段写成 string，结果一个状态值在代码里出现十几种写法，大小写不一致、拼写不一致，改起来痛不欲生。用字面量联合以后，编辑器会给出自动补全提示，状态值写错也会在编译期被拦截。
这里有一条我从实践里总结出来的经验：字面量联合类型的值，尽量和对外协议保持一致。比如后端返回的状态是"success"，那前端类型里也写"success"，不要自己翻译成"ok"再写一层映射，否则维护成本直接翻倍。前后端联调最怕的就是各自定义一套术语，最后在边界上做数据翻译，纯属给自己挖坑。
3. 类型收窄：联合类型真正的另一半
3.1 用 typeof、in、instanceof 逐渐缩小范围
联合类型只是声明了"可能是什么"，当你真正要访问成员属性时，TypeScript 必须先确定当前这个值具体是哪一个成员，否则它不会让你随便用。这就是类型收窄（Type Narrowing）。看个例子：
type Input = string | string[]; function getLength(input: Input) { if (typeof input === "string") { return input.length; // 这里 input 被收窄为 string } return input.length; // 这里 input 被收窄为 string[] }typeof是最常用的收窄手段，但并不是唯一的选择。判断对象属性是否存在用in，判断实例关系用instanceof，判断数组用Array.isArray，判断可辨识字段用等值比较。TypeScript 的控制流分析会随着 if 分支自动更新变量的"当前类型"，这就是为什么上面代码在不同分支里，变量的类型会自动变化。
实际工作中，我建议把收窄逻辑封装成独立的类型守卫函数，尤其是同一个联合类型被多个函数使用的时候：
function isStringArray(input: unknown): input is string[] { return Array.isArray(input) && input.every((item) => typeof item === "string"); }返回类型里的input is string[]就是类型谓词语法。它告诉 TypeScript：只要这个函数返回 true，传入参数就被视为 string[]。这样收窄逻辑可以复用，语义也更清晰。类型谓词的坑在于，它的合法性依赖你的实现是否正确，TypeScript 不会去验证断言本身，所以在写类型守卫时一定要保证逻辑没有漏洞。
下面这张表可以快速对照不同收窄手段的适用场景：
| 收窄手段 | 语法 | 适用场景 |
|---|---|---|
| typeof | typeof x === "string" | 判断基础类型：string、number、boolean、undefined |
| Array.isArray | Array.isArray(x) | 收窄数组类型 |
| in | "key" in obj | 判断对象是否包含某个属性 |
| instanceof | x instanceof Date | 判断类实例 |
| 等值比较 | switch (x.kind) | 可辨识联合的最常见方式 |
3.2 可辨识联合：一个字段区分所有分支
如果联合类型的每个成员都是对象，并且每个对象都有一个相同的字段用来区分彼此，这就叫可辨识联合（Discriminated Union）。这个模式是我在业务代码里用得最多的联合类型写法。
type ApiResult = | { status: "success"; data: User; timestamp: number } | { status: "error"; code: number; message: string } | { status: "loading" };看到规律了吗？每个成员对象里都有一个 status 字段，它的字面量类型互不相同。当你在代码里判断result.status === "success"之后，TypeScript 会自动把 result 收窄到第一个分支，此时访问 data 和 timestamp 完全合法；如果走到了 error 分支，访问 data 属性就会直接报错，因为那个分支的成员对象里根本没有 data。
可辨识联合最大的价值是：它把"每一种可能形态"和"标识字段"绑定在一起，让类型系统可以跟着判断逻辑自动精确缩小范围，几乎不需要额外的手动断言。任何涉及多状态、多分支的业务模型，比如请求状态、消息类型、表单步骤、页面节点，都适合用可辨识联合建模。
3.3 用 never 做穷尽性检查
可辨识联合配合 switch 使用，有一个非常实用的技巧：用 never 做穷尽性检查。
function handleResult(result: ApiResult) { switch (result.status) { case "success": return result.data; case "error": return `${result.code}: ${result.message}`; case "loading": return null; default: const _exhaustive: never = result; return _exhaustive; } }default 分支里把 result 赋给一个 never 类型的变量。如果有一天你给 ApiResult 增加了一个新分支，比如加了一个"timeout"，但忘了在 switch 里处理它，TypeScript 会在 default 分支报错：因为 result 此时是{ status: "timeout" }，不是 never，赋给 never 类型不合法。
这个技巧把"未来新增分支时漏处理"这种极其容易发生的错误，从运行时暴露提前到了编译期。我愿称它为高级类型里性价比最高的一个技巧：一行代码，永久保障 switch 分支的完整性。
4. 类型别名的进阶玩法：泛型、递归与跨场景复用
4.1 泛型别名：函数与对象的类型参数化
类型别名可以配合泛型使用，组合出非常强大的工具类型。最典型的是这种"成功/失败"的统一返回值：
type Result<T> = | { ok: true; value: T } | { ok: false; error: string };这样定义一次，项目中所有接口返回的数据都能复用。不同的接口只需要传入不同的 T，就能得到对应的完整类型：
type UserResult = Result<User>; type OrderResult = Result<Order>;在调用方配合收窄使用：
function loadUser(): UserResult { // 模拟请求 } function showUser(result: UserResult) { if (result.ok) { console.log(result.value.name); } else { console.error(result.error); } }泛型别名解决的核心问题，是"结构相同但内容类型不同"的一类场景。比如分页响应、请求包装、校验结果，这些结构的骨架是不变的，只有里面的数据类型在变。把它们抽象成泛型别名，可以在不牺牲类型安全的前提下大幅减少重复类型定义。
4.2 递归别名：描述树形 JSON
泛型之外，另一个容易让人眼前一亮的是递归类型别名。它可以用来描述任意层级的 JSON 数据结构：
type JsonValue = | string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };注意这里 JsonValue 在自己的定义里引用了自己，用来表达"值可以是任意嵌套的数组或对象"。这种类型在处理 JSON 解析、配置项、目录树、评论区回复楼层时特别有用，既保留了结构信息，又允许无限嵌套。
我举一个实际场景：某跨平台系统里有一个动态渲染配置，配置项里某个字段可能是字符串，可能是数字，也可能是一个子树对象。如果把它定义成Record<string, unknown>，所有子字段的类型信息都丢了；如果用any，就更不用说了。用 JsonValue 这个递归别名，既能保证任意嵌套结构合法，又能在收窄时逐层保留类型信息。
4.3 多个别名组合成领域模型
类型别名的价值不只在单一类型上，更在于多个别名可以组合成完整的领域模型。简单示例：
type ID = string | number; type Timestamp = number; type OrderStatus = "created" | "paid" | "shipped" | "completed"; type OrderItem = { productId: ID; quantity: number; price: number; }; type Order = { id: ID; status: OrderStatus; createdAt: Timestamp; items: OrderItem[]; };整个订单模型由多个别名拼装而成，每个别名表达一个清晰的业务概念。相比把所有字段一次性写在一个大 interface 里，这种模块化组合让人更容易理解，也更容易扩展，哪个部分需要调整就只改对应的别名，不影响其他模块。
5. 复盘：我在真实项目里踩过的联合类型坑
5.1 联合类型里的对象属性访问：为什么报错
新手最容易碰到的坑：定义了一个联合类型，成员里有几个对象都有 name 属性，但直接访问却报错。
type A = { name: string; age: number }; type B = { name: string; email: string }; type Person = A | B; function logName(p: Person) { p.name; // 这个能访问 p.age; // 这个大概率报错 }答案是：name能访问，因为两个成员都有 name；age大概率报错，因为 B 分支里没有 age。理解这个行为很关键：联合类型的属性访问规则是"取交集"，只有每个成员都有的属性才能直接访问。
这其实是合理的设计，它强迫你去做收窄。如果你确定当前一定是某个分支，就用可辨识联合或者类型守卫收窄，而不是硬访问。很多开发者遇到这种情况会直接加as any，这等于亲手关掉了类型保护，等于又回到事故现场。
5.2 可辨识联合失效的典型原因
可辨识联合最怕的是：判别字段不一致。我曾经在一个消息处理模块里踩过这个坑。起初两个成员对象的判别字段都叫 type，后来某次重构，有人把其中一个改成了 kind，另一个还是 type。结果 switch (msg.type) 分支全部失效，TypeScript 不再自动收窄，还出现了一堆诡异的类型报错。
排查了大半天才发现是字段名不统一。这种问题的隐蔽之处在于，只要可辨识字段没有被强制约束，它反而会在"看起来能编译"的情况下悄然失效。我的经验是：可辨识联合的判别字段，一定要统一命名，并且尽量放在对象字面量的第一个位置，方便 code review 时一眼看到。如果项目规模大，还可以约定一套命名规范，比如 api 相关用 status，消息相关用 type，不要混用。
另外一个容易踩的点是判别字段必须是字面量类型。如果你把判别字段声明成普通的string，那这个联合类型就不再是可辨识联合，TypeScript 无法通过等值比较自动收窄，因为 string 类型的等值比较不能排除任何分支。
5.3 undefined 和 null 混进联合类型的纠缠
另一个高频问题出在 undefined 和 null。比如你有这样一个类型：
type MaybeUser = User | undefined;收窄时习惯性只判断了 null，结果 undefined 的情况直接漏过去了。反过来也一样。实际项目里接口数据经常同时存在 null 和 undefined 两种"空"，我建议在定义联合类型时先想清楚：这个空值场景到底该用 null 还是 undefined？还是两者都有可能？如果两者都可能，就明确写User | null | undefined，然后收窄时用== null一次性覆盖两者，或者用可选链?.兜底。
还有一个相关经验：不要随手把里层某个字段的类型改成Something | undefined来"骗"过编译器。一旦你这么做了，所有调用方都被迫处理一种事实上不存在的空值，代码里会冒出大量无意义守卫。真正该做的是回到数据源头，看看接口到底会不会返回这个字段，而不是在类型层面用| undefined掩盖问题。
5.4 一个让同事排查两小时的推断问题
最后分享一个我印象最深的排查过程。某跨平台系统的消息解析函数，传入参数是string | ParsedMessage，内部逻辑先判断typeof input === "string"，是的话就 JSON.parse，否则直接使用原对象。问题在于 JSON.parse 的返回值被推断成了 any，后续所有属性访问都不再被检查，导致一处字段拼写错误直到运行时才暴露。
完整的排查链路是这样的：同事先看到运行时报错，检查业务逻辑，发现逻辑没写错；然后怀疑 JSON.parse，但单测里用真实 JSON 字符串测又没问题；最后翻到类型定义，才发现入口参数在某次重构后被改成了联合类型，而 JSON.parse 返回的 any 悄悄绕过了所有检查。修复方案是把解析结果重新断言成明确的联合类型，并且给解析函数加上类型守卫。
这个坑的教训是：联合类型只是起点，收窄之后如果调用了返回宽泛类型的方法，类型保护会被全部击穿。所以每次在联合类型分支里调用 JSON.parse、Object.entries 这类返回any或宽泛类型的函数时，都要想想返回值是否已经失去了类型信息。必要时显式断言一次，别让 any 顺着调用链往下传。下面的表是我整理出的高频坑位和应对方式：
| 坑位 | 现象 | 应对 |
|---|---|---|
| 属性访问报错 | 访问非共有属性 | 用可辨识联合或类型守卫收窄 |
| 可辨识字段不一致 | switch 分支不自动收窄 | 统一判别字段命名，放在第一位 |
| 判别字段为普通 string | 等值比较不触发收窄 | 判别字段必须是字面量类型 |
| 收窄返回值是 any | 类型检查全部失效 | 显式断言，加类型守卫 |
| null/undefined 漏判 | 运行时访问属性报错 | 明确空值语义，用== null兜底 |
6. 实践建议：什么时候用联合类型，什么时候绕开它
6.1 优先用可辨识联合建模多状态
任何存在明确状态集合的业务模型，我的第一选择都是可辨识联合。看过太多散落的 if-else 加各种非空断言的写法，状态一变就要改好几处分支，而且很难保证漏改。可辨识联合把状态和该状态下的数据结构强绑定，改一处不会漏另一处，新增状态也会被穷尽性检查提醒。相比"自由"的 if-else，这种强约束反而让人安心。
6.2 字面量联合替代大部分字符串枚举
如果你只是为了约束几个固定值，直接用字面量联合即可，不需要引入额外的枚举对象。字面量联合的好处是类型定义就是业务字典，编辑器自动补全体验也好。只有需要运行时遍历值、或者需要在前后端共享枚举定义时，再考虑真正的枚举对象，避免两端手写两套同样的枚举。
6.3 别把不相关的类型硬凑成联合
联合类型不是万能的。如果两个类型在业务上完全没有交集，只是恰好字段长得像，硬把它们并成联合类型反而会让收窄逻辑变得非常复杂。这种时候拆成两个独立类型，在调用方分别处理，可读性会好得多。联合类型表达的是"同一个业务语义下的多种可能形态"，不是"随便什么类型的大杂烩"。语义不清晰时，先用类型别名把每个成员命名好，再组合，比直接写一堆匿名对象字面量强十倍。
6.4 写在最后的个人体会
我写联合类型时有一个习惯：每个成员都单独用 type 别名定义出来，尤其在分支超过三个的情况下。这样 switch 和收窄代码里引用的是有名字的类型，而不是一长串匿名对象，报错信息也会清晰很多，一眼能看出问题出在哪个分支上。这个习惯看着不起眼，但在类型复杂起来之后，省下的排查时间相当可观。
联合类型和类型别名看似是两个简单语法，但真正用好它们的核心，是建模思路的转变：从"盯着一个类型写代码"变成"面向一组可能集合编程"。一旦你习惯用集合的视角去定义类型，很多运行时才暴露的边界问题，都会在编译期提前现出原形。
