Composer拉VCS包报“hash verification failed”主因是Git快照与dist包校验值不匹配,需清空~/.composer/cache/vcs/、删除对应vendor子目录及composer.lock中相关条目,并用--no-cache --no-plugins --no-scripts强制重拉。

哈希错误不是缓存没清干净,而是 Git 快照和 dist 包校验值对不上
Composer 拉 VCS(Git)包时报 hash verification failed,常见于用 repositories 配置了 "type": "vcs" 的私有仓库或本地 path 包。它和 dist 包的校验失败逻辑不同:VCS 不走 ZIP 下载+SHA256 校验,而是先 clone 仓库、检出 commit、再生成 dist 包(或 symlink),但 composer.lock 里仍硬编码了该 commit 对应的 dist.sha256 值——如果这个值是旧版生成的、或镜像源篡改过元数据、或你本地改过代码又没重生成 lock,就会比对失败。
删错目录等于白干:vcs/ 必须清,files/ 和 repo/ 可不动
VCS 包的校验依赖两个关键缓存位置:
-
~/.composer/cache/vcs/:存放 Git 裸仓库快照,每次composer update都可能复用它,哪怕你改了代码,它仍 checkout 旧 commit -
vendor/vendor/name/:如果是 symlink 模式(path 类型),这里只是软链,不参与校验;但如果是 dist 模式("dist": {"url": "...", "sha256": "..."}),则files/下 ZIP 才会被校验
所以正确清理顺序是:
- 删掉
~/.composer/cache/vcs/*(Linux/macOS)或%APPDATA%\Composer\Cache\Vcs\*(Windows) - 删掉项目级
vendor/vendor/name目录(不是整个vendor/) - 删掉
composer.lock中对应包的条目,或直接删整个composer.lock - 不要碰
cache/files/和cache/repo/——它们对纯 VCS 拉取无直接影响
强制重拉必须关掉缓存和插件,否则还是走旧快照
执行 composer update vendor/name --no-cache --no-plugins --no-scripts 是最低安全要求。原因如下:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
-
--no-cache:跳过vcs/缓存复用,强制重新 clone -
--no-plugins:防止插件(如hirak/prestissimo)劫持下载逻辑,绕过校验 -
--no-scripts:避免 post-update-cmd 脚本触发提前 autoload 或写入临时文件,干扰状态 - 不加
--force-checksums—— 它对 VCS 无效,因为 VCS 没有预设 checksum,只有 dist 包才用
如果仍失败,说明 Git URL 或凭据有问题:手动跑 git clone 看是否能成功,尤其注意 SSH 密钥是否已加载(ssh-add -l)、HTTPS 是否被 credential helper 缓存了过期密码。
path 类型包改了代码却不生效?autoload 没重建是真凶
用 "type": "path" 引用本地包时,hash verification failed 很少出现,但你会遇到“改了类却报 Class not found”。这不是校验问题,是 autoload 未更新:
- Composer 创建的是 symlink,不自动触发
dump-autoload - 必须手动运行
composer dump-autoload -o(项目根目录下) - 若本地包自身改了
autoload字段(如从"psr-4"改成"classmap"),还要加--classmap-authoritative - Docker 或 CI 中禁用
path——它只适合本地开发,上线必须切回真实 dist 包,否则部署机根本找不到路径
VCS 校验失败背后,往往不是网络或权限,而是 Composer 在多个缓存层之间“记混了”你到底想用哪个 commit、哪份 autoload 规则。最稳的做法永远是:清 vcs/ + 删对应 vendor/ 子目录 + 重跑 update 带完整 no-xxx 参数——别省那几秒,它真会卡在奇怪的地方。










