镜像配置“看似生效”但实际失效的典型表现是执行 composer config -g repo.packagist 返回了设置的镜像 url，而 composer install 仍卡在下载官方源 packages.json；根本原因是缓存未清理，composer 优先读取 ~/.composer/cache/repo/ 下过期的元数据快照。
镜像配置“看似生效”但实际失效的典型表现
执行 composer config -g repo.packagist 返回了你设置的镜像 URL，但 composer install 仍卡在 Downloading https://packagist.org/packages.json ——这不是网络问题，而是缓存里还存着旧源的元数据快照。Composer 启动时优先读 ~/.composer/cache/repo/ 下的 packages.json，哪怕你已改配置，只要缓存没清，它就照着老快照找包，404 或超时是必然结果。
缓存污染比配置错误更隐蔽也更致命
镜像损坏的本质不是 JSON 写错了，而是 ~/.composer/cache/files/ 里某个中断下载的 .zip 文件（比如因断网写了一半），或 ~/.composer/cache/repo/ 中过期/错位的 provider-*.json。这类文件不会报“配置错误”，但会导致：
- Failed to extract 或 corrupted archive
- 某个包反复安装失败，删 vendor/ 也没用
- composer update 显示 “Nothing to install”，明明镜像站已有新版本
- 清缓存是唯一能切断污染链的操作：
composer clear-cache会删掉所有 ZIP、provider 和 packages.json 缓存 - 只改配置不清理，等于给坏轮胎换气嘴——表面动作做了，根本问题还在
- Windows 用户注意：
clear-cache不会自动清理%LOCALAPPDATA%\Composer\Cache\下的残留，需手动确认路径
三层配置叠加导致“你以为的生效”其实是假象
Composer 查源顺序是：环境变量 > 项目级 composer.json 的 repositories > 全局 repo.packagist。你全局设好了阿里云镜像，但项目里有这一段：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
{"repositories": [{"type": "composer", "url": "https://packagist.org"}]}
那全局配置就彻底失效。更麻烦的是：composer config -g repo.packagist 依然显示阿里云地址，让你误判问题出在别处。
- 验证真实生效源，不能只看配置输出，要跑：
composer diagnose -v，末尾那行Checking https://...才是真实请求地址 - 项目级
repositories字段哪怕只是空数组[]，也会屏蔽全局设置 - 环境变量
COMPOSER_REPO_PACKAGIST优先级最高，且不随终端关闭自动清除
重置不是“回到出厂设置”，而是精准切断干扰链
所谓“一键重置”，核心就两步：composer clear-cache 切断缓存污染，composer config -g repo.packagist composer https://packagist.org 强制覆盖全局源。中间任何一环缺失，都会让重置失效。
- 别用
--unset删除字段，Composer 2.x 不会自动 fallback 到官方源，反而可能报Package not found - 如果项目必须保留私有源，不要删
repositories，而是用命令合并：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不带-g） - 重置后立刻验证，不是看命令是否成功，而是抓一次真实请求：
composer install -vvv 2>&1 | grep -i 'GET https'
最容易被忽略的点：缓存目录权限异常或磁盘满，会导致 clear-cache 表面成功实则未真正清空。运行完建议手动 ls -la $(composer config --global cache-dir) 确认子目录是否为空。
