必须先配置国内镜像源再执行composer install，顺序错误会导致卡在Downloading；确认是否生效需加-vvv参数查看日志中真实请求地址，若为packagist.org则镜像未生效，应使用composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/正确配置。
国内用 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 分钟延迟，新发布的包可能还没到镜像站——这不是配置问题，是时间差。别急着切回官方源，等一会儿再试。
