唯一能真正修复 checksum mismatch 的做法是删除 vendor 和 composer.lock 后重新运行 composer install；因为仅清缓存或只删 vendor 仍会复用 composer.lock 中已失效的旧校验和，导致校验失败。
遇到 The checksum verification failed，别急着改配置或跳过校验——95% 的情况是 vendor/ 和 composer.lock 里存着已失效的旧校验值，必须一起清理才能真正修复。
为什么只清缓存或只删 vendor 不行
Composer 校验失败不是下载出错，而是比对失败：它拿 composer.lock 里记录的 SHA256 值，去核验刚下载的包文件。一旦 lock 文件里的 hash 来自旧版包（比如作者重推了 tag），而你又没删 lock，重装时仍会用错值去校验新文件，必然失败。
-
composer clear-cache只删下载缓存，composer.lock里的错误 checksum 还在 - 只
rm -rf vendor，composer install仍照 lock 文件里的旧 hash 去校验 - Windows 下要同时执行：
rd /s /q vendor & del composer.lock
如何确认是不是镜像源同步延迟
国内镜像（阿里云、腾讯云等）通常有 10–30 分钟同步延迟，尤其新发版或 dev 分支。不能靠“换镜像”蒙混过关，得验证。
- 先切回官方源：
composer config -g --unset repos.packagist && composer config -g repo.packagist composer https://packagist.org - 再
composer clear-cache && composer install—— 如果成功，基本就是镜像没跟上 - 别立刻切回原镜像；等 30 分钟，或换华为云等已知同步更快的源
- 注意：某些私有仓库或
type: vcs配置会覆盖镜像行为，composer config repositories可查真实生效源
哪些操作只是绕过，不是修复
临时禁用校验能让你跑通命令，但掩盖了根本问题，且 Composer 2.2+ 已明确弃用相关机制。
-
COMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer install：已标记为 deprecated，未来版本会移除 -
composer config -g secure-http false：不仅跳过 checksum，还允许不安全的 HTTP 源，风险极高 -
--no-verify-checksums或--ignore-platform-reqs：这些参数根本不影响 checksum 校验逻辑，对checksum verification failed无效 - 手动编辑
composer.lock改 hash：极危险，可能引入不一致依赖
容易被忽略的底层干扰点
真正难排查的 case 往往不在 Composer 本身，而在环境层。
- 系统时间偏差 > 3 分钟：会导致 HTTPS 证书验证失败，间接造成下载截断，文件不完整 → 校验必败
- 企业代理或防火墙：某些中间设备会重写响应体（如注入脚本、压缩 HTML），哪怕只动一个字节，hash 就对不上
-
composer.json里写了自定义repositories，尤其是type: vcs：它的 dist 包 URL 和 checksum 与 packagist.org 不一致，连官方源也会报错 - PHP 的 OpenSSL 扩展未启用：
php -m | grep openssl必须有输出，否则 HTTPS 下载不可靠
