TypeScript函数重载为何无法兼容联合类型参数？

问题场景 #

在TypeScript手册《Writing Good Overloads》章节的示例中，有如下重载函数：

function len(s: string): number;
function len(arr: any[]): number;
function len(x: any) {
  return x.length;
}

单独传入字符串len("");或数组len([0]);时调用正常，但传入由三元表达式生成的string | number[]联合类型值len(Math.random() > 0.5 ? "hello" : [0]);时，会触发编译错误：

No overload matches this call.
  Overload 1 of 2, '(s: string): number', gave the following error.
    Argument of type 'number[] | "hello"' is not assignable to parameter of type 'string'.
      Type 'number[]' is not assignable to type 'string'.
  Overload 2 of 2, '(arr: any[]): number', gave the following error.
    Argument of type 'number[] | "hello"' is not assignable to type 'any[]'.
      Type 'string' is not assignable to type 'any[]'.

官方给出的解决方案是将参数改为联合类型：

function len(x: any[] | string) { return x.length; }

原因解析 #

TypeScript的重载匹配逻辑是逐个检查每个重载签名，要求传入的参数类型完全匹配某一个重载的参数类型。对于string | number[]这种联合类型，它既不是纯string类型，也不是纯any[]类型，所以无法匹配任何一个重载签名，最终触发错误。

重载的设计初衷是为不同的独立输入类型提供明确的函数签名，而非处理多个类型的联合输入场景。而直接使用联合类型作为参数时，TypeScript会自动检查联合类型的每个成员是否都符合函数的逻辑要求（这里string和any[]都具备length属性），因此可以正常通过类型校验。

版本与未来优化说明 #

这个问题和TypeScript的版本无关，重载的匹配逻辑从设计之初就是如此。目前TypeScript团队没有计划修改重载的匹配规则，因为重载的核心定位是处理单一类型的输入分支，而联合类型的场景本身就有更简洁、更合适的实现方式——官方在手册中也明确建议，这种覆盖多个类型的场景优先使用联合类型而非重载。

内容的提问来源于stack exchange，提问作者Islam Y-