如何配置ESLint校验JSDoc参数：必填无括号、可选带括号？

数据老陈

2026-7-5

配置ESLint校验JSDoc参数格式：必填/可选参数规范

要实现必填参数JSDoc无括号、可选参数带括号的校验，需要借助eslint-plugin-jsdoc插件，结合TypeScript ESLint工具链（针对TS项目），步骤如下：

1. 安装依赖

执行命令安装所需包：

npm install eslint eslint-plugin-jsdoc @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev

2. 配置ESLint规则

在项目根目录的.eslintrc.js（或.eslintrc.json）中添加以下配置：

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint', 'jsdoc'],
  rules: {
    // 强制可选参数（TS带?）的@property标签使用方括号
    'jsdoc/optional-param-markers': ['error', {
      marker: 'square-brackets',
      tags: ['property']
    }],
    // 禁止必填参数（TS不带?）的@property标签使用方括号
    'jsdoc/no-optional-param': ['error', {
      tags: ['property']
    }],
    // 校验JSDoc参数名与代码参数名一致
    'jsdoc/check-param-names': ['error', {
      tags: ['property']
    }]
  },
  settings: {
    jsdoc: {
      mode: 'typescript' // 启用TS模式，识别TS可选参数语法
    }
  }
};

规则说明

jsdoc/optional-param-markers：当TS中带?的可选参数未用方括号包裹时触发错误，确保JSDoc写法为@property [paramName]。
jsdoc/no-optional-param：当TS中不带?的必填参数被错误标记为可选（带方括号）时触发错误，确保JSDoc写法为@property paramName。
jsdoc/check-param-names：避免因参数名拼写不一致导致的校验失效。