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/

• 执行 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 是否稳定。