一、操作背景

项目基于 Vue 框架（pnpm create vue@latest 创建），已集成 ESLint + Prettier。目标是通过 Husky（Git 钩子工具） + lint-staged（暂存区文件检查工具），实现「Git 提交前自动检查并修复暂存区代码」，保证仓库代码规范，同时避免全量检查的效率问题。

二、核心依赖关系

Git 仓库（.git 文件夹）→ Husky（依托 Git 钩子工作）→ lint-staged（由 Husky 触发，仅处理暂存区文件）

三、详细操作步骤（按实际执行顺序）

步骤 1：初始化 Git 仓库（必做前置）

Husky 依赖 Git 仓库的 .git/hooks 目录，需先初始化 Git：

git init  # 项目根目录生成 .git 文件夹，开启版本控制

步骤 2：初始化 Husky（接管 Git 钩子）

在已有 Git 仓库的基础上，初始化 Husky 生成配置目录：

1. 执行初始化命令（Windows 终端分两步，避免 && 语法报错）：

   # 第一步：临时下载 husky-init 工具，自动配置基础环境
   pnpm dlx husky-init
   # 第二步：安装 husky 依赖到项目
   pnpm install
   

2. 初始化结果验证：
   • 项目根目录新增 .husky 文件夹（存放钩子脚本）；
   • package.json 自动添加 prepare 脚本（团队成员安装依赖后自动启用 Husky）：

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

   • .husky/pre-commit 钩子文件（默认内容为 npm test，后续需修改）。

步骤 3：安装 lint-staged（暂存区检查工具）

Husky 初始化完成后，单独安装 lint-staged：

pnpm add -D lint-staged  # 安装到 devDependencies

步骤 4：分情况配置 lint-staged（核心差异点）

从这一步开始，根据「调用 lint-staged 的方式」分两种情况配置，核心功能一致，仅配置细节不同。

---

情况 1：使用 pnpm lint-staged 调用（依赖 scripts 配置）

原理：pnpm lint-staged 会读取 package.json 的 scripts 中「lint-staged 脚本入口」，间接调用工具。

4.1 配置 package.json（添加规则 + 脚本入口）

修改 package.json，新增 lint-staged 规则，并保留脚本入口：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs --fix",
    "format": "prettier --write src/",
    "prepare": "husky install",
    // 关键：添加 lint-staged 脚本入口（供 pnpm 调用）
    "lint-staged": "lint-staged"
  },
  // 核心：lint-staged 检查规则（逗号后无空格！）
  "lint-staged": {
    "*.{vue,js,ts}": "eslint --fix",  // 暂存区对应文件执行 ESLint 修复
    "*.{css,scss,md,json}": "prettier --write"  // 可选：Prettier 格式化
  }
}

4.2 修改 pre-commit 钩子（触发 lint-staged）

打开 .husky/pre-commit 文件，将默认的 npm test 改为 pnpm lint-staged：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 调用 lint-staged（通过 scripts 入口）
pnpm lint-staged

---

情况 2：使用 npx lint-staged 调用（不依赖 scripts 配置）

原理：npx 可直接调用 node_modules 中已安装的 lint-staged 工具，无需通过 scripts 中转。

4.1 配置 package.json（仅添加规则，无需脚本入口）

修改 package.json，仅保留 lint-staged 规则，删除冗余脚本入口：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs --fix",
    "format": "prettier --write src/",
    "prepare": "husky install"
    // 无需添加 "lint-staged": "lint-staged"（冗余）
  },
  // 核心：lint-staged 检查规则（逗号后无空格！）
  "lint-staged": {
    "*.{vue,js,ts}": "eslint --fix",
    "*.{css,scss,md,json}": "prettier --write"  // 可选
  }
}

4.2 修改 pre-commit 钩子（触发 lint-staged）

打开 .husky/pre-commit 文件，将默认的 npm test 改为 npx lint-staged：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 直接调用 node_modules 中的 lint-staged（无需 scripts 中转）
npx lint-staged

---

步骤 5：处理 ESLint 扁平配置兼容问题（若使用 eslint.config.js）

若项目用 ESLint 扁平配置（eslint.config.js），需注意：

• 扁平配置不支持 --ignore-path 命令行参数（会报错 “Invalid option”）；
• 替代方案：在 eslint.config.js 中用 globalIgnores 定义忽略规则（参考 .gitignore）：

  import { defineConfig, globalIgnores } from 'eslint/config'
  
  export default defineConfig([
    // 忽略规则（替代 --ignore-path .gitignore）
    globalIgnores([
      'node_modules/',
      'dist/',
      '.git/',
      '.env*'
    ]),
    // 其他 ESLint 配置...
  ])
  

四、验证配置效果（两种方式通用）

1. 暂存修改文件：

   git add 任意修改后的 .vue 或 .js 文件  # 仅暂存需要提交的文件
   

2. 执行提交命令：

   git commit -m "测试 Husky + lint-staged 配置"
   

3. 预期结果：
   • 提交前自动触发 lint-staged，控制台显示检查 / 修复过程；
   • 可修复问题（如格式错误、引号转换）会被自动修复；
   • 不可修复错误（如未定义变量）会阻断提交，需手动修复后重试。

五、常见问题与解决方案

问题现象	原因	解决方案
初始化 Husky 报错 “.git can't be found”	未执行 git init，项目不是 Git 仓库	先执行 git init，再重新初始化 Husky
提交时报错 “Missing script: 'lint-staged'”	用 pnpm lint-staged 调用，但 scripts 中无入口	在 scripts 中添加 "lint-staged": "lint-staged"
lint-staged 未检查 .js 文件	规则中逗号后有空格（如 *.{vue, js}）	去掉空格，改为 *.{vue,js,ts}
ESLint 报错 “Invalid option '--ignore-path'”	使用 ESLint 扁平配置，不支持该参数	移除 --ignore-path，在 eslint.config.js 中用 globalIgnores 配置
提交时报错 “npm error Missing script: 'test'”	pre-commit 钩子未修改默认的 npm test	将钩子中的 npm test 改为对应调用命令（pnpm lint-staged 或 npx lint-staged）

六、两种调用方式对比与选择建议

维度	pnpm lint-staged 方式	npx lint-staged 方式
依赖 scripts 配置	是（需保留入口）	否（直接调用）
配置冗余度	略高（多 1 行脚本）	极简（无冗余）
手动执行便利性	方便（pnpm lint-staged）	略繁琐（npx lint-staged）
适用场景	团队习惯统一管理 scripts 命令	追求简洁配置，仅自动触发无需手动执行

选择建议

• 若团队协作，需统一命令规范，选 pnpm lint-staged（便于新人查阅）；
• 若个人开发，追求少配置，选 npx lint-staged（省去维护脚本入口的成本）。

七、核心逻辑总结

1. 流程合理性：先初始化 Git 仓库（Husky 依赖）→ 初始化 Husky（接管钩子）→ 配置 lint-staged（精准检查暂存区），完全符合工具依赖链条；
2. 最终效果：两种调用方式功能一致，均能实现「提交前自动修复暂存区代码、阻断不规范提交」，兼顾代码质量和执行效率。