如何在JSDoc中将TypeScript函数定义作为完整类型使用

错误原因 #

你的JSDoc写法存在两个问题：

1. 多余的typeof操作符：import('path/to/types').Helpers本身就是你导出的类型定义，直接访问其foo属性就能拿到对应函数的类型，加typeof会尝试取「类型的类型」，不符合预期。
2. @type直接修饰函数声明会触发tsserver的签名校验冲突，tsserver会单独推导函数声明的签名，和你指定的类型产生冲突。

解决方案 #

方案1：搭配@satisfies修饰函数声明（推荐，TS 4.9+支持）

直接用@satisfies校验函数符合目标类型，不会产生签名冲突：

/**
 * @satisfies {import('path/to/types').Helpers['foo']}
 */
function foo(param, param2) {
  // 此处param、param2的类型会自动推导，返回值也会自动校验，不符合约定就会抛出提示
}

方案2：用@type修饰函数表达式/对象方法

如果是写在对象内的方法、或者赋值给变量的函数表达式，直接用@type修饰即可：

// 对象方法场景
const myHelpers = {
  /**
   * @type {import('path/to/types').Helpers['foo']}
   */
  foo(param, param2) {
    // 自动获得完整类型校验
  }
}

// 函数表达式场景
/**
 * @type {import('path/to/types').Helpers['foo']}
 */
const foo = (param, param2) => {
  // 自动获得完整类型校验
}

注意事项 #

• 导入路径要和你实际的types.d.ts文件路径匹配，不需要加.js/.d.ts后缀，比如文件放在根目录的types文件夹下，直接写import('./types')即可。如果该类型定义已经配置到tsconfig.json的typeRoots或include规则中，可以直接用模块名导入，不需要写相对路径。
• 以上写法完全复用types.d.ts里的定义，不需要单独导入参数、返回值类型拼接。

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