Git钩子自动部署配置指南 Linux服务器实战教程

直接说结论：使用 post-receive 钩子配合 GIT_WORK_TREE 环境变量，是实现 Git 自动部署最稳定可靠的方案。至于 post-update 钩子或在裸仓库中直接执行 checkout 的方法，强烈建议避免使用——它们不仅容易失败，而且错误信息往往不明确，排查过程极其耗时。

为什么必须选择 post-receive 而非 post-update

根本原因在于裸仓库（bare repository）的特性：它不包含工作目录。当你使用 post-update 钩子时，Git 命令的默认执行环境仍在 .git 目录内部，此时若执行 git checkout，会立即触发经典错误：fatal: this operation must be run in a work tree。

而 post-receive 钩子则不同，它是唯一一个在服务器完整接收推送数据后、能够安全地通过 --work-tree 和 --git-dir 参数指定路径的钩子，这为后续的代码检出操作扫清了障碍。

• 信息获取方式：post-receive 通过读取标准输入（stdin）来获取引用（ref）的更新信息（例如 refs/heads/main），这种方式非常适合进行分支判断，从而实现按分支部署。
• 执行时机：post-update 虽然也能接收参数，但此时 Git 的内部对象写入已完成，一些关键的环境变量可能并不可靠。
• 一个常见的误区：网络上许多相互转载的教程仍在推荐 post-update，但实际上，尤其是在 Git 2.30 及之后的版本中，这套方案极有可能静默失败，导致问题难以追踪。

如何编写正确无误的 post-receive 钩子脚本

编写钩子脚本的关键，不在于“能否运行”，而在于“权限是否正确、路径是否存在、分支是否识别”。以下是一个经过验证的最小可用模板，你可以基于此进行修改：

#!/bin/sh
# 必须取消设置 GIT_DIR，否则后续 git 命令会误以为仍在裸仓库目录下
unset GIT_DIR

# 指定部署目录（必须提前创建，且所有者应为运行 git 的用户，例如 git:git）
DEPLOY_PATH="/var/www/myapp"
BRANCH="main"

# 检查部署目录是否存在，避免静默失败
if [ ! -d "$DEPLOY_PATH" ]; then
    echo "ERROR: $DEPLOY_PATH does not exist"
    exit 1
fi

# 切换到部署目录并强制检出指定分支
cd "$DEPLOY_PATH" || exit 1
git --git-dir="/repo/myapp.git" --work-tree="$DEPLOY_PATH" checkout -f "$BRANCH" 2>&1

# 修复权限（尤其当 Web 服务用户不是 git 时）
chown -R www-data:www-data "$DEPLOY_PATH"

使用此模板时，有几个关键细节必须注意：

• --git-dir 参数必须指向裸仓库的绝对路径（例如 /repo/myapp.git），使用相对路径极大概率会出错。
• checkout -f 是强制检出，它会丢弃部署目录中所有未提交的更改，包括用户上传的文件。如果生产环境存在此类文件，务必在部署前将其迁移。
• 如果使用 Nginx 或 Apache 作为 Web 服务器，最后的 chown 步骤不可省略，否则很可能导致 502 或 403 错误。

常见错误及其解决方案

post-receive 钩子默认不输出日志，错误信息容易被“吞没”。在脚本中添加简单的日志输出，能帮助你快速定位问题。以下是一些典型的错误场景及处理方法：

• 推送失败，提示 remote: fatal: not a git repository：首先检查 --git-dir 的路径拼写是否正确，然后确认该路径下是否存在 objects/ 等 Git 仓库目录。
• 推送成功，但网站页面未更新：可登录服务器，执行 ls -l /var/www/myapp 查看文件时间戳是否变化。更直接的方法是，在服务器上手动运行一遍钩子脚本中的 git checkout 命令，观察是否有报错。
• 本地推送失败，提示 Permission denied (publickey)：这不是钩子脚本的问题，而是 SSH 密钥配置有误。检查服务器上 ~git/.ssh/authorized_keys 文件是否包含了你的公钥。
• 部署后网站 CSS/JS 文件返回 404：这通常意味着前端构建产物（如 dist 目录）未提交到 Git 仓库，或者钩子脚本中缺少触发构建的命令（例如 npm install && npm run build），需要根据项目情况自行添加。

归根结底，配置 Git 自动部署真正的难点，从来不是编写那几行脚本。而是每次部署前，你都需要在心里反复确认三件事：裸仓库的权限是否正确、部署目录的权限是否正确、Web 服务用户能否读取那些文件。这三者遗漏任何一项，都足以让你耗费大量时间进行排查。