递归导致TypeScript重载函数类型检查失效问题问询

先看这两个几乎一样的TypeScript函数：

function transform1 <T extends string>(value: T): T;
function transform1 <T extends string>(value: T[]): T[]; // 报错：无法返回0
function transform1 <T extends string>(value: T | T[]) {
  if (Array.isArray(value)) {
    return 0;
  } else {
    return value[0];
  }
}

function transform2 <T extends string>(value: T): T;
function transform2 <T extends string>(value: T[]): T[];
function transform2 <T extends string>(value: T | T[]) {
  if (Array.isArray(value)) {
    return 0; // 居然没警告？
  } else {
    return transform2([value])[0];
  }
}

核心问题 #

为什么第二个函数里返回0不会触发类型警告？唯一区别是第二个函数用了递归调用transform2，而且必须给实现体显式标注返回类型T | T[]才会报错？

原因解析 #

1. 重载函数的基础检查逻辑
   TypeScript对重载函数的要求是：实现体的返回值必须能兼容所有重载签名的返回类型。

• 对于transform1，当处理数组分支时，重载签名要求返回T[]，但实际返回的0是number类型，完全不兼容T[]（T是string的子类型），所以直接报错。

2. 递归重载的类型检查妥协
   transform2的特殊点在于递归调用：

• 非数组分支里调用transform2([value])，TypeScript会匹配第二个重载签名（参数是T[]），于是直接信任重载声明的返回值是T[]，不会去递归检查这个调用的实现体到底返回了什么。所以transform2([value])[0]被推断为T，符合第一个重载的返回要求。
• 而数组分支返回0时，TypeScript的类型检查器在处理递归重载的实现体时，没有严格验证这个返回值是否匹配T[]。这是因为递归场景下，TypeScript不会无限循环检查，只能优先信任重载签名的声明，从而跳过了对这个分支的类型校验，导致0没有触发错误。

3. 显式标注返回类型的作用
   如果给transform2的实现体显式标注返回类型T | T[]，TypeScript就会严格检查每个分支的返回值是否属于这个联合类型。此时0是number类型，和T | T[]（T为string子类型）完全不兼容，就会立刻报错。

内容的提问来源于stack exchange，提问作者k-tten