ESLint 提交前校验技术方案

1. 背景与动机

在大型前端项目中，保持统一的代码风格和高质量的代码是提高开发效率、降低维护成本的关键。将 ESLint 校验集成到 git commit 之前的钩子中，可以：

即时拦截不规范代码，避免问题流入主干分支。
减轻 CI 负担，在本地解决大部分格式和规范问题。
提升团队协作体验，开发者无需手动运行 ESLint，就能获得反馈。
自动化修复 ，通过 --fix 自动调整可修复的警告。

2. Husky v9 下的正确配置流程

Husky v9 已移除对 husky install 和 husky add 命令的支持，推荐使用无参 husky 命令来初始化，再手动创建钩子脚本：

步骤 1：初始化 Husky

csharp 复制代码

pnpm dlx husky init

此命令会在项目根生成 .husky/ 目录，并在 package.json 中自动添加：

json 复制代码

{
  "scripts": {
    "prepare": "husky"
  }
}

该 prepare 脚本的作用是：当使用 pnpm/npm/yarn 安装或更新依赖时，包管理器会自动运行 prepare 脚本中的 husky 命令，从而初始化或同步 .husky/ 目录及内部钩子脚本。这样无需手动执行初始化命令，在拉取分支或更新依赖后，Husky 钩子就会自动生成或更新，保证本地环境和团队钩子保持一致。

步骤 2：创建 `pre-commit` 钩子脚本

在 .husky/ 目录下创建 pre-commit 文件，并写入：

bash 复制代码

# 使用单引号避免 zsh 历史扩展
echo '#!/usr/bin/env sh' > .husky/pre-commit
echo '. "$(dirname -- "$0")/_/husky.sh"' >> .husky/pre-commit
echo 'pnpm dlx lint-staged' >> .husky/pre-commit

提示：若在双引号中出现 !，zsh 可能报 event not found，故推荐单引号。

步骤 3：赋予执行权限

bash 复制代码

chmod +x .husky/pre-commit

作用：Git 钩子脚本需具备可执行权限才能在 git commit 时被触发，否则系统会忽略此脚本。对于类 Unix 系统（macOS、Linux），务必手动执行上述命令；在 Windows（Git Bash、WSL）环境中同样需要设置。不用此步骤会导致 .husky/pre-commit 无法执行。

步骤 4：配置 `lint-staged`

在 package.json 中添加：

css 复制代码

{
  "lint-staged": {
    "src/**/*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "git add"
    ]
  }
}

这样，git commit 时：

Husky 触发 .husky/pre-commit 脚本
lint-staged 仅对暂存文件执行 eslint --fix
如果仍有错误，返回非 0 状态码，阻止提交

3. 验证效果

perl 复制代码

$ git commit -m "feat: 新增用户登录功能"
Running ESLint...
src/login.js
  10:5  error  "userInfo" is defined but never used  no-unused-vars

ESLint 校验未通过，请修复后再提交。

通过上述流程，可在提交前强制 ESLint 校验并自动修复，确保代码库一直保持高质量、统一风格。