哈希不匹配是 composer.lock 记录的 shasum 与下载包实际哈希值不一致，主因是包重推、镜像滞后或本地篡改；应删 vendor 和 lock 后重装，并确认镜像配置生效。
哈希不匹配不是缓存脏了，是 lock 文件和实际包“对不上号”
报错 Invalid checksum for ... 或 Content-Length mismatch，本质不是文件损坏，而是 composer.lock 里记的 shasum 和你这次下载到的 zip 包算出来的哈希值不一致。常见于：包作者重推了同一个 tag、国内镜像源同步滞后、或你本地曾手动改过 vendor/ 或缓存目录。
- 别只删
vendor/然后跑composer install——它会复用旧 lock 文件里的错误哈希，报错照旧 - 也别只跑
composer update vendor/package-name——它不会刷新整个 lock 的校验上下文，可能漏掉依赖链中其他包的哈希冲突 - 最稳做法是：删干净
vendor/和composer.lock，再重新生成锁文件
强制重装前必须确认镜像源是否真正生效
很多人切了阿里云镜像却仍卡在超时或哈希错，是因为配置没落进实处——比如被项目级 repositories 覆盖，或 DNS 解析失败导致请求根本没走到镜像站。
- 验证全局镜像：运行
composer config -g repos.packagist，输出应为{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，而不是packagist.org - 手动测镜像可用性：
curl -I https://mirrors.aliyun.com/composer/packages.json，要秒回HTTP/2 200才算通 - 若企业内网 TLS 握手卡死，临时关 SSL 验证：
composer config -g secure-http false（完事务必composer config -g secure-http true恢复）
修复命令组合比单条命令更可靠
单一命令容易遗漏环节，比如清缓存不彻底、忽略平台要求、或没跳过 Git clone 导致触发 GitHub API 限流。CI/CD 中尤其明显。
- 先清缓存：
composer clear-cache - 删干净：
rm -rf vendor composer.lock（Windows 用rd /s /q vendor & del composer.lock） - 指定 dist 安装（跳过 git clone）：
composer install --prefer-dist - 如需绕过 PHP 版本等平台检查（仅调试用）：
composer install --ignore-platform-reqs
临时跳过校验只是排查手段，不是解决方案
COMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer install 可以让你快速判断是不是哈希机制本身在拦路，但它不修复任何东西，也不更新 lock 文件——下次不带这个变量照样报错，且该环境变量在 Composer 2.2+ 已被标记为 deprecated，未来版本会删。
- 它不能解决镜像不同步、包被重推、中间代理篡改响应体等问题
- 它会让后续 CI 构建不可重现，因为校验逻辑被绕过
- 真正需要的是让
composer.lock和当前源、当前网络、当前 Composer 版本彼此兼容
哈希校验本身很轻量，问题从来不在它太严，而在于你没让元数据、缓存、镜像、lock 文件这四者对齐。
