20.1 ESLint + Prettier：代码格式与语法检查

代码质量和风格一致性是团队协作的基石。ESLint 负责发现代码中的潜在错误和不符合最佳实践的写法，Prettier 负责统一代码格式（缩进、引号、分号等）。两者配合可以让开发者专注于逻辑，而不必在代码评审中争论风格问题。

为什么需要两者配合

ESLint：静态分析工具，识别语法错误、未使用变量、Hooks 规则违反等逻辑问题，也可约束编码风格。
Prettier：固执己见的格式化工具，强制统一的代码排版，避免团队成员之间因格式差异引发的冲突。

如果只用 ESLint 处理格式，规则会臃肿且容易与手动排版产生冲突；如果只用 Prettier，则缺失代码质量检查。最佳实践是 ESLint 管代码质量，Prettier 管代码格式，通过插件让两者协作而不冲突。

安装与初始化

在 React 项目中（以 Vite 搭建为例），安装所需依赖：

npm install -D eslint prettier eslint-plugin-react-hooks eslint-plugin-react-refresh eslint-config-prettier eslint-plugin-prettier @typescript-eslint/eslint-plugin @typescript-eslint/parser

说明：eslint-config-prettier 用于关闭所有与 Prettier 冲突的 ESLint 规则，eslint-plugin-prettier 将 Prettier 作为 ESLint 的规则运行（可选）。

如果使用 Vite 创建项目，它已内置 ESLint 配置。推荐使用扁平化配置（ESLint 9 默认），兼容性更好。

ESLint 配置

创建 eslint.config.js（或 eslint.config.mjs）：

import js from '@eslint/js';
import tseslint from '@typescript-eslint/eslint-plugin';
import tsparser from '@typescript-eslint/parser';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import prettier from 'eslint-plugin-prettier';
import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  // 基础推荐规则
  js.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parser: tsparser,
      parserOptions: {
        ecmaVersion: 'latest',
        sourceType: 'module',
        ecmaFeatures: { jsx: true },
      },
    },
    plugins: {
      '@typescript-eslint': tseslint,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
      prettier,
    },
    rules: {
      // TypeScript 推荐规则
      ...tseslint.configs.recommended.rules,
      // React Hooks 规则
      ...reactHooks.configs.recommended.rules,
      // React Refresh 热更新规则
      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
      // Prettier 作为规则运行（将格式错误体现为 ESLint 错误）
      'prettier/prettier': 'error',
      // 自定义规则示例
      'no-console': 'warn',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },
  // 必须放在最后，禁用所有与 Prettier 冲突的 ESLint 规则
  eslintConfigPrettier,
];

关键点解释：

parser：TypeScript 解析器让 ESLint 能理解 TS 语法。
react-hooks：强制执行 Hooks 的调用顺序和依赖项检查。
prettier/prettier：将 Prettier 格式问题视为 ESLint 错误，运行 eslint --fix 时自动格式化。
eslintConfigPrettier：必须是配置数组中的最后一个元素，确保覆盖冲突规则。

Prettier 配置

创建 prettier.config.js（或 .prettierrc）：

export default {
  printWidth: 100,        // 换行宽度
  tabWidth: 2,            // 缩进空格数
  semi: true,             // 行尾分号
  singleQuote: true,      // 使用单引号
  trailingComma: 'all',   // 尾随逗号
  bracketSpacing: true,   // 对象花括号内空格
  arrowParens: 'always',  // 箭头函数参数始终加括号
  endOfLine: 'lf',        // 统一换行符
  jsxSingleQuote: false,  // JSX 中使用双引号
};

这些配置与 React 社区习惯保持一致，你也可以根据团队风格调整。关键是 Prettier 的配置优先级最高，开发者无需再纠结格式细节。

忽略文件

创建 .prettierignore 和 .eslintignore（或使用配置文件中的 ignores），避免格式化无关文件：

# .prettierignore
node_modules
dist
build
coverage
*.min.js
pnpm-lock.yaml

// 在 eslint.config.js 中添加 ignores
{
  ignores: ['dist', 'node_modules', 'coverage'],
}

集成到工作流

1. 编辑器集成

在 VS Code 中安装 ESLint 和 Prettier 插件，并进行以下配置（.vscode/settings.json）：

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

这样每次保存文件时，Prettier 先格式化代码，然后 ESLint 自动修复可修复的问题（如添加缺少的依赖、删除未使用的变量）。

2. 命令行脚本

在 package.json 中添加脚本：

{
  "scripts": {
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "lint:fix": "eslint . --ext ts,tsx --fix",
    "format": "prettier --write \"src/**/*.{ts,tsx,css,scss,json}\"",
    "format:check": "prettier --check \"src/**/*.{ts,tsx,css,scss,json}\""
  }
}

npm run lint：检查代码质量和规范。
npm run lint:fix：自动修复可修复的问题（包括 Prettier 格式）。
npm run format：单独使用 Prettier 格式化所有文件。
npm run format:check：检查格式但不修改，常用于 CI。

3. 提交时自动检查（Husky + lint-staged）

结合 Git Hook，在提交前自动对暂存文件执行检查和格式化：

npm install -D husky lint-staged
npx husky init

在 .husky/pre-commit 写入：

npx lint-staged

在 package.json 或 .lintstagedrc.js 配置：

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,css,scss,md}": [
      "prettier --write"
    ]
  }
}

这样，每次 git commit 时，暂存区的 JS/TS 文件会被 ESLint 修复和 Prettier 格式化，确保进入仓库的代码永远符合规范。

常见问题与要点

冲突规则：务必使用 eslint-config-prettier 并放在配置最后，否则会影响体验。
性能：Vite 的 ESLint 集成默认在开发时只检查变更文件，不会拖慢启动速度。
规则粒度：开始时使用推荐规则，再根据团队需求调整，避免无休止的规则争议。
自动修复的局限性：ESLint 只能自动修复部分问题（如 no-unused-vars 中的 _ 前缀变量不会被自动删除），复杂问题仍需人工处理。

通过 ESLint + Prettier 的规范体系，你的 React 项目将拥有统一的代码面貌，代码评审时可以真正聚焦逻辑与架构，而非争论该不该加分号。