Composer 配镜像必须严格遵循规范：全局配置需用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/（三要素缺一不可），项目级配置须在 composer.json 的 repositories 数组首位添加 "type": "composer" 仓库并显式禁用官方源 {"packagist.org": false}，且修改后须删除 vendor 和 composer.lock 再执行 composer install。
配镜像不是改个 URL 就完事，不按规范写，Composer 会直接忽略配置、继续连 packagist.org，甚至静默失败。
composer config -g repo.packagist 命令必须带全三要素
这条命令是全局换源最快的方式，但漏掉任意一个关键点，配置就白写了，且不报错：
-
repo.packagist是唯一有效的键名——写成repos.packagist（多一个 s）或mirror都无效 - 必须显式指定
composer作为 type 值，不能省略；省略后 Composer 2.x+ 会 fallback 到默认源 - 镜像 URL 必须以
/结尾，例如https://mirrors.aliyun.com/composer/✅，少斜杠会导致请求路径拼错，返回 404
正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。验证是否生效：运行 composer config -g repo.packagist，输出应为完整 JSON 对象，不是空或 null。
项目级配置必须写进 composer.json 的 repositories 数组首位
项目级镜像只对当前项目起作用，但生效条件非常严格：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 必须写在项目根目录的
composer.json里，写进composer.lock或全局config.json完全不生效 - 必须作为
"type": "composer"的仓库对象，放入repositories数组的**第一个位置** - 必须显式禁用官方源：
{"packagist.org": false}是独立对象，不是字段值，也不能合并到前一个对象里
错误示例（会被忽略）："repositories": {"packagist": {"type": "composer", "url": "..."}} —— 这是对象写法，不是数组，且没禁用 packagist.org。正确结构见知识库中清华镜像那段 JSON。
改完配置后必须删 vendor 和 composer.lock 再 install
Composer 不会“重新解析”已存在的 composer.lock —— 它照着 lock 文件里的 dist URL 直接下载，根本不管 repositories 配了啥：
- 只跑
composer update没用，它可能沿用旧 lock 里的官方 URL，镜像形同虚设 - 必须先手动删掉
vendor/和composer.lock，再执行composer install - CI/CD 环境尤其要注意：缓存的
composer.lock会让流水线持续走错源，得清缓存或加rm -rf vendor composer.lock步骤
为什么还是连 packagist.org？大概率是 fallback 没关死
即使你写了镜像 URL，Composer 默认仍会在镜像查不到包时自动 fallback 到 packagist.org，这在 CI 或网络受限环境里极易超时或失败：
-
{"packagist.org": false}这行必须存在，且是repositories数组里的一个独立对象 - 某些镜像（如腾讯云）同步有延迟，新发布的包还没同步过来，又禁了官方源，就会报
Could not find package xxx - 临时排查可用
composer install -vvv --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/，加-vvv才能看到真实请求域名
最易被忽略的一点：项目里已有 repositories 字段（比如私有包源），直接手写覆盖会删掉原有配置；应该用 composer config repo.packagist composer ...（不带 -g）让 Composer 自动 merge。
