项目级repositories字段会完全屏蔽全局镜像配置，即使执行了composer config -g repo.packagist，只要composer.json中存在repositories字段（含空数组），composer就忽略全局设置并可能回退到packagist.org。

镜像源配置覆盖了全局设置，导致实际走的不是你配的镜像

项目 composer.json 里写了 "repositories" 字段，会直接屏蔽 composer config -g repo.packagist 的全局镜像配置。哪怕你在终端执行过 composer config -g repos.packagist.url https://mirrors.aliyun.com/composer/，进项目一跑 composer require，日志里照样出现 Downloading https://packagist.org/...。

验证方法：

• 运行 composer config --list | grep repos.packagist.url，确认输出是你期望的镜像地址
• 检查项目根目录下 composer.json 是否含 "repositories" 字段；若有，确认其 url 值是有效的镜像地址（如 https://mirrors.aliyun.com/composer/），而非已停更的旧地址（如 https://packagist.phpcomposer.com）
• 若需保留私有源又不想覆盖全局镜像，别用 -g 全局写入整个 repositories 数组，改用 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g）追加

packages.json 缓存没刷新，Composer 以为没新版本

composer update 显示 Nothing to install or update，但你知道某个包明明发布了新版——这不是镜像同步慢，而是 Composer 默认复用本地 ~/.composer/cache/repo/https---mirrors-aliyun-com-composer/packages.json，只要它 15 分钟内未过期，就跳过远程校验。

解决方法取决于 Composer 版本：

• ≥ 2.5：直接运行 composer update --refresh，它只丢弃 packages.json 和 provider-*.json，不删 ZIP 包，也不重建 composer.lock
• ≤ 2.4：必须手动清理缓存子目录：rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer
• composer clear-cache 无效——它不清 packages.json，只清 dist 包和部分 provider 缓存

验证镜像是否真同步：用 curl -I https://mirrors.aliyun.com/composer/packages.json 看 Last-Modified 时间，比对是否符合你预期的更新节奏。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

镜像 URL 写错或协议不匹配，触发回退到 packagist.org

常见低级但致命的错误包括：

• URL 少了末尾斜杠：https://mirrors.aliyun.com/composer → 应为 https://mirrors.aliyun.com/composer/
• 用了 HTTP 而非 HTTPS（多数镜像已强制 HTTPS，HTTP 会 301 重定向失败）
• 镜像域名拼错，比如 mirros.aliyun.com 或 mirrors.alinux.com
• 配置时用了单数 repo（composer config -g repo.packagist.url），而 Composer 2.2+ 已要求复数 repos，否则静默忽略

运行 composer config -g repos.packagist.url 查当前生效值；若为空或报错，说明配置未落地。别信 composer diag ——它默认只测 packagist.org，完全不检查你配的镜像。

依赖冲突其实是缓存错位 + 版本约束太宽，不是镜像问题

镜像本身不产生版本不一致，但它会放大本地缓存与远程元数据的错位。真正引发后续冲突的，往往是：你用 ^8.0 这类宽泛约束锁定了一个旧 packages.json，等缓存过期后镜像同步了新包，Composer 却仍按旧索引算依赖树，结果发现“找不到满足 ^8.0 的可用版本”。

这时别急着换镜像或删 vendor，先做两件事：

• 用 composer why-not vendor/package:version 定位阻塞链，看是哪个依赖在卡住版本升级
• 确认 PHP 版本、扩展是否匹配目标包的要求（例如 guzzlehttp/guzzle:^7.5 要求 PHP ≥ 8.0，而你本地是 7.4）
• 如果只是想验证可行性，加 --dry-run： composer require vendor/package:version --dry-run

最常被忽略的一点：镜像配置只是加速访问，真正的版本解析逻辑完全由 Composer 本地完成。缓存、约束写法、PHP 环境这三者没对齐，再快的镜像也救不了依赖冲突。