哈希不匹配是 Composer 的安全拦截机制，非网络问题——需同步 composer.lock 与源、清双缓存、禁用镜像验证。常见原因含镜像滞后、tag 重推、私有源不一致等；修复须 rm -rf vendor composer.lock 后切官方源重装；预防重在统一版本、提交 lock、禁用构建缓存。
哈希不匹配不是网络抖动，是 Composer 主动拒绝加载可疑包——别 retry，先确认校验源是否可信。
checksum mismatch 错误的真正原因
这个报错不是下载中断或缓存脏了那么简单。checksum mismatch 表示 Composer 下载下来的 zip 包，和 composer.lock 里记录的 dist.sha256（或 sha384）对不上。它触发的是安全拦截，不是重试逻辑。
- 国内镜像源缓存滞后：阿里云/腾讯云镜像还没同步新版 tag，但
composer.lock已记录新哈希 - tag 被重推：包作者删掉旧 release、重新打同名 tag，导致旧 lock 文件里的哈希失效
- 私有仓库或自建 Satis 返回的 dist URL 和 checksum 与 packagist.org 不一致
- 代理或企业网关篡改了响应体（少见但真实存在）
别只删 vendor，必须连 composer.lock 一起重建
只运行 rm -rf vendor 然后 composer install，会复用错误的 composer.lock，错误照常出现。真正有效的清理是“元数据+安装物”双清。
- 先备份：
cp composer.lock composer.lock.bak - 彻底清除：
rm -rf vendor composer.lock（Windows 用rd /s /q vendor & del composer.lock） - 切回官方源保真：
composer config -g --unset repos.packagist（去掉镜像干扰） - 重装生成新锁：
composer install—— 此时会拉取最新元数据，生成带当前有效哈希的新composer.lock
如果必须用国内镜像，等阿里云同步完成（通常 10–30 分钟），再执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
临时绕过校验仅限调试，且方式已受限
加 --ignore-platform-reqs 或 --no-plugins 不影响哈希校验；真正跳过需用环境变量，但风险高、不推荐上线。
- 临时验证是否为校验机制本身导致阻塞：
COMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer install - 该变量在 Composer 2.2+ 已被标记为
deprecated，未来版本会移除 -
composer config -g secure-http false会同时禁用 HTTPS 强制要求，比单纯关 checksum 更危险 - 绕过 ≠ 修复：下次不带变量仍会报错，且不会修正
composer.lock中的错误哈希
如何预防下次再踩坑
哈希不匹配问题本质是“锁定文件”和“分发源”之间的时间差或信任链断裂。日常维护的关键是让两者保持同步节奏。
- 团队统一 Composer 版本：用
composer self-update 2.5.8对齐，避免 1.x 和 2.x 混用导致 lock 格式不兼容 -
composer.lock必须提交 Git：每次composer update后都git add composer.lock && git commit - CI 流程中禁用缓存干扰：
composer clear-cache && composer install --no-cache，确保每次构建都走真实校验 - 检查 PHP 基础依赖：
openssl扩展必须启用，allow_url_fopen = On，否则校验阶段可能静默失败
最常被忽略的一点：你以为在修 vendor，其实问题藏在 lock 文件和镜像源的配合关系里——不看 composer.lock 头部的 content-hash 和你当前 Composer 版本是否匹配，就动手删目录，等于蒙眼换轮胎。
