团队协作必须用项目级配置，因全局配置composer config -g仅写入用户私有文件、不被Git跟踪、CI/CD容器无法读取，且会被项目repositories字段完全忽略；切换镜像前必须删除vendor/和composer.lock并执行composer install --no-cache，否则dist.url仍指向旧源导致未走镜像。
团队协作必须用项目级配置，且只认这四个镜像源：阿里云、清华、腾讯云、安畅（php.cnpkg.org）。其他镜像要么已停服，要么在 Composer 2.2+ 中被默认拒绝（HTTP 地址）、或同步滞后导致 composer install 报 Could not find package。
为什么全局配置 composer config -g 在团队里根本不可靠
它只写进当前用户的 ~/.composer/config.json，而 Git 不跟踪这个文件，CI/CD 流水线（如 GitHub Actions、GitLab Runner）启动的是干净容器，压根读不到；Docker 或宝塔环境里 PHP 常以 www-data 或 www 用户运行，你配的是 $USER，等于没配。
更关键的是：只要项目 composer.json 里有 repositories 字段，全局配置就完全被忽略——不是“优先级低”，是彻底不加载。
常见失败现象：
-
composer config -g repo.packagist返回空或Key "repo.packagist" does not exist，说明根本没写进去 - 原因通常是键名写成
repos.packagist（多一个 s）、漏掉中间的composertype 值、URL 少了末尾/
项目级配置的正确写法和硬约束
进项目根目录（含 composer.json），运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
注意：不加 -g。这条命令会自动向 composer.json 的 repositories 字段追加条目，不覆盖已有私有源。
但必须满足两个前提：
- 如果
"repositories": {}是空对象，没问题；但如果它是空数组"repositories": []，命令会直接报错，需先手动改成{} - URL 必须以
/结尾：https://mirrors.aliyun.com/composer/✅，少斜杠会拼成/composerpackages.json导致 404 - type 值必须是
"composer"，写成"mirror"或"packagist"无效
换镜像后仍卡在 Downloading？不是网络问题，是 composer.lock 没重建
镜像只缓存元数据（packages.json），不托管实际包文件。如果 composer.lock 里 dist.url 还是 https://api.github.com/，Composer 就绕过镜像直连 GitHub——你看到的“卡住”其实是根本没走镜像。
切换前必须做两件事：
- 删掉
vendor/和composer.lock - 再执行
composer install --no-cache，强制重新拉取元数据并生成带镜像域名的dist.url
老项目若保留旧 composer.lock，它记录的是旧源的哈希值，和镜像返回的元数据不匹配，必报错。
四个可用镜像源的实测差异和选型建议
截至 2026 年 8 月，只有以下四个源真实可用且稳定：
-
https://mirrors.aliyun.com/composer/：同步最快（约 15 分钟），南方/北方延迟均低于 60ms，Laravel/Symfony 等主流包入库及时 -
https://mirrors.tuna.tsinghua.edu.cn/composer/：教育网和北方用户首选，学术网络质量极佳，但部分私有包索引略滞后 -
https://mirrors.cloud.tencent.com/composer/：华南地区下载峰值达 9.2MB/s，HTTPS 证书链已修复 -
https://php.cnpkg.org：Laravel 11 和 PHP 8.5 兼容包入库最快，适合新项目快速启动，但文档弱，出问题依赖社区反馈
所有 HTTP 地址（无 https://）在 Composer 2.2+ 中默认被拒绝；https://packagist.phpcomposer.com、https://packagist.laravel-china.org 已停服或返回 404/502。
最后强调一点：哪怕你确认 URL 正确、composer config repo.packagist 输出也对，只要没删 composer.lock 和 vendor/，镜像就形同虚设——这是最常被跳过的步骤，也是最顽固的问题根源。
