Git Hooks 自动化工作流配置

小马 工具&效率 511 次阅读 2026-07-23

Git Hooks 自动化工作流配置

Git Hooks 是 Git 提供的一种脚本触发机制,允许你在特定的 Git 操作前后自动执行自定义脚本。常见的用途包括:代码风格检查、单元测试运行、提交信息规范检查、自动部署等。通过在 .git/hooks/ 目录下放置可执行脚本,Git 会在相应事件触发时自动运行它们。

Git 提供了多种钩子类型,按触发时机分为客户端钩子和服务端钩子。客户端钩子在本地操作时触发,如 pre-commit、commit-msg;服务端钩子在 git push 到远程时触发,如 pre-receive、post-receive。

常用客户端钩子

pre-commit:在 git commit 执行前触发,常用于代码风格检查、语法验证、Lint 检查。如果脚本返回非零值,提交将被拒绝。

# .git/hooks/pre-commit
#!/bin/bash

echo "运行 pre-commit 检查..."

检查 JavaScript 文件语法

for file in $(git diff --cached --name-only --diff-filter=ACM | grep ".js$"); do node --check "$file" || exit 1 done

运行 ESLint

if [ -f "package.json" ]; then npx eslint $(git diff --cached --name-only --diff-filter=ACM | grep ".js$") || exit 1 fi

echo "pre-commit 检查通过"
exit 0

commit-msg:在提交信息填写完毕后、提交创建前触发,常用于验证提交信息格式。

# .git/hooks/commit-msg
#!/bin/bash

commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|test|chore)((.+))?: .{1,50}"

if ! [[ "$commit_msg" =~ $pattern ]]; then
echo "提交信息格式错误!"
echo "格式要求: type(scope): description"
echo "示例: feat(login): 添加第三方登录功能"
exit 1
fi

exit 0

post-commit:在提交完成后触发,常用于通知、构建触发等。

# .git/hooks/post-commit
#!/bin/bash

echo "提交完成: $(git log -1 --oneline)"

触发 CI 构建


curl -s "https://ci.example.com/build?commit=$(git rev-parse HEAD)" > /dev/null || true

常用服务端钩子

pre-receive:在远程仓库收到推送前执行,常用于强制推送规范检查、权限控制。

# .git/hooks/pre-receive
#!/bin/bash

while read oldrev newrev refname; do
branch=$(echo "$refname" | sed "s/refs/heads///")

# 禁止向 main 分支强制推送
if [ "$branch" = "main" ] && [ "$oldrev" != "0000000000000000000000000000000000000000" ]; then
echo "禁止向 main 分支强制推送"
exit 1
fi
done

exit 0

post-receive:在推送被接受后执行,常用于自动部署。

# .git/hooks/post-receive
#!/bin/bash

branch=$(echo "$refname" | sed "s/refs/heads///")

if [ "$branch" = "main" ]; then
echo "开始部署到生产环境..."
cd /var/www/app || exit
git pull origin main
npm install
pm2 restart app
echo "部署完成"
fi

使用 Husky 管理 Git Hooks

手动管理 .git/hooks 容易遗忘,且不便团队同步。使用 Husky 可以将钩子脚本纳入版本控制。

npm install husky --save-dev

初始化 husky(会在 .husky/ 目录创建钩子)

npx husky install

添加 pre-commit 钩子

npx husky add .husky/pre-commit "npm run lint" npx husky add .husky/commit-msg "npx commitlint --edit $1"

提交 .husky 配置到版本控制

git add .husky git commit -m "添加 Git Hooks 配置"

跳过钩子

临时跳过 pre-commit 钩子
git commit --no-verify -m "紧急提交,跳过检查"

跳过 commit-msg 钩子
git commit --no-verify -m "quick fix"

注意事项

    • .git/hooks/ 目录下的示例脚本以 .sample 为后缀,Git 不会自动执行它们,需要去掉后缀并添加执行权限
    • 钩子脚本要有执行权限(chmod +x),否则 Git 无法运行
    • pre-commit 等钩子中避免执行耗时过长的操作,会影响开发体验
  • Husky 只管理客户端钩子,服务端钩子需要在远程仓库服务器上配置
  • 钩子脚本中的路径是相对于 .git/hooks/ 目录的

Git Hooks 是实现团队规范化、自动化的重要工具,合理利用能显著提升代码质量和协作效率。

原理与机制

Git 的GitHooks自动化工作流配置建立在对象模型之上:文件内容经哈希后成为 blob,目录成为 tree,一次提交则是一个指向 tree 的 commit 对象。分支只是一个指向某个 commit 的可移动引用,切换分支本质上就是把引用指向不同的 commit。正因为引用可以随意移动,Git 才需要 reflog 来记录引用的移动历史——这也是误删分支后仍能恢复的原因。

提交对象记录的是父提交的哈希,因此提交历史天然构成一条有向无环图。合并会在两个父提交之上生成一个新提交,rebase 则是把一系列提交摘下来重新生成——提交哈希会全部改变。这就是「已经推送过的提交不要 rebase」的底层原因:改写历史会让协作者的本地分支与远端失去共同祖先。

冲突的本质是同一个文件的同一区域被两个分支做了不同修改。Git 能自动合并不同区域、相同行的增删,但当两边的修改语义重叠时必须由人决定。解决冲突的正确流程是:三方合并理解双方意图、编辑冲突标记、git add 标记已解决、提交。切忌用 -X ours 或 -X theirs 一把梭,那只是把选择权交给 Git 而非你自己。

实战场景

在功能开发场景中,GitHooks自动化工作流配置的标准流程是:从主干切出特性分支、开发并提交、合并回主干后删除分支。保持主干随时可发布,是协作纪律的基础。

在线上紧急修复场景中,应从生产标签切出修复分支,修复合并后同样把修复回合到主干,而不是直接在主干上提交——否则主干会与其他人的开发产生冲突。

在代码评审场景中,评审者关注的是变更意图而非逐行挑错:先确认这个改动解决什么问题,再检查实现方式与边界条件,最后确认有对应的测试。

常见陷阱

陷阱一:把密钥或大文件提交进仓库。提交后再删除并不能消除历史,必须配合 git filter-repo 清理并轮换密钥;.gitignore 要在首次提交前就配好。

陷阱二:对已推送的提交执行 rebase 或 reset。这会改写历史并让协作者无法同步。共享分支上的修正应该用 git revert 生成新提交。

陷阱三:误用 git checkout -- . 丢弃改动。这条命令会不可逆地覆盖工作区所有未提交修改。执行前先 git stash 或 git diff > patch 备份。

最佳实践

提交粒度要小且语义单一。一次提交只做一件事,写清楚「为什么改」而不只是「改了什么」,方便日后追溯与挑选回滚。

提交前必看 diff。git diff --staged 能避免误提交调试输出、临时文件与密钥。

定期同步主干。用 git fetch 加上 git rebase origin/main(仅限自己的特性分支)保持提交历史线性,减少合并冲突的堆积。