Git Hooks 功能与作用详解

[一、Git Hooks 概述](#一、Git Hooks 概述)
[二、Git Hooks 核心分类及对应功能](#二、Git Hooks 核心分类及对应功能)
- [2.1 客户端钩子（Client-side Hooks）](#2.1 客户端钩子（Client-side Hooks）)
- - [2.1.1 pre-commit 钩子](#2.1.1 pre-commit 钩子)
  - [2.1.2 prepare-commit-msg 钩子](#2.1.2 prepare-commit-msg 钩子)
  - [2.1.3 commit-msg 钩子](#2.1.3 commit-msg 钩子)
  - [2.1.4 post-commit 钩子](#2.1.4 post-commit 钩子)
  - [2.1.5 pre-push 钩子](#2.1.5 pre-push 钩子)
  - [2.1.6 其他客户端钩子](#2.1.6 其他客户端钩子)
[2.2 服务器端钩子（Server-side Hooks）](#2.2 服务器端钩子（Server-side Hooks）)
- - [2.2.1 pre-receive 钩子](#2.2.1 pre-receive 钩子)
  - [2.2.2 update 钩子](#2.2.2 update 钩子)
  - [2.2.3 post-receive 钩子](#2.2.3 post-receive 钩子)
[三、Git Hooks 的核心作用](#三、Git Hooks 的核心作用)
- [3.1 规范开发行为，降低沟通成本](#3.1 规范开发行为，降低沟通成本)
- [3.2 提前拦截错误，保障代码质量](#3.2 提前拦截错误，保障代码质量)
- [3.3 自动化流程，提升开发效率](#3.3 自动化流程，提升开发效率)
- [3.4 管控权限与安全，降低项目风险](#3.4 管控权限与安全，降低项目风险)
- [3.5 适配团队协作，支撑规模化开发](#3.5 适配团队协作，支撑规模化开发)
[四、Git Hooks 简单使用示例](#四、Git Hooks 简单使用示例)
- [4.1 pre-commit 钩子示例（校验 JavaScript 代码格式）](#4.1 pre-commit 钩子示例（校验 JavaScript 代码格式）)
- [4.2 commit-msg 钩子示例（规范提交信息格式）](#4.2 commit-msg 钩子示例（规范提交信息格式）)
[五、Git Hooks 使用注意事项](#五、Git Hooks 使用注意事项)
- [5.1 钩子文件的存放与共享](#5.1 钩子文件的存放与共享)
- [5.2 钩子脚本的权限问题](#5.2 钩子脚本的权限问题)
- [5.3 钩子的兼容性](#5.3 钩子的兼容性)
- [5.4 避免钩子脚本过于复杂](#5.4 避免钩子脚本过于复杂)
- [5.5 钩子的跳过机制](#5.5 钩子的跳过机制)
六、总结

注：本文全部由豆包AI生成~

一、Git Hooks 概述

Git Hooks（Git 钩子）是 Git 版本控制系统中自带的一种自动化触发机制，本质是一组可执行脚本，能够在 Git 执行特定命令（如提交、推送、合并等）的前后，自动触发执行。这些脚本可以由开发者自定义编写，支持多种编程语言（如 Shell、Python、Node.js 等），无需额外安装插件，是 Git 内置的核心扩展功能之一。

Git Hooks 的核心价值在于"自动化管控"与"流程标准化"，它可以嵌入到 Git 工作流的关键节点，实现代码校验、规范检查、自动化部署、通知提醒等功能，减少人工操作成本，规避开发风险，保障代码质量和团队协作效率。

Git Hooks 分为两类：客户端钩子（Client-side Hooks）和服务器端钩子（Server-side Hooks）。客户端钩子运行在开发者本地的 Git 仓库中，主要用于规范本地开发行为；服务器端钩子运行在 Git 远程仓库（如 GitLab、GitHub、Gitee 等）的服务器上，主要用于管控代码提交到远程仓库的行为，二者协同作用，构建完整的 Git 工作流管控体系。

二、Git Hooks 核心分类及对应功能

Git 默认为每个仓库提供了钩子模板，存放于仓库的 .git/hooks 目录下，模板文件以 .sample 为后缀（如 pre-commit.sample），开发者只需移除后缀并编写自定义逻辑，即可启用对应钩子。以下按"客户端钩子"和"服务器端钩子"分类，详细介绍各类钩子的触发时机、核心功能及应用场景。

2.1 客户端钩子（Client-side Hooks）

客户端钩子仅作用于本地仓库，由开发者本地 Git 命令触发，主要用于规范本地开发流程，提前发现问题并拦截错误操作，避免错误代码进入版本控制流程。常见客户端钩子如下：

2.1.1 pre-commit 钩子

触发时机：执行 git commit 命令后、提交信息录入前（即暂存区内容提交到本地仓库前）。

核心功能：校验暂存区的代码是否符合规范，若校验失败，直接终止提交操作，阻止错误代码提交。

典型应用场景：

• 代码格式校验：使用 ESLint、Prettier、Pylint 等工具，检查代码缩进、语法错误、代码风格是否符合团队规范；

• 代码质量检查：执行单元测试、静态代码分析（如 SonarLint），确保提交的代码无明显 Bug、无冗余代码；

• 文件类型限制：禁止提交临时文件（如 .log、.tmp）、编译产物（如 dist、build 目录）、敏感文件（如配置文件、密钥文件）；

• 代码注释检查：确保新增代码有足够的注释，避免无注释代码提交。

注意：pre-commit 钩子仅校验暂存区（git add 后的内容），未添加到暂存区的代码不会被校验。

2.1.2 prepare-commit-msg 钩子

触发时机：pre-commit 钩子执行成功后、提交信息编辑器打开前（若使用 git commit -m "xxx" 直接指定提交信息，则触发后直接使用指定信息）。

核心功能：自动生成或修改提交信息模板，规范提交信息格式，减少开发者手动编写提交信息的成本。

典型应用场景：

• 自动添加分支信息：根据当前分支名称（如 feature/xxx、bugfix/xxx），自动在提交信息开头添加分支标识，便于后续追溯；

• 生成标准化提交模板：固定提交信息格式（如"类型: 描述"，类型包括 feat、fix、docs、style 等），强制开发者按规范编写；

• 自动关联需求/BUG 编号：从分支名称中提取需求编号（如 feature/REQ-123），自动添加到提交信息中，关联项目管理工具（如 Jira）。

2.1.3 commit-msg 钩子

触发时机：提交信息编辑完成后、提交操作最终执行前（即提交信息已确定，准备写入本地仓库时）。

核心功能：校验提交信息的格式、长度、内容是否符合规范，若不符合，终止提交操作。

典型应用场景：

• 提交信息格式校验：强制要求提交信息符合 Conventional Commits 规范（如"feat: 新增用户登录功能""fix: 修复首页加载卡顿问题"），禁止无效提交信息（如"修改代码""bug 修复"）；

• 提交信息长度限制：限制提交信息标题长度（如不超过 50 字符），避免提交信息过于冗长或简略；

• 敏感词检查：禁止提交信息中包含敏感词汇（如"密钥""密码""测试"等），避免泄露关键信息。

区别：prepare-commit-msg 是"修改/生成"提交信息，commit-msg 是"校验"提交信息，二者协同确保提交信息规范。

2.1.4 post-commit 钩子

触发时机：提交操作成功完成后（即代码已提交到本地仓库）。

核心功能：提交后的后续操作，不影响提交结果（即使钩子执行失败，提交也已生效）。

典型应用场景：

• 提交成功通知：发送本地通知（如系统弹窗）或消息（如企业微信、钉钉消息），告知开发者提交成功；

• 自动更新本地文档：提交后自动生成或更新项目文档（如 API 文档、CHANGELOG.md）；

• 触发本地构建：提交后自动执行本地构建命令，检查代码是否可正常编译运行。

2.1.5 pre-push 钩子

触发时机：执行 git push 命令后、本地代码推送到远程仓库前。

核心功能：校验即将推送的代码（本地分支与远程分支的差异），若校验失败，终止推送操作，避免错误代码推送到远程。

典型应用场景：

• 远程分支冲突检查：检查本地分支与远程目标分支是否存在冲突，若有冲突，提示开发者先拉取远程代码合并；

• 代码质量二次校验：再次执行单元测试、静态代码分析，确保推送的代码无质量问题（避免开发者跳过 pre-commit 钩子提交错误代码）；

• 分支权限控制：禁止向保护分支（如 master、main、develop）推送代码，或仅允许特定开发者推送。

2.1.6 其他客户端钩子

• pre-applypatch：触发时机为执行 git apply（应用补丁）前，用于校验补丁文件的合法性；

• post-applypatch：触发时机为 git apply 执行成功后，用于补丁应用后的后续操作（如通知、日志记录）；

• pre-rebase：触发时机为执行 git rebase（变基）前，用于校验变基操作的合法性，避免破坏分支结构；

• post-rewrite：触发时机为执行 git rebase、git commit --amend（修改最近一次提交）等改写提交历史的操作后，用于更新相关记录。

2.2 服务器端钩子（Server-side Hooks）

服务器端钩子运行在远程 Git 仓库的服务器上，由客户端的 git push 命令触发，主要用于管控远程仓库的提交行为，确保推送到远程的代码符合团队规范、无安全风险，同时实现自动化部署、权限控制等功能。常见服务器端钩子如下：

2.2.1 pre-receive 钩子

触发时机：客户端执行 git push 后、远程仓库接收代码前（即远程仓库尚未更新，仍处于待接收状态）。

核心功能：校验推送的代码、分支、开发者权限等，若校验失败，直接拒绝接收推送，阻止错误代码进入远程仓库。

典型应用场景：

• 开发者权限控制：校验推送者是否有对应分支的推送权限（如普通开发者禁止向 master 分支推送）；

• 分支规范校验：禁止推送不符合命名规范的分支（如禁止推送无意义分支名、临时分支）；

• 代码质量终极校验：执行服务器端的静态代码分析、单元测试，确保推送的代码符合项目最高质量标准；

• 提交历史校验：禁止强制推送（git push --force），避免覆盖远程仓库的提交历史，防止代码丢失。

注意：pre-receive 钩子是远程仓库的"第一道防线"，能够直接拦截所有不符合规范的推送，是服务器端最核心的钩子。

2.2.2 update 钩子

触发时机：与 pre-receive 钩子类似，在客户端推送代码、远程仓库接收前触发，但二者的触发逻辑不同：pre-receive 钩子针对整个推送操作（一次推送可能包含多个分支），而 update 钩子针对每个推送的分支，即一次推送多个分支时，update 钩子会为每个分支单独触发一次。

核心功能：对每个推送的分支进行单独校验，粒度比 pre-receive 更细。

典型应用场景：

• 分支差异化校验：对不同分支设置不同的校验规则（如 master 分支严格校验，develop 分支宽松校验）；

• 分支保护：针对保护分支，单独校验推送者权限、代码质量，确保保护分支的稳定性；

• 分支更新控制：禁止向已冻结的分支（如发布分支）推送代码，避免影响发布进度。

2.2.3 post-receive 钩子

触发时机：远程仓库成功接收客户端推送的代码后（即代码已写入远程仓库，推送操作完成）。

核心功能：推送后的自动化操作，不影响推送结果，是实现"推送即部署""推送即通知"的核心钩子。

典型应用场景：

• 自动化部署：推送到指定分支（如 master 分支）后，自动执行部署脚本，将代码部署到生产环境、测试环境（如执行 Docker 构建、Nginx 重启）；

• 推送通知：向团队成员发送推送通知（如企业微信、钉钉、邮件），告知谁推送了代码、推送的分支、提交信息等；

• 代码备份：推送完成后，自动备份远程仓库的代码，防止代码丢失；

• 触发 CI/CD 流水线：调用 CI/CD 工具（如 Jenkins、GitLab CI），启动自动化测试、构建、部署流程。

三、Git Hooks 的核心作用

Git Hooks 作为 Git 工作流的"自动化插件"，其作用贯穿整个开发、提交、推送、部署流程，核心价值体现在以下 5 个方面，能够显著提升开发效率、代码质量和团队协作规范性。

3.1 规范开发行为，降低沟通成本

通过 pre-commit、commit-msg 等钩子，强制开发者遵循团队的代码规范、提交规范，避免因代码风格不一致、提交信息不清晰导致的沟通成本。例如：

• 代码格式校验钩子，确保所有开发者提交的代码缩进、命名、语法一致，无需人工 review 时反复提醒修改；

• 提交信息规范钩子，确保提交信息清晰可追溯，后续排查问题、查看迭代记录时，能够快速定位提交目的。

这种"自动化规范"比人工约定更高效、更严格，能够减少团队内部的无效沟通，让开发者专注于代码开发本身。

3.2 提前拦截错误，保障代码质量

Git Hooks 能够在代码提交、推送的早期阶段，自动检查并拦截错误代码，避免错误进入后续流程（如远程仓库、生产环境），降低问题排查和修复成本。例如：

• pre-commit 钩子拦截语法错误、未通过单元测试的代码，避免错误提交到本地仓库；

• pre-push、pre-receive 钩子拦截存在冲突、质量不达标代码，避免错误推送到远程仓库；

• 服务器端钩子执行终极校验，确保推送到远程的代码无安全漏洞、无性能问题。

这种"提前拦截"的机制，能够将代码质量问题解决在萌芽阶段，减少线上 Bug 的产生，提升项目稳定性。

3.3 自动化流程，提升开发效率

Git Hooks 能够替代大量人工操作，实现开发、提交、推送、部署全流程的自动化，节省开发者时间和精力。例如：

• 自动生成提交信息模板、关联需求编号，减少开发者手动编写提交信息的时间；

• 提交后自动生成文档、执行本地构建，无需开发者手动触发；

• 推送后自动部署、触发 CI/CD 流水线，实现"推送即部署"，缩短迭代周期。

自动化流程不仅提升了开发效率，还减少了人工操作带来的失误（如忘记部署、忘记备份）。

3.4 管控权限与安全，降低项目风险

通过服务器端钩子，能够实现对远程仓库的权限管控和安全防护，避免因误操作、恶意操作导致的项目风险。例如：

• 权限控制：禁止普通开发者向保护分支推送代码，防止误操作覆盖核心代码；

• 安全校验：拦截包含敏感信息（密钥、密码）的代码提交，避免信息泄露；

• 提交历史保护：禁止强制推送，防止提交历史被覆盖，确保代码可追溯、可回滚。

这些管控措施，能够保障项目的安全性和稳定性，尤其适合多人协作的大型项目。

3.5 适配团队协作，支撑规模化开发

在多人协作、多分支开发的场景中，Git Hooks 能够统一团队的工作流程，确保所有开发者遵循相同的规范，支撑项目规模化开发。例如：

• 通过分支校验钩子，规范分支命名和使用（如 feature 分支用于开发新功能、bugfix 分支用于修复 Bug）；

• 通过推送通知钩子，让团队成员实时了解代码推送情况，便于协作开发、代码 review；

• 通过自动化部署钩子，确保所有环境（测试、预生产、生产）的代码一致，避免环境差异导致的问题。

对于大型团队、复杂项目，Git Hooks 是实现流程标准化、协作高效化的关键工具。

四、Git Hooks 简单使用示例

以下以最常用的 pre-commit 钩子（校验代码格式）和 commit-msg 钩子（规范提交信息）为例，演示 Git Hooks 的基本配置和使用方法，使用 Shell 脚本编写（适用于 Linux/macOS 系统，Windows 系统可使用 PowerShell 脚本）。

4.1 pre-commit 钩子示例（校验 JavaScript 代码格式）

进入本地 Git 仓库的 .git/hooks 目录：
cd /path/to/your/git/repo/.git/hooks
复制 pre-commit.sample 模板，并重命名为 pre-commit（移除 .sample 后缀）：
cp pre-commit.sample pre-commit
编辑 pre-commit 文件，编写校验逻辑（使用 ESLint 校验 JavaScript 代码）：

javascript 复制代码

#!/bin/sh
# 检查是否安装 ESLint
if ! command -v eslint >/dev/null 2>&1; then
  echo "Error: ESLint 未安装，请先执行 npm install -g eslint"
  exit 1
fi

# 校验暂存区的 JavaScript 文件
ESLINT_ERRORS=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.js$' | xargs eslint 2>&1)

if [ -n "$ESLINT_ERRORS" ]; then
  echo "ESLint 校验失败："
  echo "$ESLINT_ERRORS"
  exit 1
fi

echo "ESLint 校验通过，允许提交"
exit 0

赋予 pre-commit 文件可执行权限：
chmod +x pre-commit
测试：提交一个包含语法错误的 JavaScript 文件，Git 会自动触发 pre-commit 钩子，校验失败并终止提交，提示错误信息。

4.2 commit-msg 钩子示例（规范提交信息格式）

进入 .git/hooks 目录，复制 commit-msg.sample 模板，并重命名为 commit-msg：cp commit-msg.sample commit-msg
编辑 commit-msg 文件，编写校验逻辑（强制符合 Conventional Commits 规范）：

javascript 复制代码

     #!/bin/sh
# 读取提交信息
COMMIT_MSG=$(cat "$1")

# 定义提交信息规范：开头为类型（feat/fix/docs/style/refactor/test/chore），后跟冒号和空格，再跟描述
REGEX="^(feat|fix|docs|style|refactor|test|chore): .{1,50}$"

if ! echo "$COMMIT_MSG" | grep -E "$REGEX" >/dev/null; then
  echo "提交信息格式错误！请遵循 Conventional Commits 规范："
  echo "示例：feat: 新增用户登录功能"
  echo "示例：fix: 修复首页加载卡顿问题"
  echo "类型说明：feat（新功能）、fix（Bug修复）、docs（文档修改）、style（代码风格）、refactor（重构）、test（测试）、chore（构建/依赖）"
  exit 1
fi

echo "提交信息格式正确"
exit 0

赋予 commit-msg 文件可执行权限：
chmod +x commit-msg
测试：执行 git commit -m "修改代码"，Git 会触发 commit-msg 钩子，提示格式错误；执行 git commit -m "feat: 新增用户登录功能"，校验通过，允许提交。

五、Git Hooks 使用注意事项

5.1 钩子文件的存放与共享

默认情况下，Git Hooks 存放于仓库的 .git/hooks 目录下，而 .git 目录不会被 Git 跟踪（即不会提交到远程仓库），导致团队其他成员无法共享钩子脚本。解决方法：

• 在仓库根目录创建 .githooks 目录，将钩子脚本放入该目录；

• 执行命令 git config core.hooksPath .githooks，将 Git Hooks 的默认目录改为 .githooks；

• 将 .githooks 目录提交到远程仓库，实现团队共享。

5.2 钩子脚本的权限问题

Git Hooks 脚本必须具备可执行权限（如 Linux/macOS 下的 chmod +x 权限），否则 Git 不会触发钩子执行。若钩子未触发，首先检查脚本权限是否正确。

5.3 钩子的兼容性

不同操作系统（Linux、macOS、Windows）的脚本语法存在差异（如 Shell 脚本不支持 Windows 系统），若团队成员使用不同操作系统，建议编写跨平台的钩子脚本（如使用 Python、Node.js 编写），或为不同操作系统编写对应的脚本。

5.4 避免钩子脚本过于复杂

钩子脚本的核心作用是"轻量校验、自动化触发"，若脚本过于复杂（如执行大量耗时操作），会导致 Git 命令执行缓慢，影响开发效率。建议将复杂操作（如大型测试、构建）交给 CI/CD 工具，钩子仅负责简单的校验和触发。

5.5 钩子的跳过机制

Git 提供了跳过钩子的命令（如 git commit --no-verify 跳过 pre-commit 和 commit-msg 钩子，git push --no-verify 跳过 pre-push 钩子），但需谨慎使用，仅在紧急修复、特殊场景下使用，避免滥用导致规范失效。

六、总结

Git Hooks 是 Git 内置的强大自动化工具，通过在 Git 工作流的关键节点触发自定义脚本，实现了代码规范校验、自动化操作、权限管控等核心功能。其客户端钩子专注于规范本地开发行为，服务器端钩子专注于管控远程仓库提交，二者协同作用，能够显著提升代码质量、开发效率和团队协作规范性。

对于开发者而言，Git Hooks 能够减少人工操作、提前拦截错误，让开发更高效、更规范；对于团队而言，Git Hooks 能够统一工作流程、降低协作成本，支撑项目规模化开发。掌握 Git Hooks 的使用，是提升 Git 应用能力、优化开发流程的重要手段。