为什么传入any调用TS重载函数的返回类型与ReturnType获取结果不同？

底层原因 #

该现象是TypeScript的重载匹配规则和any类型的特性共同作用的结果，核心逻辑如下：

1. 重载签名采用从上到下的短路匹配规则：编译器会按照重载声明的顺序，逐个校验入参是否匹配当前重载的参数类型，一旦找到第一个兼容的重载就会直接采用该签名的返回值类型，不会继续校验后面的重载签名。
2. any类型兼容所有类型：当入参是any类型时，它可以匹配第一个重载的string类型参数，所以编译器直接采用第一个重载的返回值类型string，不会继续匹配后面的undefined或者联合类型重载。
3. 你定义的第三个重载（入参为联合类型的签名）虽然兼容any，但因为排序靠后，永远不会被any类型的入参匹配到。而ReturnType<typeof myFunction>是收集所有重载签名的返回值类型取联合，所以结果是string | undefined，和单次重载匹配的结果逻辑不同。

设计考量 #

TypeScript团队设计这套规则主要有三点考量：

• 性能优先：如果每次重载匹配都需要遍历所有重载，收集所有兼容的签名再合并返回值类型，会大幅提升编译复杂度和耗时，尤其是当重载数量较多时，对大型项目的编译速度影响极大。从上到下的短路匹配可以把重载匹配的时间复杂度控制在可控范围内，且大多数场景下不需要遍历完全部重载。
• 向后兼容：这套短路匹配规则是TypeScript 1.0版本就定下的核心规则，大量存量代码都依赖重载的排序逻辑实现类型推断，如果修改为全量匹配取联合的规则，会导致无数现有项目的类型校验报错，破坏整个生态的兼容性。
• 符合多数场景的开发预期：通常开发者写重载时都会遵循「更具体的签名在前，更宽泛的签名在后」的规范，any入参匹配靠前的具体签名，避免返回过于宽泛的联合类型，可以减少开发者后续不必要的类型断言操作，符合大多数场景下的开发效率需求。

可选修复方案 #

如果你希望any类型的入参返回string | undefined的类型，可以调整重载的排序，把最宽泛的联合类型重载放到最前面：

function myFunction(input: string | undefined): string | undefined
function myFunction(input: string): string
function myFunction(input: undefined): undefined
function myFunction(input: string | undefined): string | undefined {
    return input
}

或者单独增加一个针对any类型的重载放在最前面：

function myFunction(input: any): string | undefined
function myFunction(input: string): string
function myFunction(input: undefined): undefined
function myFunction(input: string | undefined): string | undefined {
    return input
}

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