composer clear-cache必须最先执行，因其清理的repo/元数据缓存（如packages.json快照）控制composer请求逻辑，不清则镜像配置无效，仍会按旧源请求导致404或损坏包。
为什么 composer clear-cache 必须最先执行
缓存不是“顺手清一下”的可选项，而是 Composer 请求逻辑的元数据中枢。不先清，后续所有镜像配置操作都等于对空气说话——composer install 仍会按旧 packages.json 快照去请求，结果还是 404 或 corrupted archive。
composer clear-cache 实际清理三类关键内容：
-
files/：中断下载或损坏的 ZIP 包（比如guzzlehttp/guzzle卡在 extract 阶段） -
repo/：本地保存的packages.json和provider-*.json快照（15 分钟默认不过期，改了镜像也无效） -
vcs/：Git 裸库缓存（影响dev-master类版本拉取）
若提示 Permission denied，常见原因是曾用 sudo composer，需修复属主：sudo chown -R $USER:$USER ~/.composer/cache。切勿直接 rm -rf ~/.composer/cache——IDE 或后台进程可能正锁着某些文件，删完会导致后续索引错乱。
配置 repo.packagist 的三个硬性条件
键名、type 值、URL 结尾斜杠，三者错一个就静默失效。命令跑完没报错，但 composer install -vvv 日志里依然出现 packagist.org，大概率是这里错了。
- 键名必须是
repo.packagist（单数），不是repos.packagist或repositories -
type必须显式指定为"composer"，不能省略或写成composer-type - URL 必须是 HTTPS 且以
/结尾，例如：https://mirrors.aliyun.com/composer/（少斜杠会拼出/composerpackages.json导致 404）
正确写法：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。验证输出应为 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 或纯 URL 字符串。空、null、或仍是官方地址，说明配置失败。
确认当前生效的镜像来源，别只信 composer config
composer config -g repo.packagist 只告诉你“写了什么”，不等于“生效了什么”。真实请求优先级是：COMPOSER_REPO_PACKAGIST 环境变量 > 项目级 repositories > 全局 repo.packagist > 默认源。
- 查全局配置：
composer config -g repo.packagist（返回空或报错说明未设） - 进项目目录查项目级：
composer config repo.packagist或检查composer.json中"repositories"字段 - 查环境变量：
echo $COMPOSER_REPO_PACKAGIST（Linux/macOS）或echo %COMPOSER_REPO_PACKAGIST%（Windows） - 最可靠验证：
composer diagnose -v，末尾明确显示Checking https://repo.packagist.org/packages.json才算回到官方源
如何让 Composer 真正拿到新发布的包版本
用镜像本身不等于能立刻获取新包——Composer 默认复用本地 packages.json 缓存（15 分钟不过期），哪怕阿里云镜像上已有 monolog/monolog v3.6.0，你本地还在按旧列表算依赖。
- Composer ≥ 2.5：用
composer update --refresh，它只清理repo/下对应镜像的元数据（如https---mirrors-aliyun-com-composer/packages.json），不碰 ZIP 包和 lock 文件 - Composer ≤ 2.4：手动删缓存目录：
rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer，再跑composer update - 验证镜像是否同步：用
curl -I https://mirrors.aliyun.com/composer/packages.json看Last-Modified时间；查具体包用curl -s https://mirrors.aliyun.com/composer/p2/vendor/package-name.json | jq -r '.packages."vendor/package-name" | keys[]' | sort | tail -3
真正容易被忽略的是：镜像元数据同步有延迟，且 Composer 不主动校验镜像状态。你看到 composer config 输出了阿里云地址，不代表它此刻就能拉到你要的新版包——得亲手查接口、比时间、看版本列表才作数。
