GitHub CLI gh --attach 上傳圖片與影片：Issue、PR、留言教學

—attach 支援哪些指令#

目前可在這些指令使用：

—attach 可以重複指定。它接受本機檔案路徑，也可以在路徑後用 # 加上替代文字，例如 ./artifacts/login.png#登入錯誤畫面。影片不使用替代文字語法。

先確認 CLI 版本與登入狀態#

先在執行腳本的機器上檢查：

1
gh version
2
gh auth status

版本低於 2.99.0 時，先依 GitHub CLI 官方安裝文件 更新，再重開 shell 或確認 PATH 指向新版本。gh auth status 只能確認目前的登入身分；實際上傳時，該身分還要對 repository 具有必要的寫入權限。

GitHub CLI 的驗證可以來自 gh auth login 建立的 OAuth token 或 classic personal access token。不要把 token 寫進腳本、Issue body 或 CI log；若在 CI 執行，應使用平台提供的 secret 注入方式並檢查 log 遮罩。

建立帶截圖與影片的 Issue#

以下範例會建立一個登入錯誤回報，附上一張截圖和一段重現影片：

1
gh issue create \
2
  --repo OWNER/REPO \
3
  --title "登入後畫面空白" \
4
  --body "請先查看附加的截圖與重現影片。" \
5
  --attach './artifacts/login.png#登入錯誤畫面' \
6
  --attach './artifacts/reproduce.mp4'

—attach 會先上傳檔案，再把產生的 GitHub media reference 放進 body。因為檔案路徑會交給 shell 解析，包含空白或 # 的路徑應加引號；若要使用 # 指定替代文字，應確認它位於路徑尾端，而且不會和檔名本身混淆。

對既有 Issue 留言的用法相同：

1
gh issue comment 123 \
2
  --repo OWNER/REPO \
3
  --body "這是最新一次測試的錯誤畫面。" \
4
  --attach './artifacts/login.png#最新錯誤畫面'

Pull Request 的建立、編輯和留言也接受相同的旗標。例如在 code review 腳本中附上失敗測試的影片：

1
gh pr comment 456 \
2
  --repo OWNER/REPO \
3
  --body "CI 失敗時的重現步驟如下。" \
4
  --attach './artifacts/ci-failure.webm'

如果只想讓腳本負責附件，不要在命令列放很長的 body，可以改用 —body-file，讓文字和附件在同一個可審查的檔案中管理。

既有 Markdown 圖片 reference 會被重寫#

GitHub CLI 的這項功能不只會附加新檔案。若 body 裡已經有指向本機檔案的 Markdown image reference，且同一個檔案也透過 —attach 指定，CLI 會把原本的 reference 改成上傳後的 GitHub media reference。

例如 report.md：

1
## 登入錯誤
2

3
![登入畫面](./login.png)
4

5
請在 Safari 重新整理後觀察。

建立 Issue 時：

1
gh issue create \
2
  --repo OWNER/REPO \
3
  --title "Safari 登入問題" \
4
  --body-file ./report.md \
5
  --attach './login.png#登入畫面'

這個行為適合保留報告原本的 Markdown 結構。若檔案沒有在 body 中被引用，GitHub CLI 會把附件 reference 加到 body 後面；因此正式腳本應明確決定哪些檔案是 body 內容的一部分，哪些只是額外證據，避免 Issue 底部堆積沒有說明的 media。

檔案格式與大小限制#

依 GitHub 文件，目前可附加：

• 圖片：PNG、JPEG、GIF、WebP、SVG。
• 影片：MP4、MOV、WebM。

大小限制沿用 GitHub 網頁上傳規則：圖片與 GIF 上限為 10 MB；影片在 Free plan 上限為 10 MB，付費方案上限為 100 MB。GitHub Enterprise Server 目前不支援這個 CLI media attachment 流程。

在腳本中可以先擋掉過大的檔案，讓錯誤在上傳前發生：

1
test -f ./artifacts/login.png || {
2
  echo "找不到截圖" >&2
3
  exit 1
4
}
5

6
if [ "$(wc -c < ./artifacts/login.png)" -gt 10485760 ]; then
7
  echo "截圖超過 10 MB" >&2
8
  exit 1
9
fi

這段只示範圖片的 10 MB 檢查；影片要依 repository 所屬方案選擇 10 MB 或 100 MB 的上限。更重要的是不要為了繞過限制，把原始影片不加說明地壓縮或轉檔；應在 body 裡記下取樣方式、時間點和重現命令。

把附件接到本機診斷流程#

一個實用的 CLI 流程可以分成四段：

1. 測試命令把 screenshot、console log 或重現影片寫入暫存目錄。
2. 腳本確認檔案存在、大小和副檔名符合規則。
3. gh issue create 或 gh pr comment 用 —body-file 加上多個 —attach。
4. 腳本記錄產生的 Issue／PR URL，但不記錄 OAuth token 或附件內容。

若診斷內容本身包含秘密、個人資料或 production URL，先做遮罩再上傳。GitHub media 一旦進入 Issue、PR 或 comment，就會成為 repository 協作紀錄；—attach 解決的是上傳流程，不會替你決定資料是否適合公開給該 repository 的讀者。

如果你也用 GitHub CLI 管理 Codespaces 網路連接，可以參考 Codespaces port forwarding 的安全檢查；那篇處理的是 port permission，不是 media attachment，但兩者都應放在同一份 CLI 權限與 log policy 中檢查。

一份可驗證的上線清單#

正式把功能放進 CI 或 bug-report script 前，建議用測試 repository 執行：

• gh version 確認至少 2.99.0。
• gh auth status 確認使用正確帳號或 CI token。
• 用一張小於 10 MB 的 PNG 和一個短 MP4／WebM 做成功測試。
• 測試 —attach 的多次指定，以及路徑後加 #alt text。
• 測試 —body-file 中已存在的本機 Markdown image reference 是否被重寫。
• 測試一個未被 body 引用的附件，確認它會追加到 body。
• 用 gh issue view NUMBER —web 或直接開啟 URL，確認圖片、影片和替代文字。
• 用一個沒有寫入權限的 token 做失敗測試，確認腳本不會把敏感 body 重試到錯誤目的地。

結論：把媒體當成可審查的回報輸入#

gh —attach 讓 Issue、PR 和留言可以在同一個 CLI 工作流中完成文字、圖片與影片的提交。先升級到 2.99.0，再用 —body-file 管理可審查的說明，用可重複的 —attach 指定證據，並在腳本中檢查格式、大小和權限。最後別忘記 media 會留在協作紀錄中：上傳前的遮罩和資料分類仍然是團隊責任。

常見問題#