在主流云服务器上配置Compoer镜像源的指南

Composer镜像配置不生效是因为漏掉三个硬性条件：键名必须为单数repo.packagist、type值必须显式写composer、URL须HTTPS且末尾带/，任一缺失即静默回退官方源；验证需输出完整JSON对象。

composer config -g repo.packagist 命令为什么总不生效

不是网络慢，是命令漏了三个硬性条件，Composer 2.x+ 静默 fallback 到 https://packagist.org，连报错都没有。

• repo.packagist 必须是单数、小写、无额外字符；写成 repos.packagist 或 packagist.org 都无效
• 中间的 composer 是必需的 type 值，不能省略，也不能当注释处理
• URL 必须是 HTTPS 协议，且末尾带 /，例如 https://mirrors.aliyun.com/composer/✅；少斜杠会拼出 /composerpackages.json 导致 404

验证是否真写进去了：运行 composer config -g repo.packagist。正确输出必须是完整 JSON 对象，形如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。返回空、null、Key not found，或只有一行 URL 字符串，说明没配成功。

项目级配置比全局更可靠

全局配置写在 ~/.composer/config.json，但在 CI（如 GitHub Actions）、宝塔（www 用户）、Docker 容器里，实际运行用户根本读不到你的配置。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

• 进项目根目录，执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加 -g）
• 该命令会自动识别 composer.json 中已有的 repositories 结构：如果是对象，就写入 "packagist" 键；如果是数组，就追加新项，不破坏私有源
• 改完立刻运行 composer update --lock，确保 composer.lock 记录的是镜像源地址，而非官方源
• 切勿手动写 "packagist.org": false —— 这会导致 php、ext-json 等基础约束校验失败

换源后仍卡在 “Loading composer repositories” 怎么办

这不是镜像没生效，而是 Composer 还在读旧缓存和旧 composer.lock。

• 先清缓存：composer clear-cache
• 删掉项目下的 vendor/ 和 composer.lock
• 再跑 composer install -vvv，观察日志里是否出现 mirrors.aliyun.com 或 mirrors.cloud.tencent.com
• 如果日志里还是 packagist.org，说明镜像根本没走通，回头检查上面两个副标题里的硬性条件

哪些镜像地址现在还能用（2026 年 8 月实测）

截至今天，只有这三个镜像全量同步、HTTPS 强制、延迟稳定（5 分钟内），其余旧地址基本不可靠：

• 阿里云：https://mirrors.aliyun.com/composer/（最稳，适合生产环境）
• 腾讯云：https://mirrors.cloud.tencent.com/composer/（Laravel 生态包缓存更及时）
• 华为云：https://mirrors.huaweicloud.com/composer/（文档明确支持，同步延迟低）

清华源带宽足但偶有同步延迟；已停更的 packagist.phpcomposer.com 自 2025 年底起大量返回 404，务必避开。