---
title: Husky Git Hooks 配置指南
slug: husky-git-hooks-setup
date: 2025-10-27
author: Frankie 徐
category: other
tags: ['husky', 'git-hooks', 'ci-cd', 'code-quality']
description: 基于 Husky v9 的 Git Hooks 配置指南，实现 commit 和 push 前的自动代码质量检查。
permalink: https://www.210k.cc/husky-git-hooks-setup
---

> 本文介绍如何在项目中配置 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 操作时自动运行代码质量检查
- **快速反馈**：在本地就能发现并修复问题
- **团队统一**：确保所有团队成员使用相同的质量标准
- **部署安全**：防止有问题的代码进入生产环境

## 🔧 环境准备

确保项目已安装必要依赖和脚本：

```json
{
  "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：安装和初始化

```bash
# 安装 Husky
bun add -D husky

# 初始化 Husky（v9 语法）
bunx husky init
```

### 步骤 2：配置 package.json

更新 `package.json` 中的 `prepare` 脚本：

```json
{
  "scripts": {
    "prepare": "husky"
  }
}
```

**重要**：使用 Husky v9 语法 `"husky"`，不是 v8 的 `"husky install"`。

### 步骤 3：创建 pre-commit Hook

创建 `.husky/pre-commit` 文件（**注意：v9 不需要 shebang 和 husky.sh 引用**）：

```bash
# 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` 文件：

```bash
# 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：设置执行权限

```bash
# 运行 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` 脚本自动设置。

### 错误处理机制

```bash
bun run check
if [ $? -ne 0 ]; then
  echo "❌ Check failed!"
  exit 1
fi
```

- `$?` 获取上一个命令的退出码
- `exit 1` 阻止 Git 操作继续
- 提供清晰的错误提示

## 📖 使用指南

### 正常使用

```bash
# 提交代码（自动运行 pre-commit 检查）
git commit -m "feat: add new feature"

# 推送代码（自动运行 pre-push 检查）
git push
```

### 跳过检查（紧急情况）

```bash
# 跳过 pre-commit 检查
git commit --no-verify -m "urgent fix"

# 跳过 pre-push 检查
git push --no-verify
```

## ⚡ 性能优化

### 使用 lint-staged 优化检查速度

对于大型项目，可以考虑只检查暂存的文件：

```bash
bun add -D lint-staged
```

更新 `package.json`：
```json
{
  "lint-staged": {
    "*.{js,ts,tsx}": [
      "biome check --write",
      "tsc --noEmit"
    ]
  }
}
```

更新 `.husky/pre-commit`：
```bash
echo "🧹 Running lint-staged..."
bunx lint-staged
```

### 分支差异化检查

修改 `.husky/pre-push` 实现分支策略：

```bash
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 文件开头的以下两行：
```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
```

**Q: Hook 没有执行怎么办？**

A: 检查文件权限：
```bash
chmod +x .husky/pre-commit .husky/pre-push
```

**Q: 如何手动测试 hook？**

A: 直接运行 hook 文件：
```bash
./.husky/pre-commit
./.husky/pre-push
```

**Q: 新团队成员如何设置？**

A: 克隆项目后运行：
```bash
bun install  # 自动运行 prepare 脚本
```

**Q: 找不到 `bun` 命令怎么办？**

A: 使用绝对路径：
```bash
/usr/local/bin/bun run check
```

## 🏆 最佳实践

### 分层检查策略
- **pre-commit**：快速检查（格式 + 类型）
- **pre-push**：完整检查（类型 + 构建）
- **CI/CD**：最终保障（测试 + 部署）

### Git 跟踪策略
```bash
# ✅ 应该跟踪的文件
.husky/pre-commit
.husky/pre-push

# ❌ 不应该跟踪的文件
.husky/_/
```

### 团队协作
新成员克隆项目后只需运行 `bun install`，hooks 自动生效。

## 📚 参考资源

- [Husky 官方文档](https://typicode.github.io/husky/)
- [Git Hooks 文档](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
- [lint-staged](https://github.com/okonet/lint-staged) - 只检查暂存的文件
- [commitlint](https://commitlint.js.org/) - 提交信息规范检查

## 📝 总结

通过配置 Husky Git Hooks，实现了：

✅ **自动化代码质量检查**  
✅ **团队开发标准统一**  
✅ **部署安全性保障**  
✅ **开发效率提升**  

这套配置在保证代码质量的同时，也考虑了开发体验和性能优化。

---

*最后更新：2025年10月27日*  
*作者：Frankie 徐*