如何搭建一套基于 Git Hooks 的自动化代码质量准入流水线

pre-commit用于本地快速拦截，post-receive用于服务端部署；前者禁用耗时操作和.git目录外依赖，后者须通过--work-tree配合裸仓库执行checkout，并统一用husky或setup-hooks.sh管理同步。

能，但必须分清客户端和服务端职责，否则上线即崩。 pre-commit 负责本地拦截，post-receive 才能触发部署，两者混用或错放位置是绝大多数失败案例的根源。

pre-commit 钩子该检查什么、不该检查什么

它只运行在开发者本地，执行时间必须短（理想

• 代码格式：用 prettier --check 或 eslint --quiet 扫描暂存区文件（git diff --cached --name-only 获取）
• 敏感词扫描：git diff --cached -U0 | grep -q "password|API_KEY" && echo "⚠️ 检测到疑似密钥" && exit 1
• 提交信息规范：commit-msg 单独处理，别塞进 pre-commit
• 禁止做：跑全量单元测试、构建产物、调远程 API——这些应交给 pre-push 或 CI

pre-push 钩子是质量门禁的关键一环

它在 git push 发出前触发，适合执行稍重但仍有意义的拦截，比如：

• 仅对即将推送的 commit 运行测试：npm test -- --changedSince=origin/main
• 校验 package.json 依赖是否已安装：! npm ls &> /dev/null && echo "❌ node_modules 缺失" && exit 1
• 检查是否有未提交的 .env 文件：git status --porcelain | grep ".env$" && echo "❌ .env 文件未提交或被忽略" && exit 1
• 注意：Windows 用户需确保脚本用 #!/usr/bin/env bash 开头，避免 /bin/bash 路径失效

post-receive 钩子不能直接写部署逻辑

它运行在裸仓库（bare repo）里，没有工作目录，git checkout 会失败。正确做法是：

• 在钩子中只做两件事：cd 到目标部署路径 + 执行一个外部 deploy.sh
• deploy.sh 里用 git --work-tree=/path/to/site --git-dir=/path/to/bare.git checkout -f
• 务必加 chmod +x 权限，且脚本第一行必须是 #!/usr/bin/env bash
• 错误日志要重定向：把 2>&1 >> /var/log/deploy.log 加到命令末尾，否则失败时完全看不到原因

真正难的不是写脚本，而是让所有成员的 .git/hooks/ 同步更新——没人会手动复制，也没人记得 chmod +x。用 husky 或自建 setup-hooks.sh 注册到 package.json postinstall 才是可持续方案。