GitHub CLI 如何用 --attach 在 Issue 或 PR 中上传本地图片与视频？
【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli
在排查问题时，你经常需要把本地截图或录屏直接放进 GitHub Issue / PR 的正文，而不是先手动传到别的图床再贴链接。GitHub CLI 的--attach标志可以完成这件事：它在创建或评论 Issue、PR 时把本地图片/视频上传到 GitHub，并把正文中引用的本地路径改写成上传后的远程资源地址；正文没有引用到的文件会被自动追加到正文末尾。
适用前提（以下各条不满足时命令会在打开编辑器之前就报错）：
- 登录凭证是 OAuth、personal access token 或 fine-grained PAT，其他凭证类型会报
unsupported authentication type； - 你对目标仓库有写权限（WRITE / MAINTAIN / ADMIN 之一），只读权限会报
attaching files requires write access to the repository； - 目标是 GitHub.com 上的仓库。
--attach在 GitHub Enterprise Server 上不受支持，会报attaching files is not supported on GitHub Enterprise Server。
哪些命令支持 --attach
--attach注册在 Issue 与 PR 的创建、评论和编辑命令上，包括：
gh issue creategh issue commentgh issue editgh pr creategh pr comment
两个已知的不兼容组合：gh issue create使用--web时、gh pr create使用--dry-run时都不支持--attach，同时传会直接报错。
基本用法
--attach可重复使用，单个文件的基本写法是：
# 附带一张截图，# 后面是图片的 alt 文本 $ gh issue comment 12 --attach './login.png#The login error state' # 重复该标志一次附带多个文件 $ gh issue comment 12 --attach ./before.png --attach ./after.png创建 Issue 或 PR 时同理：
$ gh issue create --attach './login.png#The login error state' $ gh issue create --attach ./before.png --attach ./after.png几个使用规则：
- 格式为
<file>#<image alt text>，其中 alt 文本只适用于图片。不写#部分时，图片以文件名作为 alt 文本（去掉扩展名、剩余的点号替换为空格）；视频没有 alt 文本，写成视频会报cannot set alt text on video。 - 每条命令最多接受 50 个
--attach值，超出会报--attach` accepts at most 50 values per command。 - 空路径（如
--attach ""）报cannot attach an empty path; --attach needs a file path；-这类标准输入不被接受。 - 同一个文件用两种写法传两次会报
attached files must be unique。 gh issue edit不带 body 相关标志时，issue 保留已有正文，附件追加到正文末尾。gh issue comment/gh pr comment在没有通过标志提供正文和附件时，会交互式提示输入评论内容。
支持的文件类型与大小限制
--attach按扩展名判断文件类型，接受的类型如下（不区分大小写）：
| 类型 | 扩展名 | 客户端大小上限 |
|---|---|---|
| 图片 | png、jpg、jpeg、gif、webp、svg | 10 MB |
| 视频 | mp4、mov、webm | 100 MB |
超出上限会报...: images must be at most 10 MB这类错误。注意视频一栏的 100 MB 只是客户端的宽松边界：真实限制取决于账户套餐，gh 在发请求前无法得知，所以更小的请求也可能被服务端拒绝。
其他在上传前就会被拒绝的情况：
- 文件不存在，或路径是目录（
... is a directory）； - 不是普通文件（如命名管道，
... is not a regular file）； - 零字节文件（
... is empty，空文件上传后也无法正常渲染）； - 扩展名不在支持列表中，报
... is not a supported file type (supported: png, jpg, jpeg, gif, webp, svg, mp4, mov, webm)。
正文中的 Markdown 如何被改写
上传成功后，CLI 会处理正文里的 Markdown 引用：
- 如果正文已经引用了某个附件文件，例如
alt，该引用会被改写成上传后返回的资源 URL，原来写的 alt 文本保持不变； - 正文没有引用到的附件会被追加到正文（或评论）末尾：图片以
alt的形式追加；视频没有 Markdown 的播放器语法，GitHub 只会在一个段落的完整内容是一个裸 URL 时把它渲染为播放器，所以视频以裸 URL 单独成段追加； - 代码围栏（``` fence）和行内代码（
`跨度）里的路径不会被改写； - 参考式链接（reference-style link）会在其定义行处改写，一次编辑覆盖该标签的所有使用处；
- 视频不能用参考式图片的方式内嵌，会报
cannot embed a video as a reference-style image: ...。
路径匹配按绝对路径进行，因此正文里写的相对路径（如./login.png）也能对上。
上传失败与不可撤销
上传按--attach给出的顺序进行，遇到第一个失败就停止，后面的文件不再尝试。即使部分成功、部分失败，Issue / PR 仍会用上传成功的那部分创建或更新：比如gh issue edit的帮助文案明确说明，此时命令以非零状态退出，但被编辑的 issue URL 仍会打印到 stdout。
需要特别注意的一点：上传无法撤销，也没有删除已上传资源的接口。所以 CLI 会在有文件成功上传时坚持把改写后的正文写进目标资源，避免出现“文件已上传但正文没有引用”的孤儿资源。
服务端返回错误时的提示信息：
- 404：
could not upload <file>: attaching files requires write access to the repository（端点对无写权限的 token 返回 404 而不是 403，不要按状态码误判为“资源不存在”）； - 422：
could not upload <file>: <服务端返回的 message>； - 429：
could not upload <file>: rate limited; retry after N seconds（无 Retry-After 头时为rate limited; wait and try again）。
结果验证
运行命令后按以下两点确认：
- 命令打印出新建/更新后的 Issue 或 PR URL（部分失败时退出码非零，但 URL 仍会输出），打开该 URL 检查正文；
- 正文中的本地路径引用已变成远程资源地址。测试代码里对上传端点返回的示例 URL 形如
https://github.com/user-attachments/assets/AAA（测试桩数据，仅展示 URL 形态），实际地址以端点返回为准；没有引用的附件应出现在正文末尾。
如果验证时发现正文仍是本地路径，说明该引用没有被改写——先检查正文里的路径写法是否与--attach传入的路径指向同一文件（按绝对路径匹配），再确认该路径没有写在代码围栏或行内代码里。
相关源码位置
- 标志解析与校验：internal/attachments/flags.go
- 文件类型、大小限制与错误信息：internal/attachments/userasset.go
- 上传请求、凭证与权限检查：internal/attachments/client.go
- Markdown 引用改写逻辑：internal/attachments/references.go、internal/attachments/attach.go
【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
