ESLint + Prettier 代码格式与语法校验

在团队协作中，保证代码风格一致、避免低级语法错误，是代码质量保障的第一步。ESLint 负责静态分析与语法规则检查，Prettier 负责代码格式化，两者配合使用能实现“写代码时自动提示、保存时自动格式化”，让开发者专注于逻辑而非排版。

1. ESLint：静态分析与最佳实践约束

ESLint 是 Node.js 生态中最主流的 JavaScript/TypeScript 静态分析工具。它不仅可以检测未定义的变量、未使用的变量、语法错误，还能强制执行编码风格约定（如禁止使用 var、强制使用一致性引号、限制嵌套深度等）。

1.1 安装与初始化

在项目根目录执行：

npm install --save-dev eslint
npx eslint --init

--init 会通过交互式问答生成基础配置，通常选择：

• 环境：Node.js（如果同时包含前端则选择 Browser）
• 模块系统：CommonJS（或 ES Modules 根据项目）
• 风格指南：选择流行风格（如 Airbnb、Standard，或仅手动配置基础规则）

也可以直接创建 .eslintrc.js 或 .eslintrc.json 文件。一个典型的 Node.js 后端的 ESLint 配置：

module.exports = {
  env: {
    node: true,
    es2021: true,
  },
  extends: ['eslint:recommended'],
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  rules: {
    'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    'no-console': 'off',          // 后端通常保留 console.log
    'prefer-const': 'error',
    'no-var': 'error',
    'eqeqeq': ['error', 'always'],
  },
};

若项目使用 TypeScript，需额外安装解析器和插件：

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

并调整配置：

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
  ],
};

1.2 常用规则与定制

ESLint 的规则有几百条，建议从 eslint:recommended 开始，根据团队习惯逐步收紧。一些实用的规则（Node.js 场景）：

• 错误防护类：no-undef（禁止使用未声明变量）、no-unsafe-finally、no-loss-of-precision
• 代码质量类：no-unused-vars（避免无用变量，可允许以下划线开头的参数）、no-return-await（在 async 函数中无必要 return await）、require-await（禁止定义 async 函数但无 await 语句）
• 风格统一类：semi（是否必须分号）、quotes（单引号/双引号）、indent（缩进空格数）、comma-dangle（尾逗号）

对于大规模已有项目，可以使用 eslint --fix 批量自动修复可修复的规则。建议将规则逐步开启，避免一次性引入大量报错导致团队抵触。

2. Prettier：代码自动格式化

Prettier 是一个“有观点的”代码格式化工具，它直接重写代码的排版（换行、缩进、引号、分号等），不需要配置大量格式化规则。其核心理念是：停止争论，让工具全权决定格式。

2.1 安装与配置

npm install --save-dev prettier

在项目根目录创建 .prettierrc 配置文件，最常见的 Node.js 项目配置如下：

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "endOfLine": "lf"
}

也可以在 package.json 中添加 "prettier": {...} 字段，但独立文件更易维护。

2.2 手动格式化与自动化

手动运行格式化：

npx prettier --write .

为了在编辑器中保存时自动格式化，可安装 VS Code 的 Prettier 插件，并在 .vscode/settings.json 中配置：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

前置条件仍然是项目中已安装 Prettier，且通常建议在项目根目录存在 .prettierrc，以避免与插件默认规则冲突。

3. ESLint 与 Prettier 的冲突化解

ESLint 内部也涉及格式规则，Prettier 的格式化结果可能与 ESLint 的某些规则冲突（如 semi、quotes、comma-dangle）。为了解决冲突，需引入专门的配置：

npm install --save-dev eslint-config-prettier eslint-plugin-prettier

• eslint-config-prettier：关闭所有 ESLint 中可能与 Prettier 冲突的格式规则。
• eslint-plugin-prettier：将 Prettier 作为 ESLint 的一条规则运行，即 prettier/prettier，可以在 ESLint 检测时直接提示格式错误（实际上背后调用 Prettier）。

在 .eslintrc.js 中配置：

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:prettier/recommended',   // 这一行必须放在最后，确保覆盖
  ],
  // ...其他规则
};

plugin:prettier/recommended 等效于同时添加：

• extends: ['prettier']（关闭冲突的 ESLint 规则）
• plugins: ['prettier']
• rules: { 'prettier/prettier': 'error' }

这样配置后，任何不符合 Prettier 格式的代码都会作为 ESLint 错误（或警告）显示，开发者只需关注 ESLint 给出的提示，同时享有 Prettier 的自动格式化能力。

4. 集成到项目工作流

4.1 npm scripts

在 package.json 中添加脚本：

{
  "scripts": {
    "lint": "eslint . --ext .js,.ts",
    "lint:fix": "eslint . --ext .js,.ts --fix",
    "format": "prettier --write .",
    "check": "npm run lint && prettier --check ."
  }
}

• lint：检查所有 JS/TS 文件，输出错误。
• lint:fix：ESLint 自动修复加 Prettier 格式化（因为 plugin:prettier/recommended 会把 Prettier 作为 ESLint 规则运行）。
• format：仅 Prettier 格式化所有支持的文件。
• check：用于 CI 检查，要求无格式和 lint 错误才能通过。

4.2 Git Hooks 结合 Husky

为强制提交之前通过校验，可使用 Husky 注入 Git 钩子：

npm install --save-dev husky
npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

然后安装 lint-staged 仅检查暂存区文件，配置在 package.json 中：

{
  "lint-staged": {
    "*.{js,ts}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yaml}": ["prettier --write"]
  }
}

提交前会自动对修改的文件执行 ESLint 修复和 Prettier 格式化，若修复后仍有代码错误（如未使用变量故意保留），ESLint 会报错阻止提交，必须人工修复。

5. 实践中的注意事项

• 不要在 ESLint 规则中重复格式化：启用 eslint-config-prettier 后，不要手动再添加 indent、semi 等规则，否则可能产生冲突或检查重叠。
• .editorconfig 配合使用：.editorconfig 可设置缩进风格、文件编码等，与 Prettier 的部分配置重叠。推荐保留 .editorconfig 供不支持 Prettier 的编辑器使用，但要确保它们的缩进配置与 .prettierrc 一致，避免保存时反复切换。
• 逐步推广：对于遗留项目，可以先在 CI 中只对变更文件进行 lint，或者设置规则级别为 warn，逐步修复后再升级为 error。
• TypeScript 项目注意处理 TS 专用规则：当使用 @typescript-eslint 时，确保 @typescript-eslint/eslint-plugin 的 'prettier' 也与 @typescript-eslint/parser 匹配，可以安装 @typescript-eslint/eslint-config-prettier 和 @typescript-eslint/eslint-plugin-prettier 包来适配 TypeScript。
• Prettier 对后端代码的格式化标准与前端一致：比如 printWidth 设置 100 字符换行，这在后端较长的查询语句中可能显得过早折叠，建议团队统一标准，接受 Prettier 的决定。

6. 真实效果与价值

通过 ESLint + Prettier 的组合，一个 Node.js 项目的代码风格可以被完全锁死，几乎不再产生因格式引起的 Code Review 争议。实际收益包括：

• 提高代码可读性和一致性，降低新人接手代码的认知成本。
• 预防常见错误（如变量未定义、未捕获的异常）。
• 集成在 CI 中，避免不规范代码进入主分支。
• 配合 Git Hooks 实现自动化格式化，减少开发者手动调整格式的时间。

这一套工具链在 Node.js 生态中几乎成为默认标准，无论是 Express 小型服务还是 NestJS 企业项目，都值得第一时间配置起来。