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、svg10 MB视频mp4、mov、webm100 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 会在有文件成功上传时坚持把改写后的正文写进目标资源避免出现“文件已上传但正文没有引用”的孤儿资源。服务端返回错误时的提示信息404could not upload file: attaching files requires write access to the repository端点对无写权限的 token 返回 404 而不是 403不要按状态码误判为“资源不存在”422could not upload file: 服务端返回的 message429could 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.goMarkdown 引用改写逻辑internal/attachments/references.go、internal/attachments/attach.go【免费下载链接】cliGitHub’s official command line tool项目地址: https://gitcode.com/GitHub_Trending/cli/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考