WebStorm 中 ESLint 提示 JSDoc 自定义类型 Unresolved variable or type 错误

ESLint 未识别自定义 JSDoc 类型问题解决方案 #

• 规则配置调整
  你遇到的Unresolved variable or type 'CustomRefA'报错通常由eslint-plugin-jsdoc的jsdoc/no-undefined-types规则触发，可按以下两种方式处理：

1. 关闭该校验规则：在项目根目录的 ESLint 配置文件（.eslintrc、.eslintrc.js等）中添加如下配置：

{
  "rules": {
    "jsdoc/no-undefined-types": "off"
  }
}

2. 若需要保留规则，可将自定义类型加入规则允许列表：

{
  "rules": {
    "jsdoc/no-undefined-types": ["error", {
      "definedTypes": ["CustomRefA", "CustomRefB"]
    }]
  }
}

• 跨文件类型引用处理
  如果自定义@typedef定义和引用不在同一个JS文件中，ESLint默认不会跨文件识别自定义类型，需手动引入：
  在引用类型的文件顶部添加导入声明即可，示例：

/** @typedef {import('./公共类型文件相对路径').CustomRefA} CustomRefA */

公共类型文件可添加@module声明提升类型识别范围，示例：

// 公共类型文件顶部添加
/** @module common-custom-types */

• WebStorm 缓存&配置校验
  WebStorm 2021.2 版本偶发ESLint缓存失效问题，可按以下步骤排查：

1. 打开WebStorm设置页，进入Languages & Frameworks > JavaScript > Code Quality Tools > ESLint，点击Clear Cache清除ESLint缓存，重启ESLint服务
2. 确认WebStorm配置的ESLint路径为当前项目node_modules/eslint对应7.32.0版本，避免识别到全局其他版本的ESLint
3. 右键项目根目录，选择Mark Directory as > Excluded，撤销排除后等待项目索引重建完成即可解决偶发的识别错误

• 基础类型规范修正
  你的代码中基础类型使用了大写Boolean，建议统一替换为小写boolean、string、number等标准小写基础类型写法，避免规则误判。

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