Composer怎么验证文件哈希_Composer完整性校验机制说明【安全】

composer 默认启用哈希校验，install/update 时自动比对 lock 中 dist.sha256（或 sha1）与缓存 zip 文件的实际哈希值，仅限 dist 安装；不匹配时报“invalid archive signature: sha256 mismatch”等错误。

Composer install/update 时如何触发哈希校验

Composer 默认就开启完整性校验，不需要额外配置。只要 composer.lock 文件存在且内容完整，每次 composer install 或 composer update 都会自动比对包的 dist.sha256（或 sha1）与本地下载文件的实际哈希值。

关键点在于：校验只发生在从 dist（zip/tar 包）安装时，而非从 source（git clone）安装；如果你看到 Installing foo/bar (1.2.3) 后没报错，说明哈希已通过。

• 若 lock 文件缺失或被篡改，Composer 会重新生成，此时跳过历史哈希验证（但新生成的 dist 哈希仍会被记录）
• 运行 composer install --no-scripts --no-plugins 不影响哈希校验，它照常执行
• 使用 COMPOSER_DISABLE_NETWORK=1 时，若本地 vendor 已存在且 lock 未变，校验可能被跳过——这不是 bug，是离线模式下的行为妥协

怎么手动验证某个包的哈希是否匹配

没有内置命令一键重算并比对所有包，但可以定位单个包快速验证：

• 查 composer.lock 中该包的 dist.sha256 字段（例如 "dist": {"sha256": "a1b2c3..."}）
• 进 vendor/foo/bar/ 目录，找到实际解压来源（通常在 composer/installed.json 或临时缓存里），但更直接的是：用 shasum -a 256 vendor/foo/bar/.git/.../archive.zip —— 不，别这么干；正确路径是 Composer 缓存目录：~/.composer/cache/files/foo/bar/abc123.zip
• 执行 shasum -a 256 ~/.composer/cache/files/foo/bar/abc123.zip，结果应与 lock 中一致

注意：缓存 zip 文件名里的 hash（如 abc123）不是内容哈希，只是 Composer 内部 key，不能拿来比对。

哈希不匹配时 Composer 报什么错

典型错误信息是：Invalid archive signature: sha256 mismatch for ... 或更短的 Signature Error for ...。

• 这个错误一定出现在下载完成、解压前，Composer 拒绝继续安装
• 常见诱因：中间人篡改、CDN 缓存污染、本地缓存损坏（比如磁盘静默错误）、lock 文件被手动编辑过
• 不要删 vendor/ 就重试——先清缓存：composer clear-cache，否则可能复用坏 zip
• 如果仅个别包失败，可临时用 composer install --ignore-platform-reqs 绕过？不行，这参数不影响哈希校验

为什么有些包没写 sha256，只写了 sha1

这是历史兼容性选择。Packagist 早期只支持 sha1，后来加了 sha256 并优先使用；但老版本 Composer（sha1。

• Composer 会按顺序尝试 sha256 → sha1 → （极少数）md5，只要有一个匹配即通过
• sha1 理论上不够安全，但实际攻击成本高；真正风险不在哈希算法本身，而在你是否信任 packagist.org 或私有 repo 的签名机制
• 如果你用的是自建 Satis/Hydra，确保生成 lock 时启用了 archive-format 和对应哈希字段，否则下游用户会降级到无校验 fallback

哈希校验本身很轻量，但依赖 lock 文件的完整性——一旦有人绕过 lock 直接改 composer.json 再 run update，旧哈希记录就作废了。这点容易被忽略。