全局镜像配置不生效是因为Composer仓库优先级规则严格：项目级repositories字段会完全覆盖全局配置，且空数组也会导致全局镜像失效；正确配置需键名repo.packagist、类型声明composer、URL以https://开头并以/结尾；项目级必须首项{"packagist.org": false}，再加镜像源；换源后需清缓存、删vendor和composer.lock、重装依赖；可用--repository-url临时验证。
全局镜像配置不生效？项目级镜像仍连 packagist.org？不是你配错了，是 Composer 的仓库加载规则太硬、太静默——它不会报错，只会默默 fallback 到官方源。
composer config -g repo.packagist 为什么总没反应
这条命令看似简单，实则三处极易出错：键名必须是 repo.packagist（不是 repos.packagist，多一个 s 就彻底忽略）；第二个参数必须显式写 composer（这是仓库类型声明，漏掉就走默认源）；URL 必须以 https:// 开头且末尾带 /（https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌）。
验证是否真正写入：运行 composer config -g repo.packagist，输出应为 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 或至少是完整 URL 字符串。如果为空、null、或仍是 https://packagist.org，说明完全没写进去。
常见错误现象：
- 命令执行后无报错，但
composer update日志里仍出现packagist.org - 全局配置被项目
composer.json中的repositories字段完全覆盖（优先级更高）
项目级 repositories 数组结构必须严格按顺序写
项目级镜像不是改个 URL 就完事。Composer 2.2+ 要求 repositories 必须是数组，且第一项必须是 {"packagist.org": false} —— 这是硬性规则，缺一不可。否则即使你写了阿里云地址，它仍会 fallback 到官方源请求元数据，卡在 Loading composer repositories。
正确结构示例：
"repositories": [
{"packagist.org": false},
{"packagist": {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}}
]
不能合并成一个对象，不能把 "packagist.org": false 放第二位，也不能写成 true 或 null。只有 false 才代表禁用。
使用场景：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 团队协作项目，需确保所有人用同一镜像源
- CI/CD 流水线中避免因环境差异导致依赖解析失败
- 已有私有 GitLab 包时，把私有源追加在镜像配置之后
换源后依然卡住或报 file could not be downloaded
镜像只加速元数据（packages.json）拉取，不影响 composer.lock 中记录的原始 dist URL。也就是说：你刚配好镜像，但 lock 文件里还存着 https://api.github.com/ 或 https://packagist.org/，Composer 仍会去连这些地址。
必须执行以下三步清理动作：
- 运行
composer clear-cache - 删除项目下的
vendor/和composer.lock - 再执行
composer install -vvv（不是update），观察日志是否出现mirrors.aliyun.com/composer/packages.json
若日志里仍有 packagist.org，说明某处配置仍被覆盖，回到上一步检查 composer.json 里的 repositories 是否含硬编码源或空数组（"repositories": [] 会让全局镜像直接失效且不报错）。
临时绕过项目配置验证镜像是否真生效
当怀疑项目配置干扰了全局设置，或想快速验证镜像地址是否可用，可跳过所有本地配置，强制指定仓库：
运行 composer update --repository-url=https://mirrors.aliyun.com/composer/。这个参数会临时覆盖所有 repositories 配置，只从该地址拉取元数据。
适用场景：
- 排查 CI 环境中为何镜像不生效
- 调试某个项目是否意外继承了错误的源
- 紧急恢复构建，不修改任何配置文件
注意：该方式仅对当前命令有效，不影响 composer.json 或全局配置。
最复杂也最容易被忽略的一点：Composer 的仓库优先级是硬编码的——项目 composer.json 中的 repositories > 全局 ~/.composer/config.json > 默认源。哪怕只写了 "repositories": []，也会让全局镜像彻底失效，且全程静默。
