GitLab CI中真正起作用的是--repository-url命令行参数，而非挂载或全局配置；因CI容器环境干净、用户权限隔离且Composer 2.9+忽略非当前用户家目录配置，只有--repository-url能100%确保走镜像源。
GitLab CI 里挂载 Composer 镜像配置基本无效，真正起作用的是命令行显式指定 --repository-url。 全局配置、~/.composer/config.json 挂载、甚至项目级 composer.json 的 repositories 字段，在 CI 干净容器中都容易被绕过或覆盖。镜像没生效的典型表现是 composer install 卡在 Resolving dependencies 或反复重试 GET https://packagist.org/packages.json。
为什么 docker run -v ~/.composer:/root/.composer 在 CI 中不工作
GitLab CI job 默认运行在全新容器中，UID 通常不是 root（比如 gitlab-runner 用户），且宿主机的 ~/.composer 根本不可达；即使你用 sudo -u gitlab-runner 手动挂载，也面临权限错位、路径不存在、并发 job 写冲突等问题。更关键的是：Composer 2.9+ 会忽略非当前用户家目录下的全局配置，除非显式设置 COMPOSER_HOME —— 但这个变量本身又得在每个 job 中单独 export，极易遗漏。
常见错误现象：
- 日志显示
Loading config file /root/.composer/config.json，但实际仍走packagist.org - 挂载后
composer config -g repo.packagist能查到地址，install却不生效 - 多个并行 job 同时写入同一挂载点，导致配置损坏或 403 错误
composer install 必须带 --repository-url 参数
这是唯一在 CI 中 100% 可控、无需依赖环境状态的方式。--repository-url 优先级高于所有配置层级（全局、项目、平台），且不会修改 composer.json 或 composer.lock，完全符合 CI 的不可变原则。
实操建议：
- 始终使用国内稳定镜像地址，如：
https://mirrors.tuna.tsinghua.edu.cn/composer/或https://mirrors.aliyun.com/composer/ - 务必搭配
--no-interaction和--no-dev（若测试工具不在运行时依赖中） - 避免使用已废弃的
--repository（少-url），Composer 2.9.6+ 会直接报错Unknown option --repository - 示例命令：
composer install --no-dev --optimize-autoloader --classmap-authoritative --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/ --no-interaction
Docker 构建阶段如何安全注入镜像源
如果你在 Dockerfile 中执行 composer install（例如多阶段构建），不能依赖构建机的全局配置，也不能挂载宿主机路径——Docker 构建上下文与 runner 宿主机完全隔离。
正确做法是把镜像源作为构建参数传入：
- 在
Dockerfile中声明：ARG COMPOSER_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/composer/ - 安装时使用：
RUN composer install --no-dev --repository-url=${COMPOSER_MIRROR} --no-interaction - CI 中调用：
docker build --build-arg COMPOSER_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/composer/ -t myapp . - 注意：不要在
RUN中用composer config -g，它会写入临时层但不生效，还可能污染缓存
最易被忽略的一点：CI 环境中 composer.lock 里的 packages.json URL 是由 lock 文件生成时的源决定的，不是运行时配置。如果 lock 文件是在本地未配镜像时生成的，即使 CI 用了 --repository-url，部分元数据请求仍可能回源——所以团队必须统一镜像源生成 lock 文件，或定期用镜像源重生成 lock。
