eslint-prettier-husky-config

ESLint、Prettier、Husky 配置

概述

为 Next.js/React 项目配置全面的代码质量工具，包括 ESLint v9（扁平配置）、Prettier、Husky Git 钩子、lint-staged 和 CI lint 检查。

安装和配置步骤

1. 安装依赖

安装 ESLint v9、Prettier 和 Git 钩子所需的软件包：

npm install -D eslint@^9 @eslint/js eslint-config-prettier eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y prettier husky lint-staged

对于 TypeScript 项目，还需添加：

npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript-eslint

2. 创建 ESLint 扁平配置

使用 assets/eslint.config.mjs 中提供的模板，在项目根目录创建 eslint.config.mjs。这种扁平配置格式：

• 使用现代 ESLint v9 配置
• 包含 React、React Hooks 和 JSX 无障碍规则
• 支持具有类型感知 lint 检查的 TypeScript
• 忽略 Next.js 构建目录和配置文件

根据项目需求自定义配置：

• 调整 languageOptions.parserOptions 以适配不同的 ECMAScript 版本
• 修改 rules 以符合团队偏好
• 按需添加其他插件

3. 创建 Prettier 配置

使用 assets/.prettierrc 中的模板，在项目根目录创建 .prettierrc。此配置：

• 设置 2 个空格缩进
• 字符串使用单引号
• 移除尾随逗号
• 将行宽设为 100 个字符
• 使用 Unix 换行符

调整格式规则以符合团队风格指南。

使用 assets/.prettierignore 创建 .prettierignore，以排除：

• 构建目录（.next、dist、out）
• 依赖项（node_modules、package-lock.json）
• 生成的文件
• 公共资源

4. 设置 Husky 和 Lint-Staged

为 Git 钩子初始化 Husky：

npx husky init

这会创建包含 pre-commit 钩子的 .husky/ 目录。

将 pre-commit 钩子的内容替换为：

npx lint-staged

使用 references/package-json-config.md 中的示例，将 lint-staged 配置添加到 package.json：

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

这样会在每次提交前对暂存文件运行 ESLint 和 Prettier。

5. 添加 Package 脚本

将以下脚本添加到 package.json（完整示例请参阅 references/package-json-config.md）：

{
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "prepare": "husky"
  }
}

这些脚本可用于：

• npm run lint - 检查 lint 错误（有警告时也会失败）
• npm run lint:fix - 自动修复 lint 问题
• npm run format - 使用 Prettier 格式化所有文件
• npm run format:check - 检查格式，不修改文件
• prepare - 安装依赖时自动设置 Husky

6. 创建 GitHub Actions Lint 工作流

使用 assets/github-workflows-lint.yml 中的模板创建 .github/workflows/lint.yml。此工作流：

• 在拉取请求以及推送到 main/master 分支时运行
• 检出代码并设置 Node.js
• 安装依赖
• 运行 lint 检查和格式检查
• 发现任何问题时使 CI 失败

自定义工作流：

• 按需调整 Node.js 版本
• 修改分支名称以匹配仓库
• 添加缓存以加快 CI 运行速度

7. 验证设置

测试完整设置：

1. Lint 检查：运行 npm run lint，验证 ESLint 配置
2. 格式检查：运行 npm run format:check，验证 Prettier 配置
3. Pre-commit 钩子：进行更改并提交，以测试 Husky 和 lint-staged
4. CI 工作流：推送到分支并创建 PR，以验证 GitHub Actions

修复任何配置问题：

• 检查 ESLint 错误，并按需调整规则
• 格式化所有文件：npm run format
• 提交配置更改

8. 团队文档

为团队成员编写设置文档（模板请参阅 references/team-documentation.md）：

• 说明每种工具的用途
• 为新开发者提供设置说明
• 记录如何临时绕过钩子（仅限紧急情况）
• 包含常见问题的故障排除步骤

配置自定义

ESLint 规则

在 eslint.config.mjs 中调整规则严重级别：

• "off" - 禁用规则
• "warn" - 警告（不会导致 CI 失败）
• "error" - 错误（会导致 CI 失败）

常见自定义方式：

• 禁用特定规则：'react/prop-types': 'off'
• 调整规则选项：'max-len': ['error', { code: 120 }]
• 添加项目专属规则

Prettier 选项

在 .prettierrc 中修改格式设置：

• printWidth - 行长度限制
• tabWidth - 每级缩进的空格数
• semi - 分号偏好
• singleQuote - 引号样式
• trailingComma - 尾随逗号规则

Lint-Staged 配置

在 package.json 中自定义提交前检查：

• 添加文件类型模式
• 添加其他命令（测试、类型检查）
• 调整哪些文件会触发哪些代码检查工具

包含类型检查的示例：

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "tsc-files --noEmit"
    ]
  }
}

故障排除

现有代码出现 ESLint 错误：运行 npm run lint:fix，然后运行 npm run format，以自动修复大多数问题。

Husky 钩子未运行：确保在初始化 Husky 后运行过 npm install。检查 .husky/pre-commit 是否具有可执行权限。

CI 失败但本地通过：确认本地和 CI 使用的 Node.js 版本一致。检查所有依赖项是否都在 package.json 中。

ESLint 与 Prettier 冲突：确保 eslint-config-prettier 位于 extends 数组的末尾，以禁用冲突的 ESLint 格式规则。

资源

scripts/

此技能不需要可执行脚本。

references/

• package-json-config.md - 完整的 package.json 示例，包含所有脚本和 lint-staged 配置
• team-documentation.md - 面向团队成员的设置说明模板

assets/

• eslint.config.mjs - ESLint v9 扁平配置模板，支持 React、TypeScript 和 Next.js
• .prettierrc - 包含推荐设置的 Prettier 配置
• .prettierignore - 要排除在格式化之外的文件和目录
• github-workflows-lint.yml - 用于自动检查代码的 GitHub Actions 工作流