如何用 GitHub CLI 的 gh release download 按 tag 和 pattern 下载指定 Release 资产？

如何用 GitHub CLI 的 gh release download 按 tag 和 pattern 下载指定 Release 资产？

【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli

用 GitHub CLI（gh）管理仓库时，经常需要从某个 GitHub Release 中取出指定的资产文件，而不是把整个 Release 的所有附件都拉下来。gh release download就是完成这件事的命令：它可以按 release tag 定位到指定版本，再用 glob 形式的--pattern过滤出想要的那几个资产文件，下载到你指定的目录。本文基于 命令实现 与验收测试整理出完整的参数用法、冲突限制和验证方式。前提是你已安装gh并能访问目标仓库，安装方式可参考 README 中 macOS / Linux / Windows 的预编译二进制说明。

命令形式：tag 可选，但决定要不要写 pattern

命令的完整形式为：

gh release download [<tag>]

规则来自命令源码中的参数校验：

• 提供 tag（如v1.2.3，请替换为你仓库中实际的 release tag）时，下载该 Release 的资产；不加 pattern 就下载该 Release 的全部资产。
• 不提供 tag 时，gh从项目的最新 Release下载，此时--pattern或--archive二者必填其一，否则报错：

`--pattern` or `--archive` is required when downloading the latest release

按 tag 下载全部资产

主路径是最短命令——在任意目录（或克隆好的仓库目录）下直接指定 tag：

gh release download v1.2.3

默认下载目录由-D, --dir控制，默认值为当前目录.。如果要在其他仓库中下载而不依赖当前 git 目录，可加-R, --repo指向目标仓库（release命令组通过cmdutil.EnableRepoOverride启用了该覆盖）。

仓库自带的验收测试展示的正是这条主路径：先gh release upload v1.2.3 ../asset.txt上传资产，再执行gh release download v1.2.3，随后用exists asset.txt确认文件已出现在当前目录（见 release-upload-download.txtar）。

用 --pattern 按文件名过滤资产

-p, --pattern是 glob 模式，只下载与模式匹配的资产；模式与资产的完整文件名做 glob 匹配，可以重复传多次，多个模式之间是"任一匹配即下载"的关系：

# 只下载 tar 包 $ gh release download v1.2.3 -p '*.tgz' # 同时匹配 Debian 与 RPM 包 $ gh release download -p '*.deb' -p '*.rpm'

第二条不带 tag，因此作用于最新 Release，满足"无 tag 必须带 pattern 或 archive"的校验。结合-D可以指定落地目录，目录不存在时会自动创建（实现中通过MkdirAll保证）：

$ gh release download v1.2.3 -p 'windows-*.zip' -D tmp/assets

pattern 匹配不上时，命令会给出明确的错误而不是静默成功：

• Release 有资产但无匹配项：no assets match the file pattern
• Release 本身没有任何资产：no assets to download

出现这两类报错时，先核对资产文件名（例如用gh release view v1.2.3查看），再修正 pattern。

可选分支：下载源码归档而不是上传的资产

如果目标是该 tag 对应的源码归档而非 Release 上手动上传的附件，用-A, --archive：

$ gh release download v1.2.3 --archive=zip

取值只允许zip或tar.gz，其他值报错：the value for--archivemust be one of "zip" or "tar.gz"。注意--archive与--pattern互斥，同时给出会报specify only one of '--pattern' or '--archive'。归档文件的保存名来自服务端响应头，验收测试中--archive=zip的产物形如myrepo-1.2.3.zip（文档示例）。如果目标 Release 是 draft（草稿），归档 URL 不存在，报错会提示：

release "patch-36" with tag "v1.2.3", does not have a "tar.gz" archive asset. Most likely, this is because it is a draft.

（以上为 download_test.go 中记录的实际报错示例。）

控制落盘位置：--output、--clobber 与 --skip-existing

几个标志的冲突规则在执行前就会校验，报错信息可以直接当作参数约束来记：

• -O, --output FILE：把单个资产直接写入指定文件，适合 pattern 恰好只命中一个资产的场景；若匹配到多个资产，报错unable to write more than one asset with--output, got N assets。
• -O -表示写标准输出。写 stdout 时有安全限制：在终端（TTY）下拒绝直接输出二进制内容；资产包含终端转义序列时会报the asset contains terminal escape sequences; use--outputto save it to a file, or pass --allow-escape-sequences to output it anyway。确需原样输出时加--allow-escape-sequences。
• 目标文件已存在时的默认行为是报错停止：already exists (use--clobberto overwrite file or--skip-existingto skip file)。--clobber覆盖同名文件，--skip-existing跳过同名文件继续下载其余资产。

结果验证与常见报错对照

验证方式与仓库验收测试一致：命令正常退出后，检查目标目录（--dir指定目录或当前目录）下是否出现预期的资产文件。失败时按以下报错定位，这些文案均出自实现代码：

• `--pattern` or `--archive` is required when downloading the latest release—— 未给 tag 且未给 pattern/archive，补上参数或显式写 tag。
• no assets match the file pattern—— pattern 与资产名不匹配，用gh release view <tag>核对真实文件名。
• no assets to download—— 该 Release 没有上传任何资产。
• already exists (...)—— 目录中已有同名文件，按需求选--clobber或--skip-existing。
• 在 Windows 上，若 Release 含CON、NUL等保留文件名，会报unable to download release due to asset with reserved filename "CON.tgz"，整个下载中止，需要先在 Release 端处理该资产。

更多参数与行为的边界情况，可进一步查看 参数解析测试 与 release 命令组入口。

【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli