不能只用 composer config -g,因为它仅写入当前用户家目录的 ~/.composer/config.json,而 php 进程(如 www-data、ci runner)以不同用户运行,无法读取 root 或其他用户的配置;唯一跨用户可靠方案是 composer 2.2+ 支持的系统级配置 /etc/composer/config.json,需确保路径存在、权限正确、结构合规且 url 末尾带斜杠。

为什么不能只用 composer config -g
因为 composer config -g 总是写进当前用户的 ~/.composer/config.json,而 PHP 进程(比如 www-data、nginx 或 CI runner)运行时根本不会读 root 的配置。你用 sudo composer config -g 配的是 /root/.composer/config.json,但 www-data 的 $HOME 是 /var/www,它默认连这个目录都没有,更别说读配置了。
常见失败现象:
– sudo -u www-data composer config -g repo.packagist ... 直接报错 “Could not write to /var/www/.composer/config.json”
– 手动创建 /var/www/.composer 后仍失败,因 www-data 的 shell 是 /sbin/nologin,sudo -i -u www-data 会立即退出
– 即使硬塞进去了,CI 流水线用 gitlab-runner 用户构建,又得重配一遍
/etc/composer/config.json 是唯一真正跨用户的方案
Composer 2.2+ 支持系统级配置,路径固定为 /etc/composer/config.json,优先级高于所有用户级配置,且不依赖任何用户 $HOME。它对批量部署(Ansible)、Docker 容器或低权限 Web 用户特别关键。
必须确保:
– /etc/composer/ 目录存在,权限为 755,属主 root:root
– 配置文件内容结构正确:"repositories" 必须是对象(不是数组),键名严格为 "packagist.org"
– URL 必须以 / 结尾,且为 HTTPS,例如:"url": "https://mirrors.aliyun.com/composer/"
– 文件权限设为 644,否则 Composer 会静默忽略
示例内容:
{
"repositories": {
"packagist.org": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
}
}
验证是否真被目标用户加载
别只看 root 用户的输出,验证必须用实际运行 PHP 的用户执行,否则毫无意义。
比如 Nginx + PHP-FPM 场景下,应使用 www-data:
-
sudo -u www-data composer config repo.packagist—— 输出应为镜像 URL 对象 -
sudo -u www-data composer diagnose—— 确认不报Could not fetch packages.json -
sudo -u www-data composer show monolog/monolog | head -3—— 观察是否秒出结果,而非卡在Loading composer repositories
如果 composer config --list --global 显示 repo.packagist 为空,但 /etc/composer/config.json 存在且格式正确,大概率是 Composer 版本低于 2.2,需先升级。
项目级配置会完全覆盖全局设置
只要项目根目录下的 composer.json 包含 "repositories" 字段(哪怕只写了 {} 或 {"packagist.org": false}),/etc/composer/config.json 就彻底失效。
快速检查方式:
– grep -A5 '"repositories"' composer.json
– 若存在,临时禁用: composer config --unset repositories(仅当前项目生效)
注意:composer clear-cache 必须在切换源后执行,否则旧缓存可能仍触发原始域名请求;parallel-downloads=10 这类性能参数也建议统一写进 /etc/composer/config.json,避免每个用户单独配。











