jenkins 中直接执行 composer config -g 基本无效，因 agent 环境临时且项目级 repositories 会完全屏蔽全局配置；必须每次构建前动态探测镜像可用性，并在项目根目录写入 composer config repo.packagist composer $mirror_url/，同时清理 vendor/ 和 composer.lock 以确保生效。
为什么直接写 composer config -g 在 Jenkins 里基本无效
因为 Jenkins agent（尤其是 Docker 或临时节点）每次构建都是干净环境，~/.composer/config.json 写进去就丢了；更关键的是，只要项目根目录的 composer.json 里有 repositories 字段，全局配置就会被完全忽略——连 fallback 都不触发，Composer 直接走你项目里写的源。
常见现象：Pipeline 里执行了 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，日志显示成功，但 composer install 依然卡在 Resolving dependencies 或持续连接 packagist.org。
- agent 容器没挂载
$HOME/.composer→ 配置不持久 -
composer.json含"repositories": []→ 全局镜像被静默屏蔽 - 命令漏掉
composertype 参数，或 URL 少末尾/→ 配置写入但无效
必须在 Pipeline 中动态探测并写入项目级镜像
核心逻辑不是“配一次”，而是“每次构建前检查镜像是否可用，再写进项目级配置”。所有操作都在项目根目录下进行，绕过全局配置失效问题。
先用 curl 探活：
sh 'curl -I -s -o /dev/null -w "%{http_code}" https://mirrors.aliyun.com/composer/packages.json'
若返回非 200，fallback 到 https://packagist.org，并确保 "packagist.org": true（不是 false）。
- 执行
composer config repo.packagist composer $MIRROR_URL/—— 注意不加-g，且 URL 必须带结尾/ - 删掉
vendor/和composer.lock，否则 Composer 会沿用旧 lock 文件里的 dist URL，导致校验失败 - 不要用
composer config --unset repositories，它会清空整个字段，私有源直接失效
保留私有源时怎么安全写入镜像
项目原本用了私有 Git 包（如 "my-vcs": {"type": "vcs", "url": "https://git.internal/pkg"}），直接运行 composer config repo.packagist 会全量替换 repositories 数组，导致私有包无法解析。
正确做法是手动编辑 composer.json，把镜像源作为 repositories 数组第一个元素，私有源跟在后面，并显式加 {"packagist.org": false} 作为独立对象：
[
{"type":"composer","url":"https://mirrors.aliyun.com/composer/"},
{"type":"vcs","url":"https://git.internal/pkg"},
{"packagist.org": false}
]
- 顺序不能错：镜像源必须在最前，否则 Composer 不会优先使用它
-
{"packagist.org": false}是独立对象，不能嵌套在镜像对象里 - 别手写 JSON —— 格式错一个逗号或引号，整个
repositories就失效
路径、权限、缓存三者不对齐，镜像再快也白搭
即使镜像配置全对，Jenkins 构建仍可能卡在 Resolving dependencies 或报 Allowed memory size exhausted——问题往往出在环境层面。
- 检查
~/.composer目录归属：确保 Jenkins 用户（如jenkins）可读写，常见坑是sudo -u jenkins composer config -g没用对用户 - 首次运行前建议清理：
rm -rf ~/.composer/cache，否则旧元数据还在用官方源 - 若用 Docker agent，镜像配置需写入容器内的
/var/jenkins_home/.composer/config.json，而非宿主机 - Composer 2.5+ 默认启用插件，某些镜像站不支持插件元数据接口，可加
--no-plugins规避，但注意这会禁用部分依赖解析能力
真正起效的那行指令就是 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，但前提是它跑在正确的用户、正确的路径、正确的上下文里——而 Jenkins 的 ephemeral agent 天然破坏这三点。所以别寄希望于“配一次”，得把探测、写入、清理、验证串成 Pipeline 的固定步骤。
