配置ESLint与Prettier强制规范JavaScript函数注释风格

图 0：ESLint 与 Prettier 联合驱动函数注释风格工程化规范架构概览

在大型 JavaScript 项目中，单靠 Prettier 只能统一代码缩进与空行外观，无法识别函数是否缺少说明、参数注释是否遗漏或类型标注是否失真；而依赖人工 Code Review 往往费时且容易产生疏漏。切实可行的解决路径是实行“语义校验与视觉排版分工治理”：利用 ESLint 搭配专用的 eslint-plugin-jsdoc 插件深入抽象语法树（AST），对函数注释的完整度、@param 命名对应关系以及 @returns 返回值做强校验；同时利用 Prettier 负责行宽截断与星号排版，并通过 eslint-config-prettier 停用重叠的排版冲突规则。结合编辑器保存自动修复与 Git 提交前守卫，即可在团队中将规范化函数注释落到实处。

一、明确职责分工：为什么不能仅靠单一工具？

很多开发者在刚开始制定前端规范时容易产生误解，试图仅通过 Prettier 解决所有注释排版问题，或仅通过 ESLint 处理所有代码细节。理解两者在底层实现机制上的差异，是配置整套体系的前提：

• Prettier 的本质是“无偏见的格式化器”：它接收源代码并将其解析为语法树后，丢弃所有原有的排版细节，完全根据设定的行宽（printWidth）、单双引号、分号和缩进规则重新打印代码。Prettier 会对多行注释的前导星号 * 进行对齐，但它完全不关心业务语义——如果一个函数声明了三个入参，注释里却只写了一个参数说明，甚至完全没有写 JSDoc 注释，Prettier 仍然会判定该文件完全合法并正常保存。
• ESLint 的本质是“代码质量与语法模式检查器”：它通过 AST 遍历对代码节点的属性进行逻辑判断。借助 eslint-plugin-jsdoc，ESLint 能够精确比对 FunctionDeclaration 节点的 params 数组与上方 JSDocComment 块中的 @param 标签数量与命名。一旦发现名称错位、类型遗漏或无注释函数，就会给出阻断性报错。

图 1：Prettier 与 ESLint 在函数注释规范中的职责边界及协作模型

如上图所示，两者协同的最佳实践是：由 ESLint 严抓“写没写、对不对、全不全”的契约问题，由 Prettier 严抓“美不美、齐不齐、换不换行”的呈现问题。通过 eslint-config-prettier 清理二者之间的格式规则重叠，从而实现流畅协作。

二、环境依赖安装与包职责解析

在项目根目录下，我们需要安装 ESLint 核心包、Prettier 核心包以及两者协同所需的插件。执行以下命令进行本地开发依赖安装：

# 使用 npm 安装所需开发依赖
npm install --save-dev eslint prettier eslint-plugin-jsdoc eslint-config-prettier prettier-plugin-jsdoc

以下是本次方案中各个依赖包的核心职能与选用依据：

图 2：从依赖安装到自动化守卫落地的完整实施路径

三、配置 ESLint：基于 Flat Config 建立严格注释规则

在现代前端工程中（ESLint 9+），官方已全面推行 Flat Config（平面配置）规范。我们以项目根目录下的 eslint.config.mjs（或 eslint.config.js）为例，展示如何配置 eslint-plugin-jsdoc 规则集。

// eslint.config.mjs
import js from '@eslint/js';
import jsdoc from 'eslint-plugin-jsdoc';
import prettierConfig from 'eslint-config-prettier';

export default [
  // 1. 继承 ESLint 官方推荐的基础语法检查
  js.configs.recommended,

  // 2. 针对所有 JavaScript 源码配置 JSDoc 强校验规则
  {
    files: ['**/*.js', '**/*.mjs'],
    plugins: {
      jsdoc: jsdoc,
    },
    rules: {
      // 强制要求函数编写 JSDoc 注释
      'jsdoc/require-jsdoc': [
        'error',
        {
          require: {
            FunctionDeclaration: true,
            MethodDefinition: true,
            ClassDeclaration: true,
            ArrowFunctionExpression: false, // 简短内联箭头函数可免除
            FunctionExpression: true,
          },
          contexts: [
            // 导出函数必须有注释
            'ExportNamedDeclaration > FunctionDeclaration',
            'ExportDefaultDeclaration > FunctionDeclaration',
          ],
        },
      ],

      // 验证 @param 标签是否存在且与函数形参一一对应
      'jsdoc/require-param': 'error',
      'jsdoc/check-param-names': 'error',

      // 强制要求 @param 必须提供数据类型与文本说明
      'jsdoc/require-param-type': 'error',
      'jsdoc/require-param-description': 'error',

      // 校验函数返回值：有 return 语句时必须包含 @returns
      'jsdoc/require-returns': 'error',
      'jsdoc/require-returns-type': 'error',
      'jsdoc/require-returns-description': 'warn',

      // 检查 JSDoc 原生数据类型的合法性与大小写规范
      'jsdoc/check-types': 'error',

      // 确保注释文本与标记符合常规格式
      'jsdoc/check-tag-names': 'error',
      'jsdoc/check-alignment': 'error',
    },
  },

  // 3. 必须放在数组最后：关闭所有可能与 Prettier 发生冲突的格式规则
  prettierConfig,
];

核心检查规则的设计意图与作用机制

配置中的几条核心规则构成了防御不规范注释的主体：

• jsdoc/require-jsdoc：控制“哪种函数必须写注释”。如果无差别要求每一个 array.map(x => x + 1) 都写 JSDoc，会极大降低开发效率。因此规则中将 ArrowFunctionExpression 设为 false，而将普通的 FunctionDeclaration 与模块导出的公共函数设置为强制报错（error）。
• jsdoc/check-param-names 与 jsdoc/require-param：不仅检查参数数量，更比对参数标识符。例如函数参数为 (userId, options)，若注释误写成了 @param {string} uid，Linter 会立刻提示找不到形参 uid，防止复制粘贴带来的“过期文档”。
• jsdoc/require-returns：Linter 会静态扫描函数作用域内是否存在带返回值的 return 表达式。如果存在返回值但 JSDoc 缺少 @returns 标签，将触发阻断报错。

图 3：ESLint 遍历 AST 节点并校验 JSDoc 标签与真实形参的映射关系

四、配置 Prettier：让函数注释排版整洁有序

在语义校验生效后，我们需要 Prettier 对 JSDoc 文本进行格式对齐。在项目根目录下创建或编辑 .prettierrc.json：

{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "plugins": ["prettier-plugin-jsdoc"],
  "jsdocParser": true,
  "jsdocDescriptionWithDot": false,
  "jsdocSeparateReturnsFromParam": true,
  "jsdocAddPunctuation": false
}

代码修复对比演示

当开发者编写了残缺或格式凌乱的代码时，ESLint 与 Prettier 会对其进行检查与整理。以下通过具体代码直观展示差异：

【不合规代码示例】：缺少参数定义、缺少类型、排版错乱

// 存在问题：缺少参数说明、未标注返回值、星号未对齐、缺少参数类型
/**
* 更新用户信息
* @param id
*/
function updateUserProfile(id, profileData, notifyUser = false) {
  if (!id) return false;
  // 执行更新逻辑
  return true;
}

在执行 npx eslint 检查时，控制台将输出明确的错误信息：

  6:1  error  Missing JSDoc @param "profileData" declaration     jsdoc/require-param
  6:1  error  Missing JSDoc @param "notifyUser" declaration      jsdoc/require-param
  4:1  error  Missing JSDoc @param "id" type                     jsdoc/require-param-type
  4:1  error  Missing JSDoc @param "id" description              jsdoc/require-param-description
  6:1  error  Missing JSDoc @returns declaration                 jsdoc/require-returns

【合规且排版优良的标准输出】：

/**
 * 更新用户信息并根据设置发送变更通知。
 *
 * @param {string} id - 用户的全局唯一 ID 标识符
 * @param {object} profileData - 待更新的用户个人资料实体对象
 * @param {boolean} [notifyUser=false] - 是否在更新完成后发送邮件通知
 *
 * @returns {boolean} 更新操作是否执行成功
 */
function updateUserProfile(id, profileData, notifyUser = false) {
  if (!id) return false;
  // 执行更新逻辑
  return true;
}

经过规范后的注释块，不仅消除了所有 ESLint 警告，而且在 VSCode 等现代编辑器中，当其他开发者调用 updateUserProfile 时，鼠标悬停即可获得清晰的类型提示、参数说明与默认值展示，极大提升了工程可维护性。

五、工程化落地：编辑器自动修复与 Git 拦截守卫

仅靠口头约定无法保证团队成员每次都运行命令，必须借助工具链实现自动化修复与严格把关。

1. 配置 VSCode 保存即修复

在项目根目录下的 .vscode/settings.json 中添加以下配置。这样每当开发者按下快捷键保存文件时，VSCode 会自动依次调用 ESLint 修复（补齐能推导的标签）与 Prettier 格式化：

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

2. 在 package.json 中配置验证与修复脚本

在 package.json 的 scripts 区域添加常用命令，供本地批量扫描与持续集成（CI）调用：

{
  "scripts": {
    "lint:jsdoc": "eslint src/ --ext .js --max-warnings=0",
    "lint:fix": "eslint src/ --ext .js --fix",
    "format": "prettier --write \"src/**/*.js\""
  }
}

3. 使用 lint-staged 拦截不合规提交

配合 husky 与 lint-staged，在执行 git commit 时只对暂存区的变更文件进行检查。若存在未编写 JSDoc 或参数错漏的函数，直接中止提交过程：

// package.json 配置片段
{
  "lint-staged": {
    "*.js": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

图 4：函数注释风格规范在开发、保存与提交全生命周期中的防护与总结

六、总结与落地建议

规范 JavaScript 函数注释风格并不是追求繁冗的形式主义，而是为弱类型语言构建轻量、可信、低维护成本的类型与语义契约。在整套方案中：

1. ESLint + eslint-plugin-jsdoc 是质量守护的核心，通过 AST 语义解析强制确保函数必须附带准确、对应的参数和返回值说明；
2. Prettier + eslint-config-prettier 负责美化排版，消除了空格、换行与格式冲突的心智负担；
3. IDE 保存自动修复 + Git Hooks 门禁 则将规范内化为团队的自动化日常操作，让开发者在日常编码中自然遵循规范。

通过以上配置，团队无需花费额外精力去督促进度，代码库中的每个公共函数都能自动保有清晰、一致、可被 IDE 智能提示的专业注释。