gitlab runner中composer config -g不生效，根本原因是$home为空或指向临时路径导致全局配置无法持久化，且docker等executor每次启动均为干净容器；必须在before_script中显式设置composer_home指向缓存路径（如/cache/composer），并执行composer config --no-plugins --global repo.packagist composer https://mirrors.aliyun.com/composer/，同时确保url以/结尾、type参数不省略、缓存路径正确声明。

GitLab Runner 里 composer config -g 为什么总不生效？

根本不是镜像地址写错了，而是 Runner 启动时 $HOME 为空或指向临时路径，composer config -g 写入的配置文件（比如 /root/.composer/config.json）每次 job 结束就被丢弃。Docker executor 尤其明显——容器一销毁，全局配置就清零。

验证方法：在 before_script 里加一行 composer config -g repo.packagist，大概率输出空或报错 Key "repo.packagist" does not exist。

显式设置 COMPOSER_HOME 指向一个持久化路径（如 /cache/composer）

用 mkdir -p 确保目录存在，否则 config --global 会失败

必须加 --no-plugins 参数，避免某些插件（如 asset-plugin）在无交互环境下卡住

怎么让镜像配置在每个 job 都生效？

不能靠“一次配置、永久生效”，得在每个 job 的生命周期里重新初始化。关键是把配置动作和缓存路径绑定起来。

示例 before_script：

before_script:
  - export COMPOSER_HOME="/cache/composer"
  - mkdir -p "$COMPOSER_HOME"
  - composer config --no-plugins --global repo.packagist composer https://mirrors.aliyun.com/composer/

注意三点：

https://mirrors.aliyun.com/composer/ 末尾的 / 不能省，否则部分 Composer 版本拼接 URL 会出错

必须用 composer（不是 composer2 或 php composer.phar），否则 --global 可能写到不同位置

如果 Runner 使用的是 PHP 7.4 等旧镜像，先确认 composer --version 输出是 2.x；1.x 要用 packagist 键名，不是 repo.packagist

缓存 /cache/composer 但 vendor 不缓存，行不行？

可以，而且推荐。Composer 缓存的是下载的 ZIP 包和元数据（~/.composer/cache），不是 vendor/ 目录本身。只要 COMPOSER_HOME 被缓存，下次 job 就能复用已下载的包，跳过重复拉取。

One-click installation of GitHub projects

GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。

下载

cache: 配置要匹配 COMPOSER_HOME 路径：

cache:
  key: "$CI_JOB_NAME"
  paths:
    - /cache/composer

别写成 /cache/composer/vendor 或 vendor/ —— 前者不存在，后者没意义，还可能污染缓存。

如果用了 docker executor，确保基础镜像里 /cache 目录可写（有些精简镜像默认只读）

不要同时声明 /cache/composer 和 vendor/，后者是构建产物，应由 composer install 生成，不是缓存目标

为什么阿里云镜像比腾讯云更常被推荐？

不是速度绝对更快，而是同步稳定性更高。阿里云镜像对 Composer 2.x 元数据格式兼容性更好，尤其在 CI 场景下极少出现 Signature mismatch 或 packages.json not found 这类静默失败。

遇到问题时优先换源排查：

腾讯云：https://mirrors.cloud.tencent.com/composer/

清华：https://mirrors.tuna.tsinghua.edu.cn/composer/

华为：https://mirrors.huaweicloud.com/repository/composer/

换源后不用改配置命令，只替换 URL 字符串即可。但要注意所有镜像都要求 URL 以 / 结尾，且 type 固定为 composer。

最易被忽略的一点：如果项目 composer.json 里已有 "repositories" 字段，哪怕只写了私有源，也会完全屏蔽全局镜像配置——这时必须删掉或显式保留 {"packagist": true} 才能兜底。