composer报hash mismatch错误时应先清缓存而非删vendor，因问题根源在本地缓存或镜像同步延迟；优先执行composer clear-cache，并检查镜像源一致性、composer.json格式及content-hash生成机制。
composer install/update 报 Hash mismatch 错误时，先别删 vendor
这个错误本质是 Composer 在校验下载包的完整性时失败了，不是网络中断或权限问题，而是本地缓存或远程包元数据不一致。常见现象是执行 composer install 或 composer update 卡在某个包，然后抛出类似 Hash mismatch: expected ..., got ... 的报错。
直接删 vendor 和 composer.lock 重来，大概率还会复现——因为问题根源在 Composer 自己的缓存层或镜像同步延迟。
- 优先运行
composer clear-cache，它会清掉~/.composer/cache下所有包归档、元数据和 ZIP 校验信息 - 如果用的是国内镜像（如阿里云、腾讯云），加
-vvv看实际下载地址，确认是否指向镜像源；有时镜像没及时更新 packagist.org 的新 hash，会导致校验失败 - 临时切回官方源验证：运行
composer config -g repo.packagist composer https://packagist.org，再试一次composer update
lock 文件里 content-hash 和实际依赖不一致怎么办
composer.lock 顶部的 content-hash 是对 composer.json 内容（包括 require/dev-require 版本约束、平台配置等）做的哈希，不是对依赖树的快照。它变了但没改 composer.json？大概率是文件换行符、空格或 UTF-8 bom 导致的。
- 用
git diff --ignore-space-at-eol composer.json查看是否只有换行差异（windows/Mac/linux 混合开发常见） - 用
file composer.json检查是否含 BOM：composer.json: UTF-8 Unicode (with BOM) text就要重存为无 BOM UTF-8 - 不要手动改
content-hash字段——它由 Composer 自动生成，改了会导致后续install跳过依赖解析
某些包（比如 laravel/framework）反复报 hash 不匹配
这类高频率更新的包容易撞上镜像同步窗口期：packagist.org 已发布新版本 ZIP，但镜像还没拉取完，或只同步了 composer.json 元数据，没同步对应 ZIP 归档。此时 Composer 下载到的是旧 ZIP，但校验值是新的，必然失败。
- 检查该包最新版发布时间：
curl -s "https://packagist.org/packages/laravel/framework.json" | jq '.package.packages."laravel/framework"[] | .time' | head -1 - 等 10–15 分钟再试，或临时指定稳定小版本绕过，例如把
"laravel/framework": "^11"改成"laravel/framework": "11.9.2" - 不用
--prefer-dist强制走 ZIP（默认就是），但可加--no-cache跳过本地缓存，直连源站校验
CI/CD 流水线里出现 hash 错误，怎么稳定住
CI 环境通常禁用交互、缓存不可靠，且多任务并发可能污染全局 cache。不能依赖开发者本地 clear-cache 那一套。
- 在 CI 脚本开头固定加
composer clear-cache，哪怕慢一点也比随机失败强 - 用
composer install --no-interaction --optimize-autoloader --ignore-platform-req=ext-xdebug，去掉所有干扰项 - 确保
composer.lock提交进 Git，且 CI 拉取的是带 lock 的完整 commit——没 lock 文件时，install会退化成update，触发全新解析和下载，hash 失败概率陡增
最麻烦的情况是私有仓库 + 自建 Satis + CDN 缓存没刷新，这时候 hash 错误根本不会提示具体哪个环节出了问题，得一层层查 HTTP 响应头里的 ETag 和 Last-Modified。