composer强制启用sha-384校验以保障供应链完整性，匹配失败即拒绝安装；checksum mismatch表明信任链断裂而非网络问题，须通过手动hash比对定位源；禁用校验等于主动放弃零信任防线。
Composer 默认启用 SHA-256/SHA-384 校验，不是可选功能，而是强制安全边界——只要 composer.lock 里写了 checksum，安装时就一定会校验；跳过它等于主动关闭供应链完整性保护。
为什么 SHA-384 被选为默认强校验算法
SHA-384 是 Composer 2.2+ 的默认校验算法（替代旧版 SHA-256），原因很实际：
- 抗长度扩展攻击能力更强，比 SHA-256 更难被构造碰撞
- 与 TLS 1.3 和 Let's Encrypt 证书链使用的哈希强度对齐，避免“加密强、校验弱”的断层
- Packagist.org 所有 dist 包元数据均附带
sha384字段，且不提供降级 fallback
注意：composer install 不会尝试用 SHA-256 去匹配一个标为 sha384 的条目——匹配失败直接报 Checksum mismatch，不重试、不提示、不降级。
checksum mismatch 错误的真正根源不是网络，而是信任链断裂
这个错误不是“下载失败”，而是 Composer 明确拒绝加载一个无法验证来源一致性的包。常见真实场景包括：
- 私有仓库返回的 dist URL 指向未同步的旧构建，但
composer.lock仍记录新 checksum - 镜像源（如阿里云）元数据已更新，但缓存包体未刷新，导致 body hash 不匹配
- CI 环境中代理或构建工具（如 Docker buildkit）修改了 HTTP 响应体（例如注入 header、重编码 gzip 流）
- 本地
repositories配置了type: "package"，但手动写的dist.shasum字段抄错了位数（SHA-384 是 96 字符 hex，不是 64）
别急着删 vendor——先运行 composer diagnose，重点看 “Checking composer.json” 和 “Checking platform settings” 下是否提示 secure-http 被禁用，那说明 HTTPS 被绕过，校验本身已不可信。
如何验证 checksum 是否真被篡改，而非配置漂移
手动比对是最可靠方式，三步定位问题源头：
- 从
composer.lock中找到出错包的dist.shasum值（96 字符）和dist.url - 用
curl -L -s [url] | sha384sum（Linux/macOS）或certutil -hashfile [file] SHA384（Windows）计算实际文件 hash - 若两者不等，再检查该
dist.url是否来自预期源：composer config --list | grep repos，确认没被composer config repo.packagist临时覆盖
特别注意：如果 dist.url 是 https://api.github.com/... 类路径，说明走的是 GitHub Packages 或 VCS 模式，此时校验值由 GitHub API 动态生成，不受 Packagist 控制——必须确保你配置的 github-oauth token 有效且权限足够。
零信任下不该做的三件事
在生产环境或 CI 流水线中，以下操作等于主动放弃校验防线：
- 设置
COMPOSER_DISABLE_CHECKSUM_VERIFY=1—— 该变量已在 Composer 2.4+ 标记为 deprecated，且会同时禁用secure-http强制要求 - 用
composer update --no-scripts --no-plugins绕过校验 —— 这些 flag 完全不影响 checksum 验证逻辑 - 在
composer.json中写"minimum-stability": "dev"并依赖dev-main—— 此类分支无固定 checksum，每次构建都可能拉取不同代码
真正的零信任实践，是让校验失败成为构建流水线的硬性失败点，而不是设法绕过它。哪怕只是临时跳过，也意味着你接受了“依赖包内容不可信”这一前提——而这不是调试问题，是承认防线已被突破。
