镜像配置必须写在项目composer.json中，因为只有项目级repositories声明能被git跟踪并确保团队统一生效；全局配置易被忽略或冲突，且composer按“项目>全局>默认”优先级取首个镜像，无法合并，故必须统一写入composer.json首位并显式禁用packagist.org。
为什么镜像配置必须写在项目 composer.json 里
镜像源（比如 https://mirrors.aliyun.com/composer/）只负责下载加速，不参与版本决策。但团队多人协作时，如果有人用全局配置、有人没配、有人配错 URL，composer install 就可能拉到不同版本的包——不是因为镜像“改了版本”，而是因为部分人没走同一份 composer.lock 解析路径（比如 PHP platform 不一致 + 镜像混用导致 fallback 到 packagist.org）。真正起作用的是项目级声明。
-
repositories必须显式写进项目根目录的composer.json，且只保留一个packagist.org替代源 - 所有人执行
composer config --global --unset repos.packagist清掉全局镜像；CI 脚本开头也加这一句防污染 - 检查残留：运行
composer config --global repo.packagist，输出应为空或https://packagist.org
如何避免镜像配置被本地环境绕过
常见错误是开发者在 ~/.composer/config.json 里设了镜像，又在项目里配了另一个，结果部分包走全局、部分走项目，composer show --locked 看不出问题，但 composer install 在 CI 失败。根本原因是 Composer 会按「项目 > 全局 > 默认」优先级合并配置，而镜像 URL 不支持 merge，只取第一个生效。
- 项目
composer.json中repositories必须是完整对象，不能只写 URL；推荐格式："repositories": { "packagist.org": { "type": "composer", "url": "https://mirrors.aliyun.com/composer/" } } - 禁用
packagist.org默认源：加"packagist.org": false到repositories顶层，防止 fallback - CI 中跑
composer install前，用composer config --list | grep repos确认实际生效的源
镜像统一 ≠ 版本统一：真正决定版本的是什么
换镜像不会让 guzzlehttp/guzzle 从 2.9.1 变成 3.0.0。版本由三样东西共同锁定：composer.json 的约束、composer.lock 的快照、config.platform 的声明。镜像只是下载通道。
-
composer.lock必须提交到 Git，且所有机器严格使用它——这是版本一致的底线 -
config.platform要写死小版本，比如"php": "8.1.10"，而不是"^8.1"，否则不同 patch 版本可能触发不同依赖解析 - 扩展声明也要精确：
"ext-zip": "8.1.10"，别写true，否则会掩盖真实缺失
多微服务场景下镜像配置要不要共享
每个微服务都是独立部署单元，它们的 composer.json 和 composer.lock 必须各自维护。但镜像配置可以（也应该）统一——前提是每份 composer.json 都包含一模一样的 repositories 和 config.platform 块。
- 不要靠脚本批量注入镜像配置；用模板工具（如
composer-merge-plugin或自定义 Makefile）同步基础字段 - 禁止在某个服务里写
"url": "https://xxx.com/private-mirror"，除非整个团队都接入该私有源并验证过可用性 - 若某服务需临时调试，用
composer install --repository-url=...覆盖，但切勿提交到主分支
platform 或 lock 产生隐性冲突。最常被忽略的点是：以为配了镜像就万事大吉，结果发现 CI 报错 Your lock file does not contain a compatible set of packages，其实根源是某台机器的 PHP 小版本和 config.platform 对不上，镜像只是把这个问题更快地暴露了出来。
