TypeScript接口重载方法的顺序是否会影响类型检查？

问题原因 #

你遇到的问题本质是TypeScript泛型推断与重载签名顺序交互导致的类型兼容性问题，核心规则如下：

1. TypeScript处理重载签名时，会按声明的从上到下顺序尝试匹配。
2. 当泛型函数（如useCache）需要推断参数类型时，会优先根据第一个匹配的重载签名推导泛型参数，再验证是否兼容所有重载。

具体到你的代码：

• 当set(key: string, item: Item): void放在前面时：
  TypeScript先尝试用这个双参数重载匹配state.cache的Record<string, Item[]>类型，发现不匹配，于是继续检查下一个重载set(record: Record<string, Item[]>): void，这个重载正好匹配state.cache的类型，因此成功推断泛型参数C为Record<string, Item[]>，类型检查通过。

• 当set(key: string, item: Item): void放在后面时：
  TypeScript先匹配第一个重载set(record: Record<string, Item[]>): void，初步推断C为Record<string, Item[]>，但随后发现cache.set还有第二个双参数重载。此时TypeScript会要求C类型必须能兼容所有重载的参数要求——但Record<string, Item[]>无法作为双参数重载的第一个参数（且缺少第二个参数），因此泛型推断出现冲突，触发类型报错。

获取更多相关信息的渠道 #

• TypeScript官方手册的函数重载章节：详细讲解重载的声明规则、类型检查逻辑。
• TypeScript官方手册的类型兼容性章节：重点关注函数与重载的兼容性判断规则。
• TypeScript GitHub仓库的issues：搜索“overload order generic inference”等关键词，可以找到类似案例和官方解释。

总结 #

这确实是重载顺序直接导致的问题，TypeScript对重载的匹配和泛型推断依赖于签名的声明顺序。调整重载顺序可以解决这类兼容性问题，本质是让TypeScript优先匹配符合预期的重载签名，避免后续重载引发的约束冲突。

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