类型收窄

是什么，为什么存在

类型收窄是 TypeScript 在控制流的某个位置，把宽类型精化成更具体类型的过程。参数可以声明为 string | number，但在 typeof value === "string" 成立的分支中，编译器只把 value 当作 string。离开这条路径后，它会根据仍可到达该位置的分支重新计算类型。

这套机制解决了 联合类型（union type） 的操作安全问题。若一个值可能是字符串或数字，未经检查时只能使用两者共有的能力。守卫给编译器提供运行时证据，之后才能安全调用 toUpperCase() 或 toFixed()。

收窄同样用于 unknown、可空值、可选属性和状态对象。它常出现在 API 边界、事件处理、解析结果和错误处理代码中。开启 strictNullChecks 后，null 与 undefined 是独立类型，空值检查才能形成有意义的静态证明。

类型收窄不会修改数据，也不会把类型信息带入 JavaScript。typeof、相等比较和属性读取会在运行时执行，接口与联合类型则会被 类型擦除（type erasure） 。因此，外部数据必须经过真实检查，不能靠类型注解变得可信。

工作原理

一个变量同时有声明类型和当前位置的观察类型。声明类型决定整个作用域中允许赋入什么值；观察类型描述沿当前控制流还能到达这里的值。守卫只缩小观察类型，不会永久改写声明。

编译器为分支建立流事实。条件成立与不成立会产生不同事实，return、throw、break 等控制流终止会删除无法到达的可能性，多条路径汇合时则重新合并剩余类型。赋值也会产生新事实，所以同一个名称在相邻两行可以有不同的观察类型。

编译器理解的守卫

类型守卫（type guard） 是编译器能够用于收窄的运行时条件。不同检查提供的证据不同，不能互相替代。

真值检查也会收窄，但它回答的是 JavaScript 的真假值问题。if (value) 会排除 null 和 undefined，同时也让 0、NaN、""、0n 与 false 无法进入成立分支。若这些值在领域中有效，应明确检查空值。

相等比较可以关联两个变量。若 left 是 string | number，right 是 string | boolean，那么 left === right 成立时，两者只能同时为 string。这种结论来自两个联合类型的共同可能性，而不是比较操作进行了类型转换。

可达性、赋值与汇合

提前返回通常能让剩余路径更清楚。若数字分支已经 return，函数后面的同一参数就不再包含 number。这比在每个使用点重复类型断言更容易随联合类型变化而保持正确。

赋值后的观察类型来自实际赋入的值，但后续赋值仍按声明类型检查。一个声明为 string | number 的变量在赋入字符串后可以暂时观察为 string，稍后仍允许赋入数字。赋入布尔值则始终报错，因为它不属于声明类型。

路径重新汇合时，编译器合并每条可达路径的结果。若一个分支赋入字符串，另一个分支赋入数字，汇合处的观察类型重新成为 string | number。理解这个过程比背诵某个编辑器悬浮提示更可靠。

可辨识联合与穷尽性

可辨识联合（discriminated union） 让每个成员共享一个字面量字段，例如 status。检查这个字段会一起收窄对象和对应载荷，避免通过若干可选属性猜测当前状态。判别字段应稳定，不能同时承担普通可变数据的职责。

当所有成员都被排除后，剩余类型是 never。把默认分支中的值传给接受 never 的函数，就能把新增但未处理的成员变成编译错误。若默认分支直接返回通用文本，类型检查器无法提醒你补上新状态。

自定义谓词与断言函数

内置检查难以复用复杂结构验证时，函数可以返回 类型谓词（type predicate） ，例如 value is Command。成立分支保留 Command，不成立分支会排除它。编译器只检查谓词类型能否用于参数，不会证明函数体检查了签名承诺的每个字段。

断言函数（assertion function） 使用 asserts value is Type 或 asserts condition。函数正常返回后，调用方获得收窄结果；失败路径必须抛出或永不返回。它适合不可恢复的不变量，而普通无效输入通常更适合返回可辨识结果。

示例

下面四个程序依次展示内置守卫、赋值后的控制流、可辨识联合与 unknown 边界。每段代码都用 TypeScript 6 在 strict 模式下完成类型检查，并由本地 tsx 实际执行。

通过提前返回排除成员

第一个函数依次处理空值、字符串和 Date。前三条路径都已经返回，所以最后一行只剩 number。

value === null 必须先于宽泛的对象处理，因为 typeof null === "object"。这里用 instanceof Date 检查代码创建的实例；JSON 中的日期仍是字符串，不会因为类型注解自动变成 Date。

最后的数字分支没有 as number。它的安全性来自前面所有可达路径，而不是作者对编译器的指令。给 Input 增加新成员时，这一行会迫使实现重新处理分支。

赋值后保留收窄结果

字符串形式的基础地址先被转换并重新赋给 base。走出 if 后，两条路径上的 base 都是 URL，而箭头函数创建在最后一次赋值之后，因此可以继续使用这个收窄结果。

function makeJobUrls(base: string | URL, jobIds: number[]): string[] {
  if (typeof base === "string") {
    base = new URL(base);
  }

  // 箭头函数创建在 base 的最后一次赋值之后。
  return jobIds.map((jobId) => `${base.origin}/jobs/${jobId}`);
}

const urls = makeJobUrls("https://queue.example/api?legacy=1", [7, 11]);

for (const url of urls) {
  console.log(url);
}

https://queue.example/jobs/7
https://queue.example/jobs/11

参数的声明类型仍是 string | URL，所以更早的分支允许给它赋入 URL。控制流证明的是箭头函数创建时的观察类型。若任何嵌套函数还会给 base 赋值，编译器就不能继续依赖这份证明。

生产代码中常把稳定结果另存为 const normalizedBase = base。这不仅方便编译器，也明确告诉读者后续回调依赖哪一个不会重新赋值的值。

用判别字段驱动状态处理

每个任务状态都有同一个 status 字段，但载荷不同。switch 的每个分支只能访问对应成员的字段，默认分支则要求已经没有剩余成员。

type JobState =
  | { status: "queued"; position: number }
  | { status: "running"; worker: string }
  | { status: "failed"; reason: string }
  | { status: "done"; artifact: string };

function assertNever(value: never): never {
  throw new Error(`Unhandled state: ${JSON.stringify(value)}`);
}

function summarize(state: JobState): string {
  switch (state.status) {
    case "queued":
      return `queued:${state.position}`;
    case "running":
      return `running:${state.worker}`;
    case "failed":
      return `failed:${state.reason}`;
    case "done":
      return `done:${state.artifact}`;
    default:
      return assertNever(state);
  }
}

const states: JobState[] = [
  { status: "queued", position: 2 },
  { status: "running", worker: "runner-3" },
  { status: "done", artifact: "build-91.zip" },
];

for (const state of states) {
  console.log(summarize(state));
}

queued:2
running:runner-3
done:build-91.zip

如果加入 { status: "paused"; until: string } 却没有新增 case，assertNever(state) 会收到 paused 成员并产生类型错误。这项检查只覆盖静态联合；未经验证的外部对象仍可能带着任意 status 到达运行时。

为每个成员保留专属必填字段比堆叠可选字段更安全。{ status: string; position?: number; worker?: string } 无法表达哪个载荷与哪个状态同时成立，收窄也就不能恢复这层关系。

从 unknown 收窄到领域联合

最后一个例子把 JSON 解析结果立即放进 unknown。谓词先验证非空、非数组对象，再检查判别字段和每个分支所需的载荷。

type Command =
  | { kind: "retry"; attempts: number }
  | { kind: "cancel"; reason: string };

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function isCommand(value: unknown): value is Command {
  if (!isRecord(value)) return false;

  return (
    (value.kind === "retry" &&
      typeof value.attempts === "number" &&
      Number.isInteger(value.attempts) &&
      value.attempts >= 0) ||
    (value.kind === "cancel" && typeof value.reason === "string")
  );
}

function decodeCommand(raw: string): Command | undefined {
  try {
    const value: unknown = JSON.parse(raw);
    return isCommand(value) ? value : undefined;
  } catch {
    return undefined;
  }
}

for (const raw of [
  '{"kind":"retry","attempts":0}',
  '{"kind":"cancel","reason":"duplicate"}',
  '{"kind":"retry","attempts":"3"}',
  "not json",
]) {
  const command = decodeCommand(raw);
  console.log(command ? command.kind : "rejected");
}

retry
cancel
rejected
rejected

"kind" in value 本身不够，因为它不验证值是否是允许的字面量，也不验证关联载荷。isCommand() 的实现与签名必须同步变化；新增联合成员时，谓词、处理函数与测试都要一起更新。

捕获 JSON.parse() 的语法错误是边界契约的一部分。成功解析只说明文本是合法 JSON，不说明得到的对象符合 Command。这两类失败应分别被测试，即使接口最后都返回 undefined。

陷阱

用真值代替空值检查

修复： 只想排除空值时，写 value !== null、value !== undefined 或 value != null。为 0、空字符串和 false 各写一个边界测试，确认它们是否应被保留。

让守卫承诺超过检查内容

修复： 从 unknown 开始，检查容器、判别字段、必填字段和业务约束。若函数只回答较窄的问题，就返回 boolean 或声明一个与实际证据相符的更小类型。

把类型断言当作收窄

修复： 外部数据先赋给 unknown，再通过守卫或验证器产生领域类型。as 只应用在已有独立运行时保证、而检查器无法表达该保证的狭窄位置。

在可变边界后复用旧证明

修复： 把真正需要的已收窄值复制到 const 局部变量，再交给回调。检查从守卫到使用之间的每个写入点，不要只依赖编辑器在某一行显示的类型。

用宽泛默认分支隐藏新成员

修复： 在必须穷尽的分支中把剩余值交给 assertNever()。若协议确实允许未知外部状态，应先在解码边界把它建模为明确成员，而不是让内部联合悄悄变宽。

延伸阅读

• TypeScript Handbook：类型收窄
• TypeScript 5.4：最后赋值之后闭包中的收窄保留
• TypeScript TSConfig：strictNullChecks
• TypeScript 2.0：基于控制流的类型分析