如何在JSDoc中跨文件引用类作为参数类型？

你遇到的问题主要源于类未正确导出/导入、JSDoc标注格式错误，以及代码属性名大小写不匹配。以下是具体解决步骤：

1. 确保类正确导出并被目标文件识别 #

首先在MyClass.js中导出类，让其他文件能获取到它的类型定义：

// src/models/MyClass.js
/**
 * @class
 * @alias module:MyClass
 */
export class MyClass { // 添加export导出类
  foo() {

  }
}

然后在index.js中导入该类（哪怕代码逻辑里没直接使用，类型检查器也需要通过导入获取类型信息）：

// src/controllers/index.js
import { MyClass } from '../models/MyClass.js';

/**
 * @param {Object} context
 * @param {MyClass} context.myClass // 直接用导入的类名作为类型
 */
const myFunction = (context) => {
  const bar = context.myClass(); // 修正大小写：与标注的myClass保持一致
  bar.foo();
};

2. 无需代码导入的JSDoc类型引用方式 #

如果不想在代码层面导入类（比如用CommonJS模块或避免冗余导入），可以用@typedef结合import()类型引用：

// src/controllers/index.js
/**
 * @typedef {import('../models/MyClass.js').MyClass} MyClass
 */

/**
 * @param {Object} context
 * @param {MyClass} context.myClass
 */
const myFunction = (context) => {
  const bar = context.myClass();
  bar.foo();
};

这种方式仅在JSDoc中声明类型别名，不会影响代码运行逻辑。

3. 关键细节检查 #

• 确保属性名大小写一致：你示例中标注的是context.myClass，但代码里写的是context.MyClass()，大小写不匹配会导致类型检查器无法关联，必须统一。
• 开启编辑器类型检查：如果用VS Code，可在设置中开启"javascript.implicitProjectConfig.checkJs": true，确保JSDoc类型能被正确识别。

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