Husky + lint-staged 配置说明

✅ 配置完成

你的项目现在已经配置了 Husky 和 lint-staged，在 Git 提交前自动运行代码检查和格式化。

📦 已安装的包

{
  "devDependencies": {
    "husky": "^9.1.7",
    "lint-staged": "^16.2.7"
  }
}

🔧 配置文件

1. Husky 配置

目录: .husky/

文件:

• pre-commit - 提交前执行的 hook
• _/husky.sh - Husky 辅助脚本

pre-commit 内容:

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

npx lint-staged

2. lint-staged 配置

位置: package.json 中的 lint-staged 字段

配置:

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

🚀 工作流程

自动化流程

1. git add .
   ↓
2. git commit -m "xxx"
   ↓
3. Husky 触发 pre-commit hook
   ↓
4. lint-staged 检查暂存的文件
   ↓
5. ESLint 自动修复问题
   ↓
6. Prettier 自动格式化代码
   ↓
7. 如果所有检查通过 → 提交成功 ✅
   如果有错误 → 提交失败，显示错误信息 ❌

文件类型处理

文件类型	操作
*.js, *.vue	ESLint 检查并修复 + Prettier 格式化
*.css, *.less, *.scss	Prettier 格式化
*.json, *.md	Prettier 格式化

📝 使用示例

正常提交

# 1. 修改文件
echo "console.log('test')" >> test.js

# 2. 添加到暂存区
git add test.js

# 3. 提交（自动运行 lint-staged）
git commit -m "test: add test file"

# 输出：
# ✔ prettier --write test.js
# ✔ eslint --fix test.js
# [main xxxxx] test: add test file

提交失败（有错误）

# 1. 创建有错误的文件
cat > bad.js << 'EOF'
function test() {
  var x = 1  // 缺少分号，使用了 var
  return x
}
EOF

# 2. 尝试提交
git add bad.js
git commit -m "test: bad code"

# 输出：
# ✖ eslint --fix bad.js
# ✖ 1:7  error  Unexpected var, use let or const instead  no-var
# ✖ 1:18  error  Missing semicolon
# husky - pre-commit hook exited with code 1 (error)

跳过 Hook（不推荐）

# 使用 --no-verify 跳过 hook
git commit --no-verify -m "xxx"

🛠️ 调试

测试 lint-staged

# 不实际提交，只测试 lint-staged
npx lint-staged

查看已安装的 Hooks

# 查看所有 Git hooks
ls -la .husky/

# 查看 pre-commit 内容
cat .husky/pre-commit

手动运行 Hook

# 手动执行 pre-commit hook
.husky/pre-commit

📋 常见问题

1. Hook 不执行

检查:

# 1. 检查 .husky 目录是否存在
ls -la .husky/

# 2. 检查 pre-commit 是否可执行
ls -la .husky/pre-commit

# 3. 如果不可执行，添加权限
chmod +x .husky/pre-commit

2. lint-staged 找不到文件

原因: 文件未被 git add 到暂存区

解决:

# 确保文件已添加到暂存区
git add your-file.js

# 检查暂存区文件
git status

3. 提交速度慢

原因: lint-staged 检查的文件太多

优化:

• 缩小 package.json 中 lint-staged 的匹配范围
• 只检查 src/ 目录

{
  "lint-staged": {
    "src/**/*.{js,vue}": ["eslint --fix", "prettier --write"]
  }
}

4. 想暂时禁用 Hook

方法 1 - 跳过单次提交:

git commit --no-verify -m "xxx"

方法 2 - 暂时删除 hook:

# 删除 hook
rm .husky/pre-commit

# 提交后恢复
git checkout .husky/pre-commit

🎯 最佳实践

1. 提交前检查

即使有 Husky，建议提交前也手动检查：

# 1. 格式化代码
pnpm format

# 2. Lint 检查
pnpm lint:check

# 3. 测试
pnpm test

# 4. 提交（Husky 会再次检查）
git add .
git commit -m "xxx"

2. 团队协作

确保团队成员都安装了依赖:

# 克隆项目后
pnpm install

# Husky 会自动安装（通过 prepare 脚本）

package.json 中的 prepare 脚本:

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

这确保了每次 pnpm install 后都会自动安装 Husky hooks。

3. CI/CD 集成

在 CI 中可以跳过 Husky（因为 CI 环境不使用 Git hooks）:

# .github/workflows/ci.yml
- name: Lint and format
  run: |
    pnpm lint:check
    pnpm format:check

🔄 更新配置

添加新的 Hook

# 创建 commit-msg hook（检查提交信息）
cat > .husky/commit-msg << 'EOF'
#!/usr/bin/env sh
. "$(dirname "$0")/_/husky.sh"

npx commitlint --edit $1
EOF

chmod +x .husky/commit-msg

修改 lint-staged 配置

编辑 package.json 中的 lint-staged 字段：

{
  "lint-staged": {
    "src/**/*.{js,vue}": ["eslint --fix", "prettier --write"],
    "src/**/*.{css,less}": ["prettier --write"],
    "*.md": ["prettier --write", "markdownlint --fix"]
  }
}

添加测试到 Hook

编辑 .husky/pre-commit:

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

# 运行 lint-staged
npx lint-staged

# 运行测试（可选）
pnpm test

📚 参考资源

• Husky 官方文档
• lint-staged 官方文档
• Git Hooks 文档

🎉 总结

优势:

• ✅ 自动化代码质量检查
• ✅ 保持代码风格一致
• ✅ 防止低质量代码进入仓库
• ✅ 节省手动检查时间
• ✅ 团队协作更高效

注意事项:

• ⚠️ Hook 只在本地执行，不会影响已经推送的代码
• ⚠️ 可以使用 --no-verify 跳过（不推荐）
• ⚠️ CI/CD 中应该单独运行检查（不依赖 Hook）

下一步:

• 添加 commitlint（提交信息规范）
• 添加更多 Git hooks（commit-msg、pre-push）
• 配置 CI/CD 中的质量检查

享受自动化的 Git 工作流！🚀