composer 2.5+ 需设 composer_experimental=1 启用 verify-checksums 命令，配合 --strict 才能严格校验 vendor/ 文件与 composer.lock 中 dist.sha256 是否一致。
Composer 本身不提供一键校验已安装包文件完整性的默认命令，composer verify-checksums 是唯一能真正比对 vendor/ 文件与 composer.lock 中哈希值的机制，但它从 2.5 版本起仍是实验性功能，必须显式启用。
如何启用并运行 verify-checksums 实验命令
这个命令不是开箱即用的，它不会出现在 composer list 默认输出中，除非你主动开启实验模式。
- 先确认 Composer 版本 ≥ 2.5：
composer --version，低于则运行composer self-update - 启用实验功能：必须在调用时设置环境变量
COMPOSER_EXPERIMENTAL=1，不能只设一次就全局生效 - 执行校验：
COMPOSER_EXPERIMENTAL=1 composer verify-checksums --strict -
--strict很关键——没有它，哪怕发现不匹配也只警告并返回 0，CI 流水线会误判为成功
为什么 composer install 不报错，但 verify-checksums 却失败
因为 composer install 只在校验下载的 dist 包（zip/tar）时比对哈希，且仅发生在首次安装或缓存失效时；一旦文件落地到 vendor/，后续就不再复查。而 verify-checksums 是真读磁盘、逐包计算当前目录内容的 SHA256，并与 composer.lock 中记录的 dist.sha256 字段比对。
- 常见触发点：手动修改过
vendor/下某个文件（比如调试时改了autoload.php）、CI 构建机被复用导致文件残留、Docker 多阶段构建中权限变更覆盖了文件 - 注意：它不校验
vendor/composer/autoload_*.php这类生成文件，只校验原始包发布的文件结构 - 如果
composer.lock里某包缺失dist.sha256字段（比如用了path类型源），该包会被跳过，但不会报错
verify-checksums 找不到不匹配文件？试试手动比对单个包
当 verify-checksums 报 “Checksum mismatch” 但没指明哪个文件时，说明它检测到整体哈希不一致，但没定位到具体路径——这是设计使然，它只做包级校验，不深入到单个 PHP 文件。
- 快速定位：用
composer show --locked vendor/package --format=json提取该包的dist.sha256值 - 手动计算：进入
vendor/vendor/package目录，运行find . -type f ! -name '.git*' ! -path './tests/*' -print0 | sort -z | xargs -0 shasum -a 256 | shasum -a 256（注意排除测试、Git 元数据等非发布内容） - 对比结果：两次 SHA256 是否一致？不一致就说明该包目录内有文件被改动或增删
- 别直接比
shasum -a 256 .—— 目录本身不可哈希，必须先归并所有文件字节流再算
生产环境部署前必须检查的三个点
完整性校验不是“做了就行”，而是要嵌入可信链路。很多团队加了 verify-checksums 却仍被绕过，问题出在执行上下文。
- 确保
composer.lock文件本身未被篡改：它应由可信 CI 生成并签入仓库，禁止人工编辑；若字段被删或哈希被清空，verify-checksums会直接退出 - 构建环境必须干净：不要复用旧
vendor/目录，也不要依赖本地缓存；推荐先rm -rf vendor && composer clear-cache再重装 - Docker 镜像中校验时机很重要：必须在
COPY vendor/到最终镜像层后、ENTRYPOINT前执行verify-checksums，否则运行时文件可能已被挂载卷覆盖
最易被忽略的是：这个校验只认 composer.lock 里明确记录的 dist.sha256，而它只对 dist 包有效；如果你用了 "type": "package" 或 path 源，这部分包完全不在校验范围内——得靠代码扫描或人工审计补位。
