eslint-plugin-jsdoc：一款帮你把 JSDoc 注释也纳入代码质量检查的 ESLint 插件

4次阅读

获取下载链

微信关注「软件教程管家」公众号，回复 eslint-plugin-jsdoc

eslint-plugin-jsdoc 是一款帮你把 JSDoc 注释也纳入代码质量检查的 ESLint 插件：它检查注释里的标签、类型和值写得规不规范，让文档注释和代码走同一套 lint 流程，注释写错、标签拼错都能在提交前被拦下来。据仓库说明，它同时提供 Flat Config、eslintrc 与 TypeScript 相关推荐配置，适合把文档注释纳入团队代码规范。

30 秒速读

如果团队已经在用 ESLint，并且希望把 JSDoc 的标签、类型和值格式纳入统一检查，这个插件值得放进候选：它直接融入现有 lint 工作流，不用另起一套文档检查工具。反过来，如果项目基本不写 JSDoc，或者只需要 TypeScript 编译级类型验证，这个插件就不是你要找的工具，先别急着装。

项目信息

项目	内容
开发语言	JavaScript
运行环境	ESLint 插件，需先安装 ESLint
许可证	以仓库 LICENSE 文件为准
适用平台	多平台
配置形态	Flat Config 与 eslintrc 均支持
适用场景	JavaScript 或 TypeScript 风格项目的 JSDoc 规范检查

选型对照：它和只靠 TypeScript 检查比

结论先行：要管的是注释写得规不规范、标签全不全，用这个插件；要管的是类型本身对不对，靠 TypeScript 编译器，两件事别混成一件。

维度	eslint-plugin-jsdoc	只靠 TypeScript 检查
管什么	标签、类型写法、值格式、注释风格	类型正确性、类型推断
接入位置	ESLint 规则，随 lint 一起跑	编译或编辑器类型检查
配置形态	Flat Config 与 eslintrc 均有推荐配置	tsconfig，与 lint 配置无关
扩展方式	规则、选项、设置、自定义规则定义	类型定义与编译选项
不适合	不写 JSDoc 的项目	不管注释格式与标签完整性

上手步骤

确认项目用哪种 ESLint 配置：先定下来是 Flat Config 还是 eslintrc，再按对应路径装插件，两种配置的接法并不相同。
装插件并引入推荐配置：从 flat/recommended 或面向 TypeScript 的推荐配置起步，先跑通默认规则，再按需收紧。
把检查级别定下来：团队希望注释问题直接报错拦截，还是先警告过渡，错误级别推荐配置可以把结果按失败错误报告。
先在小范围试跑：挑一个模块开规则，看报出来的问题是不是团队真想管的，误报多的规则先关掉或放宽。
把版本与配置锁定：插件版本要与项目 ESLint 配置形态匹配，升级后重跑一次全部规则，确认 Flat Config 与自定义规则定义没有被破坏。

注意事项与边界

它只管 JSDoc 相关问题：不能替代完整的代码质量或类型检查体系，别指望一个插件同时管风格、类型与注释。
TypeScript 能力有边界：相关能力依赖项目采用的语法和 JSDoc 模式，不能据此推断它等同于完整的 TypeScript 编译检查。
生成数组配置有限制：README 提到部分配置在生成数组时对 files、ignores 等属性存在当前限制，需要这些属性与生成数组同时工作时，先按 README 或源码验证。
规则全貌要查文档：公开摘要没有完整列出全部规则、处理器和运行时兼容范围，选型前务必翻完整文档或源码，别只按规则名字下单。
升级要回归：锁定与项目 ESLint 配置方式相匹配的插件版本，升级后重新检查 Flat Config、eslintrc、TypeScript 相关配置及自定义规则定义。