Composer 安装包 hash 校验失败本质是下载内容与 composer.lock 中记录的 sha256/sha1 不一致，主因包括镜像同步延迟、代理缓存污染、本地磁盘静默错误、Composer 缓存损坏或 OpenSSL 扩展异常。
Composer 安装包 hash 校验失败，本质是下载的包内容与 composer.lock 中记录的 sha256（或 sha1）不一致，不是网络中断或权限问题，而是文件完整性被破坏——常见于代理缓存污染、镜像源同步延迟、本地磁盘静默错误，或 Composer 自身缓存损坏。
检查是否用了国内镜像且镜像不同步
很多用户配置了阿里云、腾讯云等镜像源，但这些镜像并非实时同步 Packagist，尤其对 dev 分支或刚发布的版本，composer.lock 里记录的是上游的 hash，而镜像返回的是旧版包（或中间版本），导致校验失败。
- 临时切回官方源验证：
composer config -g repo.packagist composer https://packagist.org - 运行
composer install看是否通过；若通过，说明镜像有问题 - 不要直接删
composer.lock重生成——这会丢失依赖锁定语义 - 可改用更稳定的镜像，如
https://packagist.phpcomposer.com（已停用）或当前推荐的https://packagist.org+COMPOSER_HOME缓存隔离
清除 Composer 下载缓存和已解压包
Composer 会把 zip 包缓存在 COMPOSER_HOME/cache/files/，并解压到 vendor/。如果某次下载中断后缓存残留损坏 zip，后续重试仍会读取坏文件，hash 必然失败。
- 执行
composer clear-cache（它会清files/和repo/缓存） - 手动确认
vendor/是否残留部分解压内容：若有，先rm -rf vendor/ - 避免在 CI 中复用未清理的
~/.composer/cache目录——不同 job 可能混用脏缓存
确认 PHP OpenSSL 扩展是否正常启用
Composer 用 PHP 的 openssl_verify 和 hash_file 做校验，若 openssl 扩展未加载或被禁用函数拦截，会跳过校验或报错不明确（如 Hash mismatch 但无具体 hash 对比）。
- 运行
php -m | grep openssl确认扩展存在 - 检查
php.ini中是否设置了disable_functions = hash_file,openssl_verify - 某些 Docker 镜像（如
php:alpine）默认不带openssl，需额外apk add openssl - 校验逻辑不走 cURL 选项，所以
curl.cainfo配置错误不会导致 hash 失败，但会影响包下载本身
真正麻烦的是那种「偶尔失败」的情况——比如只在某台 CI 机器上出问题，本地完全正常。这时候大概率是磁盘静默错误、内存故障，或宿主机挂载卷的 cache 模式（如 cached 或 delegated）导致文件读取不一致。别急着重装 Composer，先 dd if=/dev/zero of=test bs=1M count=100 && sha256sum test 看 hash 是否稳定。
