必须同步删除vendor和composer.lock后重新运行composer install，因为校验失败根源在于composer.lock中硬编码的dist.sha256与新下载包不匹配，仅清缓存或只删vendor无法更新该哈希值。
校验冲突不是镜像问题，是 lock 文件哈希过期
“The checksum verification failed”或“Checksum mismatch”错误，95% 的情况跟镜像本身无关，而是 composer.lock 里硬编码的 dist.sha256 值和当前下载包实际内容对不上。镜像只是把旧哈希对应的旧包（或新包）更快地拉下来，然后 Composer 立刻比对失败——它不关心你用的是阿里云还是腾讯云，只认哈希。
- 常见诱因：包作者重推了
v2.1.0tag、镜像缓存滞后、私有repositories返回的 dist URL 和官方不一致 -
composer clear-cache只清~/.composer/cache/，不影响composer.lock里的哈希，所以无效 - 只删
vendor/再跑composer install，仍会复用旧 lock 文件里的错误哈希，必然重报
必须同步清理 vendor 和 composer.lock
真正有效的修复动作是原子性清除：lock 文件和已安装代码必须一起丢掉，否则校验逻辑永远卡死在旧约定上。
- Linux/macOS 执行：
rm -rf vendor composer.lock - Windows 执行：
rd /s /q vendor & del composer.lock - 切回官方源保真：
composer config -g --unset repos.packagist（注意是repos.packagist，不是repo.packagist） - 再执行
composer install——此时会重新拉取完整元数据，生成全新composer.lock，所有哈希来自同一快照
为什么不能只用镜像“同步等待”
阿里云等镜像通常 10–30 分钟同步新版包，但你无法判断当前 composer.lock 记录的是哪个时间点的哈希。如果 lock 是上周生成的，而镜像今天刚同步，两者依然不匹配。强行在同步中途切回镜像，等于拿一个不确定是否一致的源去验证一个确定过期的哈希。
- 临时加
COMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer install仅用于调试，且该变量在 Composer 2.2+ 已被标记为 deprecated -
composer why-not对校验失败完全无响应，因为它发生在依赖解析之前，不属于约束冲突范畴 - 运行
composer show --locked | head -20可确认报错包是否出现在 lock 列表中；若未出现，说明它根本没进依赖树，不是why-not的管辖范围
项目级 repositories 会绕过镜像加速
只要 composer.json 里定义了 "repositories" 字段（尤其是 "type": "vcs" 或自定义 "type": "package"），Composer 就会优先走这个源，完全跳过全局镜像配置。这时候你看到的 “Downloading https://xxx” 地址，很可能就是你手动写的那个私有地址，而不是阿里云。
- 检查命令：
composer config repositories，看输出里是否有同名"name"条目（比如两个都写"monolog/monolog"） - 临时禁用：
composer config --unset repositories，再跑composer install -v观察日志中的下载 URL 是否变成https://repo.packagist.org/... - 若必须保留私有源，确保其
dist.sha256与 packagist.org 一致，否则校验必然失败
复杂点在于：校验失败往往和开发习惯强相关——比如手动改过 vendor/ 里的代码、Git 换行符自动转换、IDE 格式化触发文件内容变更。这些操作不会报错，但会让哈希悄然失效。一旦出问题，别先怀疑镜像，先看 composer.lock 和 vendor/ 是否还对得上。
