Homebrew 安装 cask 报 SHA-256 校验和不匹配怎么处理？
【免费下载链接】brew🍺 The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brew
在 macOS 上运行brew install --cask <cask>时，Homebrew 会校验下载文件与 cask 中记录的sha256是否一致。如果两者不一致，安装就会失败并提示校验和不匹配。本文给出一条完整处理路径：先排除本地缓存文件损坏，再判断是 cask 元数据过时还是供应商替换了下载文件，最后按文档给出的方式提交更新，而不是绕过校验。
先明白：这个报错本身是保护机制
cask 和 formula 一样使用 SHA-256 校验下载文件，Homebrew 会拒绝安装内容不匹配的文件（见 Checksum Requirements）。不匹配可能对应三种情况：
- 本地缓存的下载文件损坏；
- cask 记录的版本已过时，供应商发布了新版本或新 URL；
- 供应商在未改版本号的情况下替换了下载文件，这甚至可能是上游被入侵或供应链攻击的信号。
所以文档给出的原则是：不要绕过校验，而是查明哪个文件变了、按情况处理。
第一步：清掉出错的那个缓存文件，重试一次
按 Common Issues 中 "A cask checksum does not match" 一节的做法：
先完整读完报错，其中指明了出错的是哪个已下载文件。
定位缓存位置：
brew --cache该命令显示 Homebrew 的下载缓存目录，macOS 上通常是
~/Library/Caches/Homebrew（可用环境变量HOMEBREW_CACHE自定义）。若想看该 cask 具体的缓存文件：brew --cache myapp将
myapp替换成你安装的 cask 名称，输出即该 cask 的缓存文件/目录路径。只删除报错对应的那一个缓存文件，不要清空整个缓存目录——目录里可能还有已安装的其他软件对应的下载。
重新执行安装：
brew install --cask myapp
也可以用brew fetch --force myapp达到"删掉旧缓存并重新下载"的效果：--force会删除之前缓存的版本后重新 fetch，且fetch会打印下载文件的 SHA-256 校验值。
判断下一步：
- 如果这次安装成功，说明之前的缓存文件损坏，问题结束；
- 如果再次报校验和不匹配，且显示的校验值与第一次相同，说明不是本地缓存问题，进入第二步。
第二步：brew info对比供应商当前发布
仍然失败时，按文档做法对比 cask 记录与供应商现状：
brew info myapp brew home myappbrew info myapp显示该 cask 当前记录的版本、url和sha256；brew home myapp打开该 cask 的供应商首页，确认供应商现在实际提供的是哪个版本、哪个下载地址。
对号入座：
| 现象 | 文档给出的判断 | 处理方式 |
|---|---|---|
| 供应商已发布新版本或新 URL | cask 过时 | 提交 cask 更新，附上供应商当前版本与下载作为证据 |
| 版本号没变，但下载文件的 SHA-256 变了 | 供应商原地替换了已发布的下载 | 先按"重打标签的 cask"处理（见下文），不要直接改校验和 |
关于第二种情况，homebrew-cask 维护者指南 指出：如果校验和变化没有伴随版本号变化，应把它当作潜在的上游入侵或供应链攻击，而不是普通更新。应通过供应商的官方联系页、公开 issue 等渠道确认变更原因，并等待供应商确认后再更新校验和。
另外，如果失败不是持续性的，也可以先按 Troubleshooting 的检查清单走一遍：运行两次brew update，再运行brew doctor并处理与本次失败相关的告警，然后重试原安装命令。
需要更新校验和时怎么做
当确认是版本更新或供应商官方替换后，可以核对新文件的校验值：
brew fetch myappbrew fetch下载 cask 的文件并打印其 SHA-256 校验值。也可以对已下载的文件手动计算：
shasum -a 256 /path/to/downloaded-file/path/to/downloaded-file替换为你的下载文件实际路径（即报错信息中指出的那个文件，或brew --cache myapp给出的路径）。
拿到正确的新url和sha256后，向homebrew/cask仓库提交更新 PR，并附上供应商当前版本与下载的证据。文档明确要求：不要绕过校验，也不要在供应商未确认替换属意的情况下直接提交只改校验和的更新。
边界与限制
- 不要用
sha256 :no_check关闭校验来"解决"不匹配。Cask Cookbook 中:no_check仅用于上游配置导致无法计算校验和的场景（例如 URL 在各版本间不变），而不是用来绕过校验失败。 - 本地修改 cask 文件不会进入 Homebrew 的官方更新流程；元数据修复的正确路径是提交更新 PR，在合并后重新
brew install --cask myapp验证。 - 如果供应商的下载链接本身打不开，那属于"cask 下载失败"而不是校验和不匹配，应先测试供应商的下载链接再判断是网络问题还是链接失效（同样见 Common Issues）。
【免费下载链接】brew🍺 The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brew
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
