GitLab CI中composer config -g常失效，因配置写入root用户目录而job以gitlab-runner用户运行，需在CI脚本中由当前用户执行、键名repo.packagist（单数）、type值必填composer、URL末尾带/且为HTTPS，并验证输出完整JSON。
GitLab CI里composer config -g命令为什么总不生效
因为配置被写进了root用户的~/.composer/config.json，而CI job实际以gitlab-runner用户运行，读的是/home/gitlab-runner/.composer/config.json。你本地或用sudo执行的命令，对CI容器完全无效。
验证方式很简单：
- 在.gitlab-ci.yml的script里加一行：whoami && echo $HOME && ls -la $HOME/.composer/config.json
- 如果ls报No such file，说明配置根本没写对位置
-
composer config -g必须在CI容器内、由job当前用户（通常是gitlab-runner）执行，不能靠人工预置 - 命令必须带
-g，否则只改当前目录下的composer.json，不影响后续install -
repo.packagist键名必须拼写准确——是repo（单数），不是repos，否则静默失败 - 中间的
composer类型值不能省：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - URL末尾必须带
/，否则请求变成https://mirrors.aliyun.com/composer/packages.json→ 404 → fallback到官方源
正确配置镜像的CI脚本写法
把镜像设置直接写进.gitlab-ci.yml，放在before_script或具体job的script开头。别依赖外部配置，也别用curl手动下载packages.json——Composer自己会处理。
推荐写法（阿里云镜像）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ composer config -g --unset github-protocols
--unset github-protocols很重要：CI环境通常没SSH密钥，保留默认["https", "ssh"]会导致git clone卡住或报错。
- 执行完立刻验证：
composer config -g repo.packagist应输出完整JSON，不是null或空行 - 如果输出
Could not find package或日志仍出现Downloading https://repo.packagist.org/packages.json，说明配置未生效 - 务必配合缓存：
cache:下加入key: $CI_COMMIT_REF_SLUG并缓存~/.composer/cache和vendor/，否则每次都是冷启动
项目级镜像配置与CI的冲突点
如果项目composer.json里已定义"repositories"为数组（比如含私有GitLab源），composer config -g不会覆盖它，但composer install会优先使用项目级配置——此时全局镜像形同虚设。
要让CI真正走镜像，得确保项目级配置本身也指向镜像源，且格式合规（Composer 2.2+要求）：
"repositories": [
{"packagist.org": false},
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
]-
{"packagist.org": false}必须是独立对象，不能合并进下一项 - 私有VCS源（如
gitlab.example.com/pkg.git）必须插在这两项之后，不能删掉第一项 - 如果项目原来用的是
"repositories": {}（空对象），可以用composer config repo.packagist composer ...安全合并 - 改完必须删掉
vendor/和composer.lock再install，否则lock文件里还存着官方源的dist URL
私有GitLab包和中文镜像能一起用吗
不能混用。中文镜像（如阿里云https://mirrors.aliyun.com/composer/）只缓存packagist.org上的公开包，对gitlab.example.com/internal/auth-sdk这类私有包完全无感知。
一旦把私有源错误配成"type": "composer"并指向镜像地址，Composer就会尝试从镜像拉取不存在的packages.json，结果必然是404或Could not find package。
- 私有GitLab仓库的
repositories条目，type必须是vcs，url必须是可git clone的地址（带.git后缀） - 认证靠
auth.json，路径必须是~/.composer/auth.json（Linux/macOS），字段名必须是http-basic，域名key必须和url的host严丝合缝（端口、子路径都不能差） - CI中建议用
CI_JOB_TOKEN或预设变量注入Token，避免硬编码；同时禁用github-protocols防止SSH干扰
最易被忽略的一点：镜像配置和私有源配置是两套独立机制，它们共存的前提是互不干扰——即私有源不用镜像URL，镜像也不试图代理私有请求。强行统一，只会让composer install在“找不到包”和“404”之间反复横跳。
