Checksum mismatch 错误是因下载包的 SHA256/SHA384 校验值与官方记录不符，触发 Composer 安全保护；主因包括镜像缓存滞后、tag 重推导致 lock 文件校验值失效、代理篡改响应或私有仓库 checksum 不一致。
Composer install/update 报 checksum mismatch 错误的原因
这个错误本质是 Composer 下载的包文件和官方仓库记录的 SHA256（或 SHA384）校验值对不上，触发了安全保护机制。不是网络抖动或临时失败，而是明确拒绝加载可能被篡改或损坏的包。
常见触发场景包括：
— 本地镜像源（如阿里云、腾讯云）缓存了旧版包但元数据已更新
— composer.lock 中记录的 checksum 来自旧版 packagist.org，而当前下载的是新版构建（尤其发生在包作者重推 tag 后）
— 代理/CDN 中间层修改了响应体（极少见，但企业网络中存在）
清除 vendor + lock 文件并重新生成是最稳妥的解法
不要只删 vendor/ 或只跑 composer update —— 这会复用旧 composer.lock 里的错误 checksum，错误会复现。
- 执行
rm -rf vendor composer.lock（Windows 用rd /s /q vendor & del composer.lock） - 确认当前使用的是可信源：
composer config -g repo.packagist composer https://packagist.org（若曾设过镜像，先清掉：composer config -g --unset repos.packagist） - 运行
composer install，让 Composer 从头拉取元数据并生成新composer.lock
如果必须用国内镜像，等同步完成后再切回（阿里云通常 10–30 分钟内同步完毕），不要在同步中途强制指定镜像源。
临时跳过 checksum 校验（仅限调试，禁止上线）
这不是修复，是绕过。仅用于确认是否为 checksum 机制本身导致阻塞，或排查 CI 环境中不可控的中间层干扰。
-
composer install --ignore-platform-reqs --no-plugins不影响 checksum 校验 - 真正跳过需加环境变量：
COMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer install - 或者临时修改全局配置：
composer config -g secure-http false（注意：这同时禁用 HTTPS 强制要求，风险更高）
该方式不会修正锁文件，下次不带变量仍会报错；且 COMPOSER_DISABLE_CHECKSUM_VERIFY 在 Composer 2.2+ 已标记为 deprecated，未来版本会移除。
检查是否被私有仓库或 fork 干扰
如果你的 composer.json 中声明了 repositories，尤其是 type vcs 或自建 Satis/SatisPress 服务，它们返回的 dist 包 URL 和 checksum 可能与 packagist.org 不一致。
- 运行
composer config repositories查看所有注册源 - 临时注释掉
repositories块，再试composer install - 检查 fork 的包是否打了同名 tag 但内容不同 —— Composer 无法区分“哪个才是权威”，只会按配置顺序取第一个匹配源
私有源务必确保其 dist 下载地址返回的 ZIP 文件与它在 packages.json 中声明的 dist.shasum 完全一致，否则每次 install 都会失败。
