本文介绍如何在项目中配置 Husky v9，实现 commit 和 push 前的自动代码质量检查，确保代码质量和部署安全。
版本兼容性
⚠️ 重要: 本教程适用于 Husky v9.x 及以上版本。
- Husky v8: 使用
husky install和 shebang 语法 - Husky v9: 使用
husky init和简化语法（推荐） - Husky v10: 将完全移除对 v8 语法的支持
如果您使用的是 v8，请升级到 v9 或参考对应版本文档。
🎯 为什么使用 Husky？
在团队开发中，经常遇到以下问题：
- 代码格式不统一，影响可读性
- TypeScript 类型错误导致运行时问题
- 构建失败但已推送到远程仓库
- 部署时才发现代码问题，影响发布流程
Husky 通过 Git Hooks 在提交和推送时自动运行代码质量检查，实现：
- 自动化检查：在 Git 操作时自动运行代码质量检查
- 快速反馈：在本地就能发现并修复问题
- 团队统一：确保所有团队成员使用相同的质量标准
- 部署安全：防止有问题的代码进入生产环境
🔧 环境准备
确保项目已安装必要依赖和脚本：
{
"devDependencies": {
"@biomejs/biome": "1.9.4",
"husky": "^9.1.7",
"typescript": "^5.8.2"
},
"scripts": {
"build": "next build",
"typecheck": "tsc --noEmit",
"check": "biome check .",
"check:write": "biome check --write ."
}
}
⚙️ 配置步骤
步骤 1：安装和初始化
# 安装 Husky
bun add -D husky
# 初始化 Husky（v9 语法）
bunx husky init
步骤 2：配置 package.json
更新 package.json 中的 prepare 脚本：
{
"scripts": {
"prepare": "husky"
}
}
重要：使用 Husky v9 语法 "husky"，不是 v8 的 "husky install"。
步骤 3：创建 pre-commit Hook
创建 .husky/pre-commit 文件（注意：v9 不需要 shebang 和 husky.sh 引用）：
# Git hook: pre-commit
# Fast checks only – lint + type (bun)
echo "🧹 Running code quality checks..."
echo "📝 Checking code style with Biome..."
bun run check:write
if [ $? -ne 0 ]; then
echo "❌ Biome check failed! Please fix the issues above."
exit 1
fi
echo "🔍 Type checking..."
bun run typecheck
if [ $? -ne 0 ]; then
echo "❌ Type check failed! Please fix the type errors above."
exit 1
fi
echo "✅ Pre-commit checks passed!"
步骤 4：创建 pre-push Hook
创建 .husky/pre-push 文件：
# Git hook: pre-push
# Heavy check – build to catch compile-time issues (bun)
echo "🔍 Running type check..."
bun run typecheck
if [ $? -ne 0 ]; then
echo "❌ Type check failed!"
exit 1
fi
echo "🏗️ Testing production build..."
bun run build
if [ $? -ne 0 ]; then
echo "❌ Build failed! Push cancelled."
exit 1
fi
echo "✅ All checks passed! Pushing to remote..."
步骤 5：设置执行权限
# 运行 prepare 脚本（自动设置权限）
bun run prepare
# 手动设置权限（如果需要）
chmod +x .husky/pre-commit .husky/pre-push
🔍 工作原理
Git Hooks 在特定的 Git 操作时自动执行脚本：
- pre-commit: 在
git commit前执行，用于快速检查 - pre-push: 在
git push前执行，用于完整验证
Husky 将这些 hooks 存储在 .husky/ 目录中，通过 prepare 脚本自动设置。
错误处理机制
bun run check
if [ $? -ne 0 ]; then
echo "❌ Check failed!"
exit 1
fi
-
$?获取上一个命令的退出码 -
exit 1阻止 Git 操作继续 - 提供清晰的错误提示
📖 使用指南
正常使用
# 提交代码（自动运行 pre-commit 检查）
git commit -m "feat: add new feature"
# 推送代码（自动运行 pre-push 检查）
git push
跳过检查（紧急情况）
# 跳过 pre-commit 检查
git commit --no-verify -m "urgent fix"
# 跳过 pre-push 检查
git push --no-verify
⚡ 性能优化
使用 lint-staged 优化检查速度
对于大型项目，可以考虑只检查暂存的文件：
bun add -D lint-staged
更新 package.json：
{
"lint-staged": {
"*.{js,ts,tsx}": [
"biome check --write",
"tsc --noEmit"
]
}
}
更新 .husky/pre-commit：
echo "🧹 Running lint-staged..."
bunx lint-staged
分支差异化检查
修改 .husky/pre-push 实现分支策略：
branch="$(git rev-parse --abbrev-ref HEAD)"
# 只在主分支进行完整检查
if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
echo "🚨 Pushing to protected branch, running full checks..."
bun run typecheck || exit 1
bun run build || exit 1
else
echo "🔍 Running type check only (feature branch)..."
bun run typecheck || exit 1
fi
echo "✅ All checks passed! Pushing to remote..."
🔧 故障排除
常见问题
Q: 看到 “DEPRECATED” 警告怎么办？
A: 删除 hook 文件开头的以下两行：
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
Q: Hook 没有执行怎么办？
A: 检查文件权限：
chmod +x .husky/pre-commit .husky/pre-push
Q: 如何手动测试 hook？
A: 直接运行 hook 文件：
./.husky/pre-commit
./.husky/pre-push
Q: 新团队成员如何设置？
A: 克隆项目后运行：
bun install # 自动运行 prepare 脚本
Q: 找不到 bun 命令怎么办？
A: 使用绝对路径：
/usr/local/bin/bun run check
🏆 最佳实践
分层检查策略
- pre-commit：快速检查（格式 + 类型）
- pre-push：完整检查（类型 + 构建）
- CI/CD：最终保障（测试 + 部署）
Git 跟踪策略
# ✅ 应该跟踪的文件
.husky/pre-commit
.husky/pre-push
# ❌ 不应该跟踪的文件
.husky/_/
团队协作
新成员克隆项目后只需运行 bun install，hooks 自动生效。
📚 参考资源
- Husky 官方文档
- Git Hooks 文档
- lint-staged - 只检查暂存的文件
- commitlint - 提交信息规范检查
📝 总结
通过配置 Husky Git Hooks，实现了：
✅ 自动化代码质量检查
✅ 团队开发标准统一
✅ 部署安全性保障
✅ 开发效率提升
这套配置在保证代码质量的同时，也考虑了开发体验和性能优化。
最后更新：2025年10月27日
作者：Frankie 徐