Webhooks 触发的是服务器行为，非 Composer 自身功能；Gitee Webhook 需配置签名验证（X-Gitee-Token + Secret）、勾选“代码推送”，由服务端脚本校验后执行 composer install/update。
Webhooks 触发的是服务器行为，不是 Composer 自身功能
Composer 本身不监听或响应 Webhooks；所谓“Webhooks 触发 composer 更新”，本质是 Gitee 的 Webhook 推送事件到你自己的服务器，由你写的接收端（比如一个 PHP 脚本或轻量 HTTP 服务）执行 composer install 或 composer update。关键不在 Composer 配置，而在服务端如何安全、可靠地响应推送。
Gitee Webhook 配置要点（含签名验证）
Gitee 发送的 POST 请求带 X-Gitee-Token 请求头和 JSON body，必须校验签名才能避免被伪造请求触发部署。不能直接裸奔执行 composer install。
- 在 Gitee 仓库 → 管理 → Webhooks 中添加 URL，如
https://yourdomain.com/webhook.php - 设置 Secret（自定义字符串），Gitee 会用它对 payload 做 HMAC-SHA256 签名
- 务必勾选「推送事件」中的「代码推送」（Push Hook）
- URL 必须能被公网访问（或内网穿透调试时用 ngrok）
PHP 接收脚本示例（含签名验证 + composer 执行）
以下脚本放在 Web 可访问路径下（如 Nginx 的 /var/www/html/webhook.php），需确保运行用户（如 www-data）有项目目录写权限和 composer 命令可用。
#!/usr/bin/env php
<?php
$secret = 'your_webhook_secret_here'; // 和 Gitee 后台填的一致
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEE_TOKEN'] ?? '';
if (empty($signature) || hash_hmac('sha256', $payload, $secret) !== $signature) {
http_response_code(401);
exit("Unauthorized\n");
}
// 解析事件类型和分支
$data = json_decode($payload, true);
if (!$data || !isset($data['ref']) || $data['ref'] !== 'refs/heads/main') {
exit("Skipped: not main branch\n");
}
$project_path = '/var/www/my-project';
chdir($project_path);
// 拉取最新代码（假设已配置好 SSH key 或 token）
exec('git pull origin main 2>&1', $output, $return_code);
if ($return_code !== 0) {
error_log("Git pull failed: " . implode("\n", $output));
exit("Git pull failed\n");
}
// 执行 composer 安装（--no-dev 可选，按需加）
exec('COMPOSER_HOME=/root/.composer /usr/local/bin/composer install --no-interaction --no-dev 2>&1', $output, $return_code);
if ($return_code !== 0) {
error_log("Composer install failed: " . implode("\n", $output));
exit("Composer install failed\n");
}
echo "Done.\n";
常见失败点和绕过陷阱
这个流程看着简单，但 80% 的问题出在环境权限和上下文不一致上：
-
exec()在 PHP-FPM 下默认禁用，需检查disable_functions是否包含exec、shell_exec等 - Web 进程用户（如
www-data）通常没权限执行git pull（SSH key 权限、known_hosts 问题）——建议改用 HTTPS + Personal Access Token -
composer命令路径可能不是/usr/local/bin/composer，用which composer确认；且需保证该用户能访问COMPOSER_HOME - Gitee Webhook 默认超时 10 秒，如果
composer install耗时长（尤其首次），会中断并标记为失败 —— 改用异步队列或后台 nohup 是更稳做法 - 别把
composer.json放在 Web 根目录下可公开访问路径，否则泄露依赖结构
真正要跑通，重点不是写几行 PHP，而是让 git、composer、权限、网络这四者在同一个用户上下文里安静协作。其他都是锦上添花。
