需在git服务器配置post-receive钩子：进入仓库hooks目录，新建可执行脚本，按顺序执行git checkout、composer install、迁移状态校验后migrate、清缓存，并确保www-data权限与错误捕获。
在Git服务器上配置post-receive钩子实现Laravel自动部署
当代码推送到远程Git仓库时，自动拉取最新代码、执行迁移并刷新缓存，避免每次上线都手动SSH登录执行命令——这需要在Git服务器端直接运行部署逻辑，而不是依赖Webhook或CI/CD平台中转。
第一步：登录Git服务器，进入目标仓库的.git目录，确认存在hooks子目录：cd /var/opt/gitlab/git-data/repositories/@hashed/xx/yy/zz.git && ls hooks/。若无post-receive文件，需新建；若有但不可执行，先运行chmod +x hooks/post-receive。
第二步：编辑hooks/post-receive，写入以下核心逻辑（注意替换实际路径）：
#!/usr/bin/env bash
while read oldrev newrev refname; do
if [[ $refname == "refs/heads/main" ]]; then
echo "Deploying Laravel to production..."
cd /var/www/myapp || exit 1
git --git-dir=/var/opt/gitlab/git-data/repositories/@hashed/xx/yy/zz.git --work-tree=/var/www/myapp checkout -f main
composer install --no-dev --optimize-autoloader --quiet
php artisan migrate --force --quiet 2>/dev/null || true
php artisan config:clear && php artisan cache:clear && php artisan view:clear
chown -R www-data:www-data /var/www/myapp/storage /var/www/myapp/bootstrap/cache
fi
done
第三步：确保该脚本对Git进程可执行，且/var/www/myapp目录归属为www-data用户（或Nginx/PHP-FPM实际运行用户），否则chown会失败导致后续artisan命令报错。
第四步：测试推送——本地执行git push origin main，观察终端是否输出“Deploying Laravel to production...”。若无输出或报错，检查Git服务器日志：sudo gitlab-ctl tail gitlab-shell，常见错误是git --work-tree路径不存在或权限不足。
极狐GitLab中用gitaly命令设置自定义服务器钩子
极狐GitLab 15.6+不再支持传统hooks目录直写，必须通过gitaly hooks set命令注入，否则钩子不会被Gitaly服务加载。
方法一：打包钩子脚本为tarball
在服务器上新建custom_hooks/post-receive文件，内容同上节逻辑；确保第一行是#!/usr/bin/env bash；运行chmod +x custom_hooks/post-receive；再执行tar -cf custom_hooks.tar custom_hooks生成归档。
方法二：调用gitaly命令注入
使用约定式提交信息暂存、提交和推送git更改。当用户想要提交和推送更改、提到推送到远程、或要求保存并推送工作时触发。也适用于用户说“推送更改”、“提交并推送”、“推送这个”、“推送到github”或类似git工作流程请求时。
执行以下命令（注意替换真实值）：cat custom_hooks.tar | sudo -u git -- /opt/gitlab/embedded/bin/gitaly hooks set --storage default --repository group/project.git --config /var/opt/gitlab/gitaly/config.toml。【storage名称必须与gitaly配置中[storages]下定义的名称完全一致，否则命令静默失败】
方法三：验证钩子是否生效
推送一次空提交：git commit --allow-empty -m "test hook" && git push origin main；然后立即查看Gitaly日志：sudo gitlab-ctl tail gitaly；若看到post-receive hook executed类日志，说明已挂载成功。
规避post-receive钩子的三个致命陷阱
陷阱一：钩子内执行php artisan migrate却未判断迁移状态
直接写php artisan migrate --force会导致重复执行已存在的迁移，破坏数据库一致性。必须前置检查：if [[ $(php artisan migrate:status --json | jq -r 'map(select(.status == "not run")) | length') -gt 0 ]]; then php artisan migrate --force; fi，依赖jq命令解析JSON结果。
陷阱二：忽略PHP-FPM用户与Git用户权限隔离
Git进程以git用户运行，但artisan命令需www-data权限写storage日志和cache文件。钩子中不能只靠chown，而应在php.ini里设syslog.ident = laravel-deploy，让所有PHP日志统一由syslog接管，绕过文件权限争抢。
陷阱三：钩子脚本未捕获stderr导致错误静默
所有关键命令末尾加|| echo "ERROR: $(basename $0) line $LINENO"，例如composer install ... || echo "ERROR: composer failed at line 12"。否则某一步失败后脚本继续执行，你会看到“部署完成”假象，实际view:cache根本没刷成功。
