Checksum mismatch 错误是因下载包的 SHA256/SHA384 校验值与官方记录不符，触发 Composer 安全保护；主因包括镜像缓存滞后、tag 重推导致 lock 文件校验值失效、代理篡改响应或私有仓库 checksum 不一致。
Composer install/update 报 checksum mismatch 错误的原因
这个错误本质是 Composer 下载的包文件和官方仓库记录的 SHA256（或 SHA384）校验值对不上，触发了安全保护机制。不是网络抖动或临时失败，而是明确拒绝加载可能被篡改或损坏的包。
常见触发场景包括：
— 本地
镜像源
（如
阿里云
、
腾讯
云）缓存了旧版包但元数据已更新
—
中记录的 checksum 来自旧版 packagist.org，而当前下载的是新版构建（尤其发生在包作者重推 tag 后）
— 代理/CDN 中间层修改了响应体（极少见，但企业网络中存在）
清除 vendor + lock 文件并重新生成是最稳妥的解法
不要只删
或只跑
—— 这会复用旧
里的错误 checksum，错误会复现。
执行
（Windows 用
）
确认当前使用的是可信源：
（若曾设过镜像，先清掉：
）
运行
，让 Composer 从头拉取元数据并生成新
如果必须用国内镜像，等同步完成后再切回（阿里云通常 10–30 分钟内同步完毕），不要在同步中途强制指定镜像源。
临时跳过 checksum 校验（仅限调试，禁止上线）
这不是修复，是绕过。仅用于确认是否为 checksum 机制本身导致阻塞，或排查 CI 环境中不可控的中间层干扰。
Trae win
Trae Windows 官方版本现已全面支持 Win10 和 Win11 系统（64位）。国内开发者可直接访问 Trae 中文官网（trae.cn 或 trae.com.cn），一键下载官方正版 .exe 安装包，享受国内直连的高速稳定体验。安装过程极其简便，双击即可运行，并支持一键无缝导入 VS Code 或 Cursor 的原有主题、快捷键及插件配置。登录支持手机号、微信或稀土掘金账号。内置免费的豆包与 DeepSeek 等顶级大模型，让你开箱即用，轻松开启高效的 AI 智能编程之旅。
下载
不影响 checksum 校验
真正跳过需加
环境变量
：
或者临时修改全局配置：
（注意：这同时禁用 HTTPS 强制要求，风险更高）
该方式不会修正锁文件，下次不带变量仍会报错；且
在 Composer 2.2+ 已标记为 deprecated，未来版本会移除。
检查是否被私有仓库或 fork 干扰
如果你的
中声明了
，尤其是 type
或自建 Satis/SatisPress 服务，它们返回的 dist 包 URL 和 checksum 可能与 packagist.org 不一致。
运行
查看所有注册源
临时注释掉
块，再试
检查 fork 的包是否打了同名 tag 但内容不同 —— Composer 无法区分“哪个才是权威”，只会按配置顺序取第一个匹配源
私有源务必确保其
下载地址返回的 ZIP 文件与它在
中声明的
完全一致，否则每次 install 都会失败。
composer.lockvendor/composer updatecomposer.lockrm -rf vendor composer.lockrd /s /q vendor & del composer.lockcomposer config -g repo.packagist composer https://packagist.orgcomposer config -g --unset repos.packagistcomposer installcomposer.lockcomposer install --ignore-platform-reqs --no-pluginsCOMPOSER_DISABLE_CHECKSUM_VERIFY=1 composer installcomposer config -g secure-http falseCOMPOSER_DISABLE_CHECKSUM_VERIFYcomposer.jsonrepositoriesvcscomposer config repositoriesrepositoriescomposer installdistpackages.jsondist.shasum