TypeScript函数重载传入联合类型参数报错原因咨询

核心报错原因 #

• 重载匹配规则是 「单签名精确匹配」，而非 「多签名范围合并」
  TypeScript 处理函数重载调用时，会按顺序逐个比对公开的重载签名，要求传入的参数类型完全符合某一个重载的入参类型要求，而不是判断入参是否能被所有重载入参类型的并集覆盖。你传入的string | number联合类型，既不满足第一个重载的string类型要求（联合包含 number 无法分配给 string），也不满足第二个重载的number类型要求（联合包含 string 无法分配给 number），因此所有重载匹配失败抛出错误。
• 重载的实现签名对外不可见
  写在所有重载最后、包含实际逻辑的函数签名，仅用于 TypeScript 内部校验重载实现的逻辑合法性，完全不会暴露给外部调用方。所以哪怕你的实现写了arg: any可以兼容联合类型，外部调用时也感知不到这个实现签名的存在。

对 TypeScript 重载特性的理解 #

这个设计是 TypeScript 故意为之：函数重载的核心作用是定义离散、明确的合法调用形式，而不是自动合并所有可能的参数类型。如果你的场景确实需要支持string | number联合类型入参，只需要新增对应的重载签名即可：

export function fn(arg: string): void;
export function fn(arg: number): void;
// 新增联合类型重载即可解决报错
export function fn(arg: string | number): void;
export function fn(arg: any) {
    console.log(arg);
}

之所以 TypeScript 不默认把多个重载的参数类型自动合并为联合对外暴露，是因为重载的场景远不止单参数类型不同：很多时候重载的参数数量、参数位置、返回值类型都会有差异，自动合并会破坏重载的严格性，导致错误的类型推断结果。

内容的提问来源于stack exchange，提问作者Bruno