如何通过Composer国内镜像加速下载，提升项目启动速度？

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

国内使用 `composer install` 卡在 `Downloading...`，不是网络差，而是本地没有镜像源——必须先配置镜像源，再运行命令，顺序错了就白费了。

怎么确认当前走的是哪个源

别猜，直接看日志。加 -vvv 参数执行任意命令，比如：

composer install -vvv

输出里会有一行类似：

Downloading https://packagist.org/packages.json

或

Downloading https://mirrors.aliyun.com/composer/packages.json

这才是真实请求地址。如果看到 packagist.org，说明镜像没生效；看到镜像域名（如 mirrors.aliyun.com），才算到位。

常见误判点：

• 只改了 composer.json 里的 repositories，但项目里已有同名 packagist 源，导致被覆盖
• 全局配置写错了字段名，比如用了 repos.packagist（旧版语法）但 Composer 是 2.x，应为 repo.packagist
• 执行命令的用户和配置用户不一致（比如用 sudo composer，但 config -g 是普通用户配的）

全局镜像配置该用哪条命令

Composer 2.0+ 推荐用：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

这条命令写入的是当前用户的全局配置文件（~/.config/composer/config.json），所有项目默认继承。

注意几个关键细节：

• 必须带 -g，否则是项目级配置，只影响当前目录
• repo.packagist 是固定键名，不是 repos.packagist 或 repository
• URL 后面不能多加斜杠，https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer// ❌
• 验证是否成功：运行 composer config -g repo.packagist，输出应为 URL 字符串或 JSON 对象，非空即对

如果提示 Could not open input file: composer，说明 composer 命令没进 PATH，查安装路径后补环境变量。

为什么换了镜像还是慢？三个高频原因

镜像配对了，但下载仍卡住，大概率是以下其一：

• 并行下载没开：Composer 2.x 默认是 5，并发太低。执行 composer config -g parallel-downloads 15 提升到 15（别超 20，防 DNS 超时）
• vendor 目录残留：删了 vendor 后直接 install，Composer 还要重解压、校验、生成 autoload —— 这些不走网但很耗 CPU。可加 --no-scripts --no-autoloader 快速装完，再补 composer dump-autoload
• 包绕过镜像：某些包在 composer.json 里硬编码了 GitHub URL（比如 "url": "https://github.com/xxx/yyy/archive/"），这种请求不受镜像控制，会撞上 GitHub 限速。报错含 GithubRateLimitException 或 403 就是它。解决方案是配 GitHub Token：composer config -g github-oauth.github.com your_token_here

项目级配置怎么避免覆盖私有源

很多项目依赖私有包，composer.json 里已有 repositories 字段。此时别手动编辑，用命令追加：

composer config repo.packagist composer https://mirrors.aliyun.com/composer/

这条命令会把 packagist 源作为独立项写入 repositories，不会清空原有配置。

如果已有多个源，注意顺序：Composer 按 repositories 数组顺序查找包，packagist 应放在最前面，否则私有包可能被错误匹配。

临时调试时慎用 --repository：它会完全替换整个 repositories 列表，私有源瞬间失效。真要临时换，先 composer show vendor/package -vvv 看当前源，再决定是否覆盖。

镜像同步有 5–30 分钟延迟，新发布的包可能还没到镜像站——这不是配置问题，是时间差。别急着切回官方源，等一会儿再试。