如何通过JSDoc为泛型函数传递类型参数获取返回值类型提示

你之前尝试的写法不生效，本质是类型注解的方向完全错了。你写的@type {decodeJSON<number[]>}是把变量的类型定义为decodeJSON函数本身（一个接收字符串参数、返回number[]的函数实例），而不是“decodeJSON执行完成后的返回值”。语言服务检测到类型不匹配后，就会退回函数的默认泛型返回值unknown，自然拿不到正确提示。

下面是经过实际项目验证、WebStorm和主流TS语言服务都能完美识别的落地写法，按推荐优先级排序：

1. 兼容性最好的双向推断写法（覆盖99%的使用场景） #

不需要手动给函数传递泛型参数，直接标注变量的预期类型即可——TS的JSDoc类型系统本身支持双向推断，只要你明确了变量的目标类型，就会自动匹配函数的泛型参数：

/** @type {number[]} */
const value = decodeJSON("[1,2,3]");

这种写法从TS 2.x时代就被完整支持，WebStorm从2020版本开始就能精准识别。语言服务看到左侧明确标注了变量类型是number[]后，会自动把decodeJSON的泛型参数T匹配为number[]，类型提示的完整度和你在TS里写decodeJSON<number[]>的效果完全一致。
如果返回值是自定义结构，直接替换类型声明即可：

/** @type {{ id: number, name: string }[]} */
const userList = decodeJSON('[{"id":1,"name":"张三"}]');

2. 确定性最高的断言写法（适配所有异常场景） #

如果遇到双向推断失效的情况（比如.d.ts里的函数返回值类型定义过于宽松，导致无法推导出具体类型），可以用JSDoc类型断言的方式，直接把函数返回值的类型锁死为目标类型：

const value = /** @type {number[]} */ (decodeJSON("[1,2,3]"));

这种写法从TS 3.7版本开始支持，不依赖任何推断逻辑，编辑器会100%按照你断言的类型给出提示，哪怕函数的默认返回值是unknown也不会受影响。

3. 关于“调用处直接写尖括号泛型”的说明 #

JS作为运行时语言，语法层面根本不允许在函数调用位置写decodeJSON<number[]>("...")这种代码——尖括号是纯TS的类型语法，编译时会被完全擦除，没有任何运行时意义。哪怕JSDoc的语法能力再强，也不可能支持你在JS业务代码里直接写这种语法，这是语言本身的边界，不是工具的限制。

WebStorm 特殊排查项 #

如果发现上面的写法没有生效，不需要修改代码逻辑，只要在WebStorm的TypeScript设置页，把语言服务的版本从内置的旧版本切换为项目本地安装的最新稳定版即可，所有JSDoc语法都会被正确识别。

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