如何配置Composer使用国内镜像以提升下载速度？

本文共计836个文字，预计阅读时间需要4分钟。

若镜像未配，大概率是配置错误了，或是被更高优先级的设置覆盖了。Composer的源有明确优先级：

• composer config -g repo.packagist 输出为空、null 或报错 → 说明命令根本没写对，常见错误包括：repos.packagist（多一个 s）、漏掉 composer 类型值、URL 少末尾 /、用了 http 而非 https
• 项目根目录存在 composer.json 且含 "repositories" 字段 → 全局配置自动失效，哪怕只写了 "repositories": {} 也会屏蔽镜像
• CI/CD 或宝塔后台用 www 用户执行命令 → -g 写的是 root 的 ~/.composer/config.json，但实际运行用户读不到
• 执行 composer diagnose，看输出中 Repo packagist.org: 后面是不是你设的镜像地址；如果不是，就确认没接管

composer config repo.packagist 项目级配置怎么写才安全？

适合团队协作和 Git 管控，但必须注意写法，否则会破坏已有私有源或导致 composer validate 失败。

• 进项目根目录后，直接运行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉 -g）→ 它会自动在 composer.json 顶层添加或合并 "repositories" 字段，key 固定为 "packagist"
• 如果项目已有 "repositories": { ... }（对象格式），命令会 merge；但若已是数组格式（如 "repositories": []），命令会报错，需手动编辑成对象再重试
• 别手写 "packagist.org": false 这类字段——它会彻底禁用基础包索引，连 laravel/framework 都装不上
• 换源后首次 composer install 报 hash 不匹配？删掉 vendor 和 composer.lock 重来即可

临时切换镜像只影响当次命令，但要注意限制条件

适合排查问题、验证镜像可用性，或在 CI 脚本里隔离环境，但它不是万能开关。

• 用法：在 install 或 update 时加 --repository-url=https://mirrors.huaweicloud.com/repository/php/composer/，优先级最高，会覆盖全局和项目配置
• composer require 不支持 --repository-url，加了也无效；必须用 install 或 update
• composer create-project 不支持 -r 参数，得先配好全局或项目配置再跑
• 想确认是否真走镜像？加 -vvv 参数，观察日志里请求的 URL 是否含镜像域名，比如 mirrors.cloud.tencent.com

镜像只加速 ZIP 包和元数据的下载，不解决 Resolving dependencies 卡顿问题。如果你发现 composer update 卡在解析阶段，那和镜像无关，要检查 PHP 版本约束太宽、require-dev 包过多、或 Composer 版本太旧。另外，所有主流镜像（阿里云、腾讯云、华为云）现在都要求 URL 末尾带 /，少一个就会拼出错路径，直接 404。