提交钩子脚本怎么写？

wen 实用脚本 2026-06-05 44

提交钩子脚本怎么写？从零到一构建自动化工作流

📚 目录导读

什么是提交钩子脚本？
为什么需要提交钩子脚本？
主流版本控制系统的钩子类型
提交钩子脚本的编写步骤（含代码示例）
常见问题与最佳实践
问答环节：解决你的真实困惑

什么是提交钩子脚本？

提交钩子脚本（Commit Hook Script）是在版本控制系统的特定事件（如代码提交、合并、推送）触发时自动执行的一组自定义命令或程序，它像一个“守门员”，在代码进入仓库前进行验证、格式化、测试或通知。

提交钩子脚本怎么写？

常见场景包括：

强制代码风格检查（如ESLint、Prettier）
禁止提交敏感信息（如密码、API密钥）
自动运行单元测试
生成提交信息模板
触发CI/CD流水线

为什么需要提交钩子脚本？

痛点场景	钩子解决方案
提交了未通过编译的代码	在pre-commit阶段运行编译检查
团队风格不统一	自动格式化并拒绝不符合规范的代码
误提交了.env文件	扫描提交内容并拦截敏感文件
忘记写有意义的commit message	验证提交信息格式

主流版本控制系统的钩子类型

Git钩子（最常用）

Git钩子位于项目根目录的.git/hooks/文件夹内，默认以.sample后缀存在，主要分为两类：

客户端钩子：在开发者本地触发
- pre-commit：提交前触发，常用于代码检查
- commit-msg：提交信息编辑后触发，用于格式验证
- post-commit：提交完成后触发，用于通知
服务端钩子：在远程仓库触发
- pre-receive：推送前触发，可进行权限校验
- update：分支更新时触发
- post-receive：推送完成后触发，常用于自动部署

其他系统（简略）

SVN：通过hooks目录下的pre-commit.tmpl等文件实现
Mercurial：使用.hg/hgrc配置钩子

提交钩子脚本的编写步骤（含代码示例）

1 Git pre-commit钩子编写（最常用案例）

目标：在提交前自动运行ESLint检查并格式化代码，如果检测到错误则阻止提交。

步骤1：创建可执行钩子文件

cd your-project/.git/hooks
touch pre-commit
chmod +x pre-commit  # Linux/Mac赋予执行权限

步骤2：编写脚本内容

#!/bin/sh
# pre-commit钩子脚本：检查JavaScript/TypeScript文件
# 定义颜色变量用于输出
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color
echo "🔍 正在执行pre-commit检查..."
# 1. 获取本次提交的暂存区文件
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx)$')
if [ -z "$STAGED_FILES" ]; then
    echo -e "${GREEN}✅ 没有需要检查的JS/TS文件${NC}"
    exit 0
fi
# 2. 运行ESLint检查（需要项目已安装eslint）
echo "运行ESLint..."
npx eslint $STAGED_FILES
if [ $? -ne 0 ]; then
    echo -e "${RED}❌ ESLint检查失败，提交被阻止${NC}"
    exit 1
fi
# 3. 运行Prettier格式化
echo "运行Prettier格式化..."
npx prettier --check $STAGED_FILES
if [ $? -ne 0 ]; then
    echo "尝试自动格式化..."
    npx prettier --write $STAGED_FILES
    git add $STAGED_FILES
    echo -e "${GREEN}✅ 文件已格式化并重新暂存${NC}"
fi
# 4. 全部通过
echo -e "${GREEN}✅ 所有检查通过，允许提交${NC}"
exit 0

步骤3：测试钩子

git add src/App.js
git commit -m "test: 测试钩子"

2 commit-msg钩子：验证提交信息格式

#!/bin/bash
# .git/hooks/commit-msg
# 验证提交信息是否匹配规范：<type>(<scope>): <description>
# feat(user): 新增用户注册功能
COMMIT_MSG=$(cat $1)
if ! echo "$COMMIT_MSG" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf)\([a-z]+\): .+"; then
    echo -e "\033[31m❌ 提交信息格式错误！示例：feat(module): 添加新功能\033[0m"
    exit 1
fi
exit 0

3 使用husky统一管理钩子（推荐）

对于Node.js项目，可借助husky和lint-staged自动化管理钩子，避免手动复制文件到.git/hooks：

# 安装依赖
npm install husky lint-staged --save-dev
# 在package.json中配置
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": ["eslint --fix", "prettier --write"]
  }
}
# 激活husky
npx husky install

常见问题与最佳实践

常见问题

钩子没有生效：检查文件权限（必须可执行）和文件名是否正确（无后缀）
Windows平台兼容性：避免使用Linux特有的命令（如grep），可用findstr替代
性能问题：不要在钩子中运行耗时的测试或构建，考虑使用pre-push替代
绕过钩子：开发者可用git commit --no-verify跳过，建议通过服务端钩子补充验证

最佳实践

在团队文档中明确钩子的作用和安装方式
使用专用库（如husky、githooks）简化管理
将钩子脚本纳入版本控制（使用.githooks目录并通过git config core.hooksPath指定）
提供友好的错误提示,让开发者知道如何修复问题

问答环节：解决你的真实困惑

Q1：钩子脚本可以用Python写吗？ A：可以！只需在脚本头部指定解释器，例如#!/usr/bin/env python3，但要注意所有开发者机器上都需要安装Python及依赖库。

Q2：如何避免钩子拖慢提交速度？ A：将耗时操作（如完整测试套件）移到pre-push钩子，仅在推送时执行；本地pre-commit只运行快速检查（语法、格式、少量测试）。

Q3：多语言项目（Python+JS）如何处理？ A：在钩子中根据文件后缀区分处理，对.py文件运行flake8，对.js文件运行eslint，可参考以下伪代码：

PY_FILES=$(git diff --cached --name-only -- '*.py')
JS_FILES=$(git diff --cached --name-only -- '*.js')
[ -n "$PY_FILES" ] && flake8 $PY_FILES
[ -n "$JS_FILES" ] && eslint $JS_FILES

Q4：钩子脚本中的环境变量如何管理？ A：可以在脚本中加载.env文件，或使用export临时设置，建议保持钩子脚本自包含，避免依赖外部配置。

提交钩子脚本是保障代码质量、维护团队规范的强大工具，编写时需注意：