Composer镜像安装依赖验证_确认包完整正确

你可能遇到过这种怪事：composer install 跑得顺顺当当，一个报错都没有，但项目跑起来就是各种诡异——缺文件、类找不到、行为不对劲。排查半天，最后发现 vendor/ 里某个包的代码跟 composer.lock 里记录的版本“对不上号”。这是 Composer 的 bug 吗？不，其实是设计如此：默认情况下，它压根不校验你已经装好的包到底对不对。

composer install 为什么没报错但包内容错了

关键在于 Composer 只在首次下载 dist 包（zip 或 tar 格式）时，才会去比对 composer.lock 里记录的 dist.sha256 和解压后根目录的哈希值。一旦这个包已经被缓存过、或者你用了 --prefer-source 直接从 Git 拉代码、又或者镜像源替你替换了原始 dist 包——那这趟校验就彻底绕过去了。

现实里常见的“坑”有这些：

• 本地 vendor/ 被人手动改过或删了部分文件，composer install 两眼一抹黑，完全察觉不到
• 国内镜像（阿里云、腾讯云等）没有严格同步 Packagist 的 dist 包签名，哈希可能“碰巧匹配”但内容已经被替换
• composer.lock 是旧版生成的，当前用的是新版 Composer（比如 2.5+），但 lock 文件里根本没写 content-hash 或 dist.sha256 字段
• 项目里用了 "type": "package" 或 path 仓库，这类 source 安装方式压根不走哈希校验流程

启用 verify-checksums 实验性校验（推荐部署阶段用）

Composer 从 2.4 版本开始提供了 verify-checksums 命令，这是目前最接近“部署前验包”的官方方案。不过它仍是实验性功能，需要你显式开启环境变量才能用。

实操时有几个要点得记牢：

• 必须加上 COMPOSER_EXPERIMENTAL=1，否则命令压根不存在
• 强烈建议带上 --strict 参数——它能让命令在校验失败时返回非零退出码，这样 CI/CD 流程才能真正中断，而不是“继续往下跑”
• 执行前确保 vendor/ 已存在且 composer.lock 是最新的（也就是刚跑完 composer install）
• 它只针对 dist 包生成的 vendor 子目录做校验，对 source 类型包不适用

示例命令：

COMPOSER_EXPERIMENTAL=1 composer verify-checksums --strict

镜像配置不影响 verify-checksums 的校验逻辑

不管你用的是阿里云镜像还是官方源，verify-checksums 的行为都不受影响——它只读 composer.lock 里的 dist.sha256，然后重新计算本地 vendor/{package}/ 目录的哈希值。镜像只决定 install 阶段从哪下载 zip，跟后续校验依据没什么关系。

但这里有个陷阱你必须小心：

• 如果镜像源返回的 dist 包和 Packagist 官方不一致（比如偷偷打了补丁但没更新 sha256），那么 verify-checksums 一定会报错
• 这种报错不是 bug，恰恰是安全机制在起作用——它忠实地告诉你：“你装的包，和 lock 文件承诺的不一样”
• 正确的做法不是关掉校验，而是换镜像、切回官方源、或者联系镜像维护方确认一致性

真正卡住部署的最小可靠组合

光靠 composer install 永远无法保证 vendor 目录的完整性。生产环境的部署脚本里，必须把两步串联起来：

• 先跑 composer install --no-interaction --no-scripts --no-plugins（避免脚本干扰校验）
• 再跑 COMPOSER_EXPERIMENTAL=1 composer verify-checksums --strict

缺一不可。跳过第一步直接校验，会因 vendor 缺失而报错；跳过第二步，等于把校验权交给了镜像和网络——而这两者恰恰是最不可信的环节。