必须用多镜像+显式故障转移+并发压制三者协同，否则单镜像在ci/cd中必触发429；关键要设"canonical": false、正确配置repositories数组、调高http-max-concurrent-downloads并清缓存。
单镜像源在 CI/CD 或本地多项目并行 install 场景下必然触发 429 Too Many Requests，必须用多镜像 + 显式故障转移 + 并发压制三者协同，否则只是换了个更慢的单点。
为什么 composer install -vvv 看到镜像域名却还是卡住
日志里出现 mirrors.aliyun.com 只说明元数据（packages.json）走了镜像，但 ZIP 包下载仍可能 fallback 到 packagist.org 或 GitHub——常见原因有：
- 项目
composer.json中存在"repositories"字段，它会完全屏蔽全局repo.packagist配置 - 某个依赖包的
dist.url是硬编码的 GitHub raw URL 或私有地址，Composer 不代理这类链接 - 镜像同步延迟：新发布的包可能已上
packagist.org，但国内镜像尚未同步，Composer 会静默重试失败路径直至超时 - URL 末尾缺
/，比如https://mirrors.tuna.tsinghua.edu.cn/composer→ 拼出/p2//vendor/package.json导致 404，触发无效重试
如何配置真正生效的多镜像 fallback
关键不是“加多个源”，而是让 Composer 主动轮询、自动降级。必须满足三个条件：
-
"canonical": false必须出现在每个国内镜像条目中，否则 Composer 当作主源，不启用 fallback 逻辑 -
"repositories"必须是数组结构（不是对象），且每个元素是{"packagist": {...}}形式 - 原始
packagist.org必须保留，并设为"canonical": true，作为最终兜底
正确写法（直接写入项目 composer.json 的 repositories 字段）：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"repositories": [
{
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/",
"canonical": false
}
},
{
"packagist": {
"type": "composer",
"url": "https://mirrors.tuna.tsinghua.edu.cn/composer/",
"canonical": false
}
},
{
"packagist": {
"type": "composer",
"url": "https://packagist.org",
"canonical": true
}
}
]
}
并发参数该设 http-max-concurrent-downloads 还是 parallel-downloads
parallel-downloads 已在 Composer 2.2+ 中被正式弃用，设了也不生效；唯一有效的参数是 http-max-concurrent-downloads：
- 默认值通常为
3或6，对高并发场景严重不足 - 推荐设为
8～10：再高容易触发临时文件竞争（file_put_contents(/tmp/): failed to open stream）或镜像限流返回416 - 执行命令：
composer config -g http-max-concurrent-downloads 8 - 验证是否生效：
composer config -g http-max-concurrent-downloads输出应为数字，不是null
CI/CD 流水线里最容易忽略的权限与缓存错位
GitHub Actions runner、Jenkins agent、宝塔 PHP 管理器默认以非 root 用户（如 runner、www）运行，但 composer config -g 写的是当前登录用户的配置路径（如 /root/.composer/config.json）：
- 结果就是：本地测试 OK，流水线里仍走官方源
- 解决方法：在流水线脚本开头显式配置项目级镜像，例如：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/ --no-dev --prefer-dist - 同时必须加
composer clear-cache，否则旧缓存仍指向失效源或境外地址 - 若用了私有 Packagist（如 Satis），还需确认其 Nginx 的
limit_req设置是否匹配该并发值，否则服务端先扛不住
真正卡点不在“选哪个镜像”，而在于多镜像结构是否被识别、并发是否被压制、以及配置是否落到实际运行用户上下文里——这三个条件漏掉任何一个，所有调优都归零。
