GitHub CLI 新增媒体上传后怎么在工单中添加图片

GitHub CLI 最近补上了一个很实用的协作能力：升级到 gh v2.99.0 后，可以用可重复的 --attach 把本地图片或视频上传到 Issue、Pull Request 或评论，并让它直接出现在 Markdown 内容里。以前遇到界面缺陷、渲染结果或报错截图，往往要离开命令行打开浏览器；现在可以在提交工单的同一条命令中带上媒体文件。

最短用法是 gh issue comment ISSUE_NUMBER --body "复现结果见附件" --attach ./error.png。如果希望图片出现在正文中间，就在 body 文件里先写本地 Markdown 引用，再把同一个路径传给 --attach。

GitHub CLI 这次新增了什么

这次变化的关键不是多了一个“上传”按钮，而是媒体上传和内容写入被合并到一个命令模型中。--attach 可以用于 gh issue create、gh issue edit、gh issue comment、gh pr create、gh pr edit 和 gh pr comment。同一个文件不能重复附加，但不同文件可以多次传入。

如果正文没有引用附件，未被引用的文件会按参数顺序追加到文末；如果正文已经写了同一路径，CLI 会保留原来的 alt 文本并在原位置替换地址。这一点很适合脚本生成复现报告：正文结构由 body 文件控制，上传动作由参数控制。

把图片放进 Issue 的最短路径

先检查本机版本和认证状态。不要只看命令能否解析，真正上传还需要对目标仓库有写权限。

# 确认 CLI 版本，媒体附件要求 gh v2.99.0
gh --version
# 确认当前账号和可访问的仓库
gh auth status
# 把单张图片作为评论附件上传
gh issue comment 123 --body "复现截图已附上" --attach ./error.png

图片 alt 文本可以接在路径后的 # 之后，例如：

# # 后的内容只用于描述追加的图片
gh issue comment 123 --attach './error.png#登录页显示认证错误'

省略 alt 文本时，GitHub CLI 会退回使用文件名。对无障碍和后续检索来说，给截图写一句描述比保留 error-final-2.png 更有用。

需要把附件放在正文中间怎么办

将正文保存为 body.md，先写出本地文件引用：

复现步骤执行到第二步时出现空白区域：

![登录页的空白错误状态](./error.png)

期望结果是表单继续显示。

然后把 body 文件和相同的本地路径一起传入。路径必须对应同一个文件，CLI 才能原地替换：

# body.md 中的本地路径会被替换为 GitHub 上传地址
gh issue comment 123 \
  --body-file ./body.md \
  --attach ./error.png

如果要提交一份带前后对比的 PR，可以重复使用 --attach：

# 两个附件分别对应正文中的两个本地引用
gh pr create \
  --title "修复登录页空白状态" \
  --body-file ./pr-body.md \
  --attach ./before.png \
  --attach ./after.png

正文来自 --body、--body-file、标准输入还是编辑器，都不影响这种路径替换行为。

使用前要核对的权限与文件边界

官方文档把上传条件说得很明确：要对目标仓库有 push 权限，认证使用 GitHub CLI 已有的 OAuth token 或经典个人访问令牌。支持的媒体包括 PNG、JPEG、GIF、WebP、SVG、MP4、MOV 和 WebM。

团队脚本最好在提交前检查文件大小，并把 CLI 版本写进开发容器或 CI 镜像。这样失败时能区分“路径不存在、权限不足、文件超限”和“命令版本过旧”，而不是只看到一个上传失败。

常见问题

--attach 能用于普通评论吗？

可以，gh issue comment 和 gh pr comment 都在支持范围内，也可用于创建和编辑 Issue 或 PR。

没有仓库写权限还能上传吗？

不能。官方要求对要附加文件的仓库具有写权限；仅有读取权限的协作者需要改用有权限的账号或由有权限者提交。

为什么图片出现在文末而不是指定位置？

通常是 body 中没有写与 --attach 完全相同的本地路径。未被正文引用的附件会被追加到文末。

视频也支持 alt 文本吗？

不支持。路径后的 alt 文本适用于图片；视频附件不能用这种方式设置 alt 文本。

这项变化适合怎样的团队流程

对命令行报障、自动化 PR、编码代理和 CI 生成的复现报告来说，--attach 能减少浏览器切换，也让工单在第一次提交时就带着实际画面。落地时建议固定 gh 版本、在脚本中明确 body 文件和附件路径，并在失败日志里记录仓库、命令类型和文件大小。先把它用于开发仓库和低风险流程，确认权限与限制后，再接入更严格的自动化提交流程。

资料入口：GitHub Changelog 的功能公告 与 GitHub CLI 附件文档。