TypeScript重载函数匹配报错：类型正确却提示无匹配重载？

先看你遇到的代码场景：

定义了一个重载函数f：

const f: {
  (x: number): void;
  (x: string): void;
} = (x: number | string) => {};

同时有一个混合类型数组：

const arr = [1, "1"]; // 类型推断为 (number | string)[]

单独调用f(1)或f("1")都正常，但调用f(arr[0])时却报错：No overload matches this call.

原因分析 #

TypeScript的重载匹配逻辑是逐个匹配重载签名，要求传入的参数类型必须完全匹配其中某一个签名，而不是只要参数类型属于签名的联合集合就行。

• 当你直接传1时，参数类型是number，能精准匹配第一个重载签名；传"1"时类型是string，匹配第二个签名，所以都没问题。
• 但arr[0]的类型是number | string——这个联合类型既不是纯number，也不是纯string，没有任何一个重载签名能完全接纳它，因此触发报错。

这里要注意：函数的实现虽然接受number | string，但重载签名是对外暴露的类型约束，TypeScript会优先按照重载签名做类型检查，而不是看实现的类型。

解决方案 #

你可以根据需求选择以下几种方式解决：

1. 添加联合类型的重载签名
   给f新增一个接受number | string的重载，让联合类型参数能匹配到对应的签名：

   const f: {
     (x: number): void;
     (x: string): void;
     (x: number | string): void; // 新增联合类型重载
   } = (x: number | string) => {};
   

2. 类型窄化
   在调用前通过类型断言或条件判断，把arr[0]的类型窄化为具体的number或string：

   // 类型断言
   f(arr[0] as number);
   f(arr[0] as string);
   
   // 条件判断窄化
   const val = arr[0];
   if (typeof val === 'number') {
     f(val);
   } else {
     f(val);
   }
   

3. 直接使用联合类型定义函数（替代重载）
   如果你的函数不需要针对number和string做不同的逻辑处理，完全可以不用重载，直接定义成接受联合类型的函数：

   const f = (x: number | string): void => {};
   

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