262 lines
7.6 KiB
Markdown
262 lines
7.6 KiB
Markdown
|
---
|
|||
|
|
tags: [git, husky, pre-commit, hooks, lint]
|
|||
|
|
create time: 2026-04-30 14:45
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Husky — Git Hooks 管理工具
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
Husky 是 Node.js 生态中最流行的 Git Hooks 管理工具之一，它简化了 `pre-commit`、`commit-msg`、`push` 等钩子的配置和运行流程，让代码质量检查能够自动在提交前执行。
|
|||
|
|
|
|||
|
|
> [!tip] 为什么需要 Git Hooks？
|
|||
|
|
> 在团队协作中，手动遵守代码规范几乎不可能——lint 错误、未格式化、测试失败等问题经常流入仓库。Git Hooks 能在代码提交前自动拦截这些问题，把质量防线前置到客户端而非 CI 阶段。
|
|||
|
|
|
|||
|
|
## 核心概念
|
|||
|
|
|
|||
|
|
### 什么是 Git Hooks？
|
|||
|
|
|
|||
|
|
Git 在每个操作完成后会自动查找并执行 `.git/hooks/` 目录下的对应脚本文件。最常见的 Hook 包括：
|
|||
|
|
|
|||
|
|
| Hook 名称 | 触发时机 | 典型用途 |
|
|||
|
|
|-----------|----------|----------|
|
|||
|
|
| `pre-commit` | 执行 `git commit` 时，commit 之前 | 代码 lint、格式化、单元测试 |
|
|||
|
|
| `commit-msg` | pre-commit 成功后 | 校验 Commit Message 格式（如 Conventional Commits） |
|
|||
|
|
| `pre-push` | 执行 `git push` 之前 | 全量测试、安全检查 |
|
|||
|
|
| `post-commit` | commit 成功后 | 通知、日志记录 |
|
|||
|
|
|
|||
|
|
> [!question] 思考
|
|||
|
|
> 如果某个 Hook 执行返回非零退出码（exit code ≠ 0），会发生什么？
|
|||
|
|
> —— Git 会中止当前操作，阻止代码被提交或推送。这就是"拦截"的本质。
|
|||
|
|
|
|||
|
|
**关键点**：原生 Git Hooks 存在一个痛点——它们存储在 `.git/` 目录下，不会随版本库同步。每个开发者都需要手动配置，容易遗漏或不一致。
|
|||
|
|
|
|||
|
|
### Husky 如何解决这个问题？
|
|||
|
|
|
|||
|
|
Husky 的核心理念：**将 Hook 配置写入 `package.json`（即代码仓库本身），通过 `npx husky install` 自动生成 `.git/hooks/` 目录下的脚本。**
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TD
|
|||
|
|
Repo["代码仓库 Git"] --> Package["package.json 声明 Husky hooks"]
|
|||
|
|
Repo --> HuskyDir[".husky/ 目录 pre commit etc"]
|
|||
|
|
HuskyDir -- "npx husky install" --> GitHooks[".git/hooks/ 自动生成的 shell 链接"]
|
|||
|
|
|
|||
|
|
classDef repo fill:#dbeafe,color:#1e3a8a
|
|||
|
|
classDef dir fill:#fef3c7,color:#92400e
|
|||
|
|
classDef target fill:#dcfce7,color:#166534
|
|||
|
|
class Repo repo
|
|||
|
|
class HuskyDir dir
|
|||
|
|
class GitHooks target
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
这种设计带来的好处：
|
|||
|
|
1. **Hook 配置与代码同源** — 团队成员克隆后只需一条命令即可生效
|
|||
|
|
2. **版本控制** — Hook 脚本的变更可追溯、可 Review
|
|||
|
|
3. **易于维护** — 集中管理，无需分散在各开发者的本地配置中
|
|||
|
|
|
|||
|
|
## 安装与配置
|
|||
|
|
|
|||
|
|
### 步骤一：安装
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# npm
|
|||
|
|
npm install husky --save-dev
|
|||
|
|
|
|||
|
|
# yarn
|
|||
|
|
yarn add husky --dev
|
|||
|
|
|
|||
|
|
# pnpm
|
|||
|
|
pnpm add husky -D
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 步骤二：初始化
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Husky v9+ 使用 pkg-manager 模式
|
|||
|
|
npx husky init
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
这会自动完成两件事：
|
|||
|
|
1. 创建 `.husky/` 目录
|
|||
|
|
2. 生成 `.husky/pre-commit` 示例脚本
|
|||
|
|
3. 在 `package.json` 中添加 `"prepare"` 脚本
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"scripts": {
|
|||
|
|
"prepare": "husky"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!note] 为什么用 `prepare` 脚本？
|
|||
|
|
> 当其他开发者执行 `npm install` / `yarn install` / `pnpm install` 时，`prepare` 会自动运行，相当于一次性完成 Husky 初始化。这样就不需要每个人都手动执行 `npx husky init` 了。
|
|||
|
|
|
|||
|
|
### 步骤三：添加更多 Hook
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 创建 commit-msg hook
|
|||
|
|
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'
|
|||
|
|
|
|||
|
|
# 创建 pre-push hook
|
|||
|
|
npx husky add .husky/pre-push 'npm test'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
每个生成的 `.husky/` 目录下的文件都是一个简单的 Shell 脚本：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
#!/usr/bin/env sh
|
|||
|
|
.nvm/default/node_modules/husky/run.js node "cypress"
|
|||
|
|
# 或直接执行命令
|
|||
|
|
npm run lint
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 实战集成
|
|||
|
|
|
|||
|
|
### 集成 Lint + Format
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# .husky/pre-commit
|
|||
|
|
npx lint-staged
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
配合 `lint-staged` 只处理暂存的文件，大幅加快执行速度：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"lint-staged": {
|
|||
|
|
"*.{js,ts,jsx,tsx}": ["eslint --fix", "prettier --write"],
|
|||
|
|
"*.json": ["prettier --write"]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 集成 Commit Message 校验
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# .husky/commit-msg
|
|||
|
|
npx --no-install commitlint --edit "$1"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Commitlint 规则示例：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
// commitlint.config.js
|
|||
|
|
module.exports = {
|
|||
|
|
extends: ['@commitlint/config-conventional'],
|
|||
|
|
rules: {
|
|||
|
|
'type-enum': [2, 'always', [
|
|||
|
|
'feat', 'fix', 'docs', 'style', 'refactor',
|
|||
|
|
'test', 'chore', 'perf'
|
|||
|
|
]]
|
|||
|
|
}
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Husky Hooks 执行流程
|
|||
|
|
|
|||
|
|
提交时的 Hook 拦截链路如下：
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart TD
|
|||
|
|
Start["git commit"] --> PreCommit{"pre-commit"}
|
|||
|
|
PreCommit -->|"lint/format pass"| Stage["暂存文件已提交"]
|
|||
|
|
PreCommit -->|"lint/format fail"| BlockPre["Hook 中止提交"]
|
|||
|
|
Stage --> CommitMsg{"commit-msg"}
|
|||
|
|
CommitMsg -->|"格式正确"| Success["commit 成功"]
|
|||
|
|
CommitMsg -->|"格式错误"| BlockCommit["Hook 中止提交"]
|
|||
|
|
|
|||
|
|
classDef fail fill:#f99
|
|||
|
|
classDef success fill:#9f9
|
|||
|
|
class BlockPre,BlockCommit fail
|
|||
|
|
class Success success
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!tip] Hook 的退出码机制
|
|||
|
|
> 每个 Hook 脚本通过 exit code 决定 Git 是否继续——返回 `0` 表示成功放行，返回非 `0` 则中断整个操作。
|
|||
|
|
|
|||
|
|
## 常见场景与技巧
|
|||
|
|
|
|||
|
|
### 跳过 Hook（仅个人调试）
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git commit --no-verify
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> [!warning] 安全警告
|
|||
|
|
> `--no-verify` 仅用于紧急调试！不要在 PR 提交时使用，这会绕过所有质量检查。
|
|||
|
|
|
|||
|
|
### Conditional Husky
|
|||
|
|
|
|||
|
|
Husky v8+ 支持条件执行，避免在 CI 环境中浪费资源：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
if [ "$CI" != "true" ]; then
|
|||
|
|
npx lint-staged
|
|||
|
|
fi
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Windows 兼容性
|
|||
|
|
|
|||
|
|
Husky v9+ 已内置良好的 Windows 支持，但需注意：
|
|||
|
|
- 确保系统安装了 `sh`（Windows 上的 Git Bash 自带）
|
|||
|
|
- 或在 `.husky/_/husky.sh` 中配置 PowerShell 作为 shell 替代品
|
|||
|
|
|
|||
|
|
### 大型项目的性能优化
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"lint-staged": {
|
|||
|
|
// 按语言分组处理，充分利用并行
|
|||
|
|
"*.{js,ts}": ["eslint --cache --fix"],
|
|||
|
|
"*.{css,scss}": ["stylelint --fix"],
|
|||
|
|
"*.{png,jpg,svg}": ["imagemin"]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
结合 `turbo` 或 `nx` 做增量构建，只重新验证有变化的文件。
|
|||
|
|
|
|||
|
|
## 与其他方案的对比
|
|||
|
|
|
|||
|
|
| 方案 | 配置方式 | 跨平台 | 社区规模 | 推荐场景 |
|
|||
|
|
|------|----------|--------|----------|----------|
|
|||
|
|
| **Husky** | JS/JSON 声明式 | ✅ 好 | ⭐⭐⭐⭐⭐ | Node.js / JS 项目首选 |
|
|||
|
|
| **Pre-commit (Python)** | YAML 配置文件 | ✅ 好 | ⭐⭐⭐⭐ | 多语言混合项目 |
|
|||
|
|
| **Ruff + Git Hook** | Shell 脚本 | ✅ 好 | ⭐⭐⭐ | Python 项目快速集成 |
|
|||
|
|
| **Rust (cargo-husky)** | Cargo 构建脚本 | ✅ 好 | ⭐⭐ | Rust 项目 |
|
|||
|
|
|
|||
|
|
> [!info] 选型建议
|
|||
|
|
> 如果你的项目是 Node.js 技术栈，Husky 是最自然的选择——零额外依赖，与 npm/yarn/pnpm 生态无缝集成。对于 Go/Rust/Python 混合项目，可以考虑 [pre-commit](https://pre-commit.com/) 框架，它用 YAML 统一管理多种语言的 Hook。
|
|||
|
|
|
|||
|
|
## 进阶：CI 与 Hooks 的配合策略
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant Dev as Developer
|
|||
|
|
participant HG as Husky Hook
|
|||
|
|
participant CI as CI Pipeline
|
|||
|
|
participant MR as Merge Request
|
|||
|
|
|
|||
|
|
Dev->>HG: git commit
|
|||
|
|
HG->>HG: lint-staged + format
|
|||
|
|
alt Hook pass
|
|||
|
|
HG-->>Dev: submit successful
|
|||
|
|
Dev->>MR: git push and open MR
|
|||
|
|
MR->>CI: trigger CI
|
|||
|
|
CI->>CI: full test suite
|
|||
|
|
CI-->>MR: report result
|
|||
|
|
else Hook fail
|
|||
|
|
HG-->>Dev: blocked by hook
|
|||
|
|
Note over Dev,HG: Fix issues then commit again
|
|||
|
|
end
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**最佳实践**：
|
|||
|
|
- **客户端 Hook**（Husky）：快速反馈，只检查暂存文件 + Commit Message 格式
|
|||
|
|
- **服务端 CI**：完整测试套件 + 安全扫描 + 构建验证
|
|||
|
|
- 两者互为补充，前者保体验，后者保安全
|
|||
|
|
|
|||
|
|
## 关联笔记
|
|||
|
|
|
|||
|
|
- [[CLAUDE.md]] — Agent 行为配置参考
|