确认真正生效镜像源应运行composer config -g repo.packagist，输出须为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；若为空、null或为packagist.org，则配置未生效，常见因键名错写为repos.packagist、URL缺末尾斜杠或被项目级repositories字段覆盖；元数据缓存默认15分钟复用，需composer update --refresh（≥2.5）强制刷新。
Composer包更新频率低，不是镜像源同步慢，而是本地没拉到新数据——绝大多数情况是缓存复用、配置未生效或项目级覆盖导致的假性“延迟”。
怎么确认当前真正生效的镜像源
很多人改完配置就跑 composer update，结果还是卡在 Downloading，其实根本没走国内镜像。最可靠的方式是直接查配置输出：
- 运行
composer config -g repo.packagist，输出必须是类似{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}的完整 JSON；如果为空、null或https://packagist.org，说明全局配置没写成功 - 键名必须是
repo.packagist（单数），写成repos.packagist会静默失败，无任何提示 - 如果项目根目录有
composer.json且含repositories字段，它会完全屏蔽全局配置；此时要查composer config repo.packagist（不带-g） -
URL末尾的/不可省略，漏掉会导致部分Composer 2.2+版本回退到官方源，且无报错
为什么配置对了还是拉不到新版
镜像本身同步很快（阿里云/腾讯云通常 5–15 分钟），但 Composer 默认 15 分钟内复用本地 packages.json 元数据，哪怕镜像已更新也不会重拉。这不是网络问题，是缓存策略：
-
composer clear-cache只删 ZIP 和 provider 缓存，不影响元数据复用逻辑 -
Composer ≥ 2.5：用composer update --refresh，强制丢弃所有缓存的packages.json，重新下载索引 Composer ：手动删缓存里的 repo 子目录，例如 <code>rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer- 临时验证是否真走镜像：加
--no-cache -v，看终端输出的真实请求 URL 是否命中你配的镜像地址
项目级配置比全局更可控，但写法有坑
在 CI、宝塔或多用户环境下，composer config -g 很可能写到了错误用户的家目录下，实际运行时读不到。项目级配置可提交进 Git，行为一致，但必须注意写法：
- 进项目根目录，运行
composer config repo.packagist composer https://mirrors.aliyun.com/composer/（去掉-g），它会自动在composer.json顶层添加或合并"repositories"字段 - 如果已有
"repositories": {}（对象格式），命令能安全 merge；但若已是数组格式（如"repositories": []），命令会报错，需先手动改成对象再重试 - 别手写
"packagist.org": false这类字段——它会彻底禁用基础包索引，连laravel/framework都装不上 - 一旦项目级
repositories存在，全局配置即失效，哪怕只写了空对象也会覆盖
换源后首次 install 报 hash 不匹配？
这不是镜像问题，是旧缓存和新索引不一致导致的校验失败。删掉 vendor 和 composer.lock 后重来即可。但要注意：这不是常规操作，仅限首次切换镜像或长期未更新后遇到校验错误时才需要。
真正容易被忽略的是——镜像源解决不了依赖解析卡顿。如果 composer update 卡在 Resolving dependencies 而不是 Downloading，换源毫无帮助，得看 composer.json 的约束是否过宽、是否有循环依赖或版本冲突。
