GitHub Release 资产校验要先把证据层级排好，不必把每个工具都跑一遍。Clash Verge Rev、Mihomo、sing-box 这类客户端或 core 升级前，最小记录单应该包含 owner/repo、release tag、asset 文件名、本地 SHA256 和验证命令输出。

先看三种证据分别回答什么？

证据回答的问题常见材料失败时先停在哪里
checksum本地文件和发布方给出的摘要是否一致checksums.txt、SHA256SUMS、.sha256重新下载同一 tag 的同名文件
GitHub Release integrity这个 release 和本地 asset 是否匹配gh release verify、gh release verify-asset确认是否在官方仓库和正确 tag
GitHub artifact attestations文件是否有 GitHub 记录的构建来源gh attestation verify判断项目是否真的发布了 attestation
SLSA provenance源码、构建器、workflow、subject digest 是否符合预期.intoto.jsonl、Sigstore bundle核对 source-uri、source-tag、builder
cosign / slsa-verifier签名、透明日志和 provenance 字段是否可验证cosign verify-blob-attestation、slsa-verifier verify-artifact不混用其它项目的参数

checksum 是第一层，因为它便宜、快、能发现下载损坏和错包。provenance 是更高一层，它关心这个文件由哪个源码和构建流程产生，而不是只看文件有没有变。

校验前要记录哪些字段？

先别急着运行命令。打开 Release 页面后，写下这 5 个字段：

字段示例为什么要记
仓库MetaCubeX/mihomo避免进到同名 fork
tagv1.19.0防止用旧清单校验新文件
assetmihomo-linux-amd64-v1.19.0.gz防止架构、系统或压缩格式拿错
下载时间2026-05-24 15:30便于排查缓存和重新上传
本机路径~/Downloads/client.gz后续命令都指向同一个文件

这一步对 Windows、macOS、Linux 都一样。差别只在计算 SHA256 的命令，不在判断逻辑。

checksum 先做哪一步？

Windows PowerShell：

Get-FileHash .\client.zip -Algorithm SHA256

macOS：

shasum -a 256 ./client.zip

Linux：

sha256sum ./client.zip

把输出里的 64 位十六进制字符串，和同一 Release 页面里的 checksums.txt、SHA256SUMS 或发布说明逐字比对。只看前 8 位不够，尤其是团队分发客户端或 core 时，必须保留完整摘要。

如果 checksum 不一致，先停在下载环节。常见原因是浏览器留下了 client (1).zip、镜像缓存旧文件、下错架构、把压缩包解开后才计算哈希，或者拿了另一个 tag 的校验清单。

GitHub Release 自带校验怎么跑？

GitHub CLI 对 immutable release 和本地 Release asset 提供了命令入口。进入仓库目录，或显式加 -R owner/repo：

gh release verify v1.2.3 -R owner/repo
gh release verify-asset v1.2.3 ./client.zip -R owner/repo

这里要注意一个边界：GitHub 官方文档说明，release 的 source code zip 或 tarball 是下载请求触发生成的文件，不能用 gh release verify-asset 当作普通上传资产来校验。代理客户端用户平时要校验的是 .exe、.msi、.dmg、.apk、.zip、.tar.gz、.gz 这类项目发布者上传的资产。

如果 verify-asset 失败，先看本地文件名、tag 和仓库是否一致。不要在失败后立刻修改 Clash Verge Rev、Mihomo 或 sing-box 的配置文件，否则会把下载问题带进客户端排错。

GitHub attestation 怎么验证本地文件？

项目如果启用了 GitHub artifact attestations，可以用 GitHub CLI 直接验证二进制文件：

gh attestation verify ./client.zip -R owner/repo

这条命令验证的是本地文件和仓库发布的 attestation 是否匹配。它不是 checksum 的替代品，而是补充构建来源证据：文件摘要要对，仓库关系也要对。

如果命令提示没有 attestation，先把结论写成「项目未提供 attestation」。这不是文件一定有问题，也不代表项目不安全；它只说明你不能用 GitHub attestation 这条链路证明构建来源。

SLSA provenance 要看哪几个字段？

SLSA provenance 的价值在于把「文件从哪里来」拆成可检查字段。拿到 .intoto.jsonl 或项目给出的 provenance 文件后，重点看这些项：

字段你要确认什么错误信号
subject.digest.sha256是否覆盖本地文件摘要subject 里没有你的 asset
builder.id是否是项目声明的构建器构建器来自陌生项目
source-uri是否指向官方仓库指向同名 fork 或临时仓库
source-tag是否等于当前 release tagtag 对不上或为空
workflow ref是否来自项目发布 workflowworkflow 路径或 ref 异常

slsa-verifier 的典型形态是把本地文件、provenance 文件、源码仓库和 tag 放在同一条命令里：

slsa-verifier verify-artifact ./client.zip \
  --provenance-path ./client.zip.intoto.jsonl \
  --source-uri github.com/owner/repo \
  --source-tag v1.2.3

不要把 --source-uri 写成下载镜像地址。这里要填的是产生这个产物的源码仓库，不是你拉文件的传输入口。

cosign 和 slsa-verifier 什么时候用？

项目给什么材料，就用什么工具。Release 说明如果给的是 Sigstore bundle、证书 identity、OIDC issuer，就按 cosign 文档走；如果给的是 SLSA provenance 文件和 slsa-verifier 命令，就按 slsa-verifier 走。

cosign 验证 blob attestation 的常见形态：

cosign verify-blob-attestation \
  --bundle artifact.sigstore.json \
  --certificate-identity "https://github.com/owner/repo/.github/workflows/release.yml@refs/tags/v1.2.3" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  ./client.zip

上面只是命令形态，不能直接复制到任意项目。certificate-identity、workflow 路径、issuer、bundle 文件名都要以该项目 Release 说明为准。

失败时该怎么收口？

把失败分成 4 类，比反复重跑命令更快：

失败表现更可能原因下一步
SHA256 不一致下错 tag、文件损坏、镜像缓存旧包只重新下载同一官方 Release 的同名 asset
verify-asset 失败本地文件不是该 release asset核对 source code archive 和上传 asset 的区别
gh attestation verify 找不到记录项目未发布 attestation降级到 checksum、签名和官方仓库校验
SLSA provenance 字段对不上source-uri、source-tag 或 subject digest 错停用这份文件，等待维护者说明

只要进入第四类，就不要继续安装。对软路由、NAS 或多设备同步来说，先停用一个可疑文件，比后面排查 TUN、DNS、规则分流更省时间。

给客户端更新留一行记录

校验通过后，记录一行文本就够：

2026-05-24 | owner/repo | v1.2.3 | client-windows-amd64.zip | SHA256=... | checksum OK | gh attestation OK | source-tag OK

如果项目没有提供 attestation 或 provenance，也写清楚：

2026-05-24 | owner/repo | v1.2.3 | client.dmg | SHA256 OK | no GitHub attestation found | no SLSA provenance provided

半年后客户端无法启动时，这行记录可以先排除「下载文件变了」这件事。剩下的问题再回到 Clash Verge Rev、Mihomo、sing-box 的配置、权限、DNS 或系统服务日志里查。

相关阅读

FAQ

checksum、attestation 和 SLSA provenance 有什么区别？

checksum 证明本地文件内容是否等于某个摘要；attestation 证明文件和构建记录有关；SLSA provenance 进一步描述源码、构建器、workflow 和产物摘要。

GitHub Release 的 Source code zip 能用 verify-asset 校验吗？

不适合。GitHub 官方说明 source code zip 和 tarball 是请求下载时生成的资产，gh release verify-asset 主要用于发布者上传的 Release asset。

没有 artifact attestation 的项目还能下载吗？

可以，但要降级判断：至少确认官方仓库、release tag、文件名、SHA256 或签名材料。没有 attestation 只表示少了一层构建来源证据。

slsa-verifier 和 cosign 应该选哪一个？

项目给 in-toto SLSA provenance 文件时优先看 slsa-verifier 示例；项目给 Sigstore bundle 或 cosign 命令时按 cosign 参数验证。不要跨项目套命令。

验证失败后能继续安装客户端吗？

不建议。先排除 tag、文件名、checksum 文件、bundle 和 source-tag 是否混用；仍失败时停用这份下载文件，回到官方仓库等待说明。