如何配置ESLint消除Node.js项目中无效JSDoc标签名警告？

嘿，我之前搭建Node.js项目时也碰到过完全一样的ESLint警告！这种情况大多是因为你用了ESLint JSDoc插件默认不认可的自定义标签或非标准类型，下面给你几个靠谱的解决办法：

1. 先确认依赖的ESLint插件 #

首先得搞清楚，你是不是用了eslint-plugin-jsdoc这个插件？因为ESLint核心本身并没有内置JSDoc相关的校验规则，绝大多数「无效标签名」警告都是来自这个插件的jsdoc/check-tag-names或jsdoc/valid-types规则。

2. 允许自定义标签/类型 #

如果你的JSDoc里用了自定义标签（比如@typedef之外的自定义标签，或者TypeScript风格的类型），可以直接在你的.eslint.json里配置规则，把这些标签加入允许列表：

示例配置：允许自定义标签和TS类型 #

{
  "plugins": ["jsdoc"],
  "rules": {
    "jsdoc/check-tag-names": [
      "warn",
      {
        "definedTags": ["customTag1", "customTag2"] // 这里添加你的自定义标签
      }
    ],
    "jsdoc/valid-types": [
      "warn",
      {
        "allowUnionTypes": true, // 允许TS联合类型
        "allowEmptyNamepaths": true,
        "preferType": {
          "String": "string",
          "Number": "number" // 统一类型风格，避免不必要警告
        }
      }
    ]
  }
}

如果是用了TypeScript相关的JSDoc类型（比如@type {import('./module').Type}），还可以开启插件的TypeScript支持：

{
  "settings": {
    "jsdoc": {
      "mode": "typescript"
    }
  }
}

3. 直接禁用对应的规则 #

如果你暂时不想校验JSDoc标签的有效性，也可以直接把相关规则设为off：

{
  "rules": {
    "jsdoc/check-tag-names": "off",
    "jsdoc/valid-types": "off"
  }
}

小提示 #

记得修改配置后重启ESLint服务（如果是用编辑器插件的话，可能需要重启编辑器或者刷新ESLint状态），这样新的配置才会生效。

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