gitlab runner中composer镜像不生效的典型表现是ci日志反复出现downloading https://packagist.org/packages.json、卡在resolving dependencies或报connection refused，根本原因是runner以独立用户运行，本地全局配置无效，必须在before_script中显式执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（url末尾带/），并确保项目composer.json未定义repositories字段覆盖全局配置，同时缓存key需绑定镜像来源避免污染。
GitLab Runner 构建时 Composer 镜像不生效的典型表现
CI 流水线跑 composer install 仍卡在 Resolving dependencies、日志里反复出现 Downloading https://packagist.org/packages.json、甚至直接报 Connection refused 或 curl error 28 —— 这不是网络抖动，而是镜像根本没被用上。
必须在 job 中显式执行 config -g，不能依赖本地用户配置
GitLab Runner 默认以 gitlab-runner 用户（或容器内非 root 用户）运行 job，HOME 环境变量指向的是 Runner 自身的家目录（如 /home/gitlab-runner），而非你本地开发机的 ~/.composer/config.json。所以你在自己机器上跑过的 composer config -g 对 CI 完全无效。
- 必须在
.gitlab-ci.yml的每个需要 Composer 的 job 里，先执行：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 推荐放在
before_script中，避免每个命令前重复写 - 如果 Runner 是 Docker executor，且复用宿主机的
~/.composer目录，需确认挂载路径和权限一致，否则仍会写到容器内空白目录 - 不要用
COMPOSER_REPO_PACKAGIST环境变量替代——Composer 2.2+ 才支持，旧版 CI 镜像可能不兼容
项目级配置 + 全局配置混用时的优先级陷阱
当 composer.json 里已有 "repositories" 字段，哪怕只写了 "packagist.org": false，也会直接屏蔽全局镜像设置。这不是 bug，是 Composer 的设计逻辑：项目级配置优先级高于全局。
- 检查项目
composer.json是否存在"repositories"块；若有，确认其中是否包含"packagist"子项，且type为composer、url指向国内镜像 - 若项目需保持干净（如开源库），建议删掉整个
"repositories"字段，靠全局配置驱动 - 若必须保留私有源，应显式写出
"packagist"条目，例如："packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，不能只写"packagist.org": false - 验证方式：在 job 中加一行
composer config repo.packagist，输出应为镜像 URL；若提示Key "repo.packagist" does not exist，说明项目级没覆盖，此时才轮到全局生效
缓存 key 必须带镜像标识，否则缓存污染会导致安装失败
GitLab CI 默认缓存 ~/.composer/cache，但阿里云镜像和腾讯云镜像生成的缓存内容不互通。混用会导致 corrupted cache file 或 file could not be downloaded 错误，且难以定位。
- 缓存 key 必须显式绑定镜像来源，例如：
composer-${CI_COMMIT_REF_SLUG}-${CI_JOB_NAME}-aliyun - 避免只用
composer-${CI_COMMIT_SHA}这类通用 key，它无法区分镜像切换场景 - 如果团队同时用多个镜像（如测试用腾讯云、生产用阿里云），不同 job 的缓存 key 绝对不可复用
- 首次切换镜像后，务必手动清除旧缓存（GitLab UI → Settings → CI/CD → Clear runner caches），否则旧缓存会持续干扰新配置
