必须用 shell 脚本主动探测，先清缓存，再依次 curl -I 检查阿里云、腾讯云、华为云镜像的 /packages.json 是否返回 200，首个成功者即通过 composer config -g repositories.packagist.org 写入完整 JSON 配置，并适配 Windows 路径。
CI 中自动探测并切换 Composer 镜像源的脚本怎么写
不能靠 Composer 自己 fallback，必须用 shell 脚本主动探测。核心逻辑是：对多个国内源（如阿里云、腾讯云、华为云）依次 curl -I 请求 /packages.json，检查 HTTP 状态码是否为 200，第一个成功者即设为当前源。
实操建议用以下结构封装成预处理步骤：
- 先
composer clear-cache清掉旧元数据，避免缓存干扰探测结果 - 按优先级顺序探测：
https://mirrors.aliyun.com/composer/packages.json→https://mirrors.cloud.tencent.com/composer/packages.json→https://repo.huaweicloud.com/repository/php/packages.json - 探测成功后，用
composer config -g repositories.packagist.org写入完整 JSON（注意不是repo.packagist，CI 环境多为 Composer 2.2+，repositories.packagist.org兼容性更稳） - Windows CI（如 GitLab Runner on Windows）需额外判断配置路径：若
%APPDATA%\Composer\config.json存在，优先写入它，而非~/.composer/config.json
为什么 composer config -g repo.packagist 在 CI 里大概率失效
CI 环境中常见静默失败，根本原因不是网络，而是键名和格式不匹配 Composer 版本。Composer 2.2+ 已逐步弃用 repo.packagist，改用 repositories.packagist.org；且该字段必须是完整 JSON 对象，不能只传 URL 字符串。
错误示例：composer config -g repo.packagist https://mirrors.aliyun.com/composer/ —— 缺少 type: "composer"，末尾没斜杠，键名过时，三项全错。
正确写法（CI 安全）：composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}'。注意单引号包裹整个 JSON，双引号保留在内部，否则 shell 解析会崩。
CI 流水线里如何避免镜像切换引发 composer.lock hash 不一致
镜像源只影响下载速度，不影响包内容本身，但若不同节点用了不同镜像（比如 A 节点用阿里云，B 节点用腾讯云），而两个镜像同步延迟不一致，就可能拉到不同时间点的 packages.json 快照，导致依赖解析结果微差，最终 composer.lock 的 hash 变动。
规避方法只有两个：
- 所有 CI 节点统一用同一镜像（推荐腾讯云，它对未命中包会自动 fallback 到 packagist.org，行为最接近官方源）
- 强制锁死解析结果：在
composer install前加--no-plugins --no-scripts，并在 CI 配置中固定COMPOSER_CACHE_DIR路径，防止缓存污染
项目级配置在 CI 中反而更麻烦
很多人想把镜像写进 composer.json 的 repositories 字段来“一劳永逸”，但在 CI 场景下这反而增加风险：
- 如果项目已存在
"packagist.org": false，那无论你配什么镜像，都直接被屏蔽——CI 不报错，但composer install会卡在 Resolving dependencies -
repositories是数组时，composer config repo.packagist命令会直接失败，CI 流程中断 - 团队成员本地开发若也用了全局镜像，而项目又硬编码了另一个源，两者叠加可能触发
Package not found，排查时得比对两层配置
真正省心的做法，是在 CI 脚本开头统一执行一次探测 + 全局写入，不碰项目文件，也不依赖开发者手动维护。
