Composer国内常用镜像源汇总与切换方法

先说几个关键点：Composer 换源这事儿，很多人以为不过是复制粘贴一行命令，结果发现改了跟没改一样，包还是从国外源下。问题出在哪儿？不是命令写错了，而是 Composer 版本和配置键名不匹配，或者被更高优先级的设置悄悄覆盖了。

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

先看版本：Composer 1.x 用的是 repo.packagist，到了 2.2+ 就推荐改用 repositories.packagist.org。如果你还在用旧版命令，新版 Composer 会静默忽略——没有任何报错，但配置根本没写进去。

更隐蔽的坑在项目级配置。只要项目根目录的 composer.json 里有 repositories 字段（哪怕是个空数组，或者只写了 "packagist": false），全局配置就完全失效。这是 Composer 的优先级规则：项目级配置 > 全局配置。

Windows 用户要特别注意：用 Git Bash 时，COMPOSER_HOME 环境变量可能没生效，实际读的是 %APPDATA%\Composer\config.json，不是 ~/.composer/config.json。配置写到了错误的地方，自然不起作用。

最后，改完配置别忘执行 composer clear-cache。元数据还缓存在本地，请求照样发往旧地址，改了等于没改。

阿里云镜像源是目前最稳的选择

截至 2026 年 4 月，阿里云镜像是唯一持续全量同步、HTTPS 可靠、索引完整且仍在维护的国内源。腾讯云镜像偶有延迟，比如新发布的 lara vel/framework v11.0.0 可能晚几小时才上线；Lara vel China 镜像已在 2025 年底停止维护，访问直接返回 404；phpcomposer.com 也停更了，会触发 cURL error 60: SSL certificate problem。

配置时注意几个细节：

• 必须用 HTTPS 地址：https://mirrors.aliyun.com/composer/，末尾斜杠不能少。
• 别用 http:// 开头的旧地址——Composer 2.x 默认禁用非 HTTPS 源，会报 Invalid repository type, expected 'composer'。
• 阿里云不支持上传私有包，但如果你只是下载公共包，它就是目前最优解。

换源后怎么验证真生效了

别只看命令回显“成功”，得从三个地方交叉确认。

• 查配置：运行 composer config -g repo.packagist.url 或 composer config -g repositories.packagist.org，输出必须是镜像地址，不是空也不是 packagist.org。
• 看诊断：composer diagnose，找到 “Repo:” 那一行，域名必须匹配你设的镜像。
• 抓真实请求：composer show -p | head -3，第一行显示的源域名要是你刚配的；更彻底点，加 -vvv 跑一次 composer update，日志里 Downloading 的 URL 应含 mirrors.aliyun.com。

临时切换或项目级配置要注意什么

临时参数只影响当次命令，适合 CI 脚本或排查网络问题。但它只对 install 和 update 生效，require 后加 --repository-url 不起作用。

项目级配置要写进 composer.json 的 repositories 字段，格式必须是完整 JSON 数组。常见错误：漏掉外层方括号、URL 没加引号、误加 "packagist": false 导致基础包拉不到。如果项目已存在 repositories，别直接覆盖，要合并数组，否则会丢掉私有包源。

临时参数优先级最高，会覆盖全局和项目配置，但只影响当前命令，不会写入任何配置文件。

换源这事本身不难，真正容易卡住的是缓存没清、配置键名版本错、或者项目级 repositories 字段悄悄把全局配置顶掉了。验证时别只看命令输出，一定要看 composer diagnose 和真实请求日志。