首选方案是执行composer config -g repo.packagist修改全局配置，而非直接编辑项目级composer.json，因其避免协作冲突与版本污染，且生效于所有项目；手动改composer.json仅适用于私有包临时指定源。
为什么改 composer.json 不是首选方案
直接在项目级 composer.json 里写镜像地址，看似简单，实则容易引发协作冲突和版本污染。多人共用一个项目时，有人提交了带国内镜像的 repositories 配置，其他人执行 composer install 就可能绕过官方源或缓存不一致——这不是配置问题，是依赖解析路径被硬编码了。
真正该改的是全局或用户级配置，而不是每个项目的 composer.json。除非你明确需要为某个私有包临时指定源，否则别碰它。
composer config -g repo.packagist 是最稳妥的全局设置方式
这条命令会修改 Composer 的全局配置文件（通常是 ~/.composer/config.json），影响所有项目，且不会侵入项目文件。国内主流镜像如阿里云、腾讯云、华为云都支持标准 Packagist 协议，只需替换 URL 即可。
- 设阿里云镜像：
composer config -g repo.packagist https://mirrors.aliyun.com/composer/ - 设腾讯云镜像：
composer config -g repo.packagist https://mirrors.cloud.tencent.com/composer/ - 恢复官方源：
composer config -g --unset repo.packagist
注意：如果之前手动在 composer.json 里加过 "repositories"，得先删掉，否则会优先走项目配置，全局设置被忽略。
遇到 Could not fetch 或 file could not be downloaded 怎么排查
这类错误往往不是镜像本身失效，而是 Composer 缓存或 SSL 验证出问题。常见诱因包括：
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
- 本地
composer.lock记录的是旧源地址，运行composer update --lock可刷新锁文件里的 URL - PHP 的 OpenSSL 扩展没启用，或 CA 证书路径不对，执行
php -r "print_r(openssl_get_cert_locations());"查看capath是否指向有效目录 - 公司网络拦截了 HTTPS 重定向，可临时试下 HTTP 镜像（不推荐长期用）：
composer config -g repo.packagist http://mirrors.aliyun.com/composer/
别急着换镜像站——先跑一遍 composer diag，它能暴露 DNS、TLS、cache 等真实瓶颈点。
CI/CD 环境下必须显式设置镜像
GitHub Actions、GitLab CI 这类环境默认没有全局配置，每次都是干净容器。不能指望 composer config -g 持久生效，得在 workflow 脚本里每轮都设一次：
composer config -g repo.packagist https://mirrors.aliyun.com/composer/ composer install --no-interaction --prefer-dist
顺带提醒：有些镜像站对未认证的 CI IP 限速，如果频繁失败，试试换华为云或中科院开源协会的镜像（https://mirrors.ustc.edu.cn/composer/），它们对自动化请求更宽松。
镜像不是万能加速器，关键在匹配你的网络出口和 Composer 版本。2.x 默认启用 HTTPS 和 strict SSL，1.x 则可能需要额外加 --disable-tls——这点很容易被忽略，尤其在老旧 Docker 镜像里。
