为何TypeScript使用@type组合泛型函数时报错，@param/@return则正常？

问题核心原因 #

两种JSDoc标注方式在TypeScript对泛型的处理逻辑上存在本质差异：

1. 双@type {function(X): X}标注的问题

当你给两个函数都用@template X + @type {function(X): X}标注时，每个变量的@template X都是完全独立的类型参数——identity1的X和identity2的X是两个毫无关联的泛型占位符，TypeScript会将它们视为不同的、无约束的类型。

在identity2的实现里调用identity1(x)时，TypeScript会认为：identity2的X可以被实例化为任意类型，而identity1的X也可以被实例化为任意类型，这两个类型没有绑定关系，自然会抛出“Type 'X' is not assignable to type 'X'”的错误。

2. @param+@returns标注的正确逻辑

当你把identity1的标注换成@template X + @param {X} x + @returns {X}时，TypeScript会把这个函数识别为自身携带泛型签名的具名函数——泛型参数X是和函数的参数、返回值直接绑定的，属于函数本身的一部分。

此时在identity2中调用identity1(x)，TypeScript会自动推断：identity1的泛型参数X应该和identity2的X保持一致，因为identity1的泛型是基于传入的参数动态匹配的，而非独立的匿名类型，所以不会出现类型不兼容的问题。

总结 #

• @type {function(X): X}是给变量赋值一个泛型函数类型，每个变量的@template参数相互独立；
• @param+@returns是直接给函数定义自身的泛型签名，泛型参数和函数的调用逻辑绑定，能被TypeScript正确关联推断。

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