上傳並使用圖片與檔案

媒體庫是什麼

上傳的檔案存放於 Cloudflare R2 bucket，並由 https://jenksguo.pages.dev/media/… 提供服務。 支援：WebP、JPEG、PNG、GIF、AVIF 與 SVG 圖片，MP4 與 WebM 影片，以及 PDF——每個上限 25 MB。 實際檔案類型會從檔案本身讀取，因此即使重新命名，檔案也無法偽裝成圖片。

每個檔案都會獲得一個永久位址，例如：/media/2026/10/acme-workshop-3f9a1c2b7d.webp。最後一段 是檔案位元組的指紋，因此同一位址永遠不會指向不同內容，瀏覽器可以快取一年。再次以上傳 相同檔名與相同內容的檔案時，會重用既有副本。

檔案在上傳後即為公開，即使尚未被任何頁面使用也是如此。只上傳所有訪客皆可見的內容—— 切勿上傳含電話、身分證或私人文件的履歷等。

在主控台中

1. 開啟 https://admin.jenksguo.xyz/admin（Google 登入），並在上方列選擇 Media。
2. 將檔案拖曳到頁面上、貼上螢幕截圖，或點選 Upload。開啟 Optimise photos（預設）時， 照片會先在你的瀏覽器中縮至 2400 px 並轉換為 WebP——一張 6 MB 的手機照片通常會變成 300–600 KB。 iPhone 的 HEIC 照片在瀏覽器可讀取時會被轉換（Safari 可）。
3. 選取檔案以新增 alt text——用一句話描述圖片的內容。螢幕閱讀器與 Ask Jenks 助理會使用它。

接著可在 Content 編輯器中使用檔案：

• Cover image —— 在「Details」中選擇「Choose or upload a cover image」。它會顯示在條目頁面的最上方。
• Gallery —— 「Add photo or video」會新增顯示在正文旁的項目，每個都有替代文字與可選註解。
• Proof file —— 在 proof 列中，迴紋針會附加已上傳的 PDF（例如論文）。
• Inside the text —— 編輯器工具列中的圖片按鈕可插入圖片；你也可以直接拖曳或貼上圖片到文字中。 選取已插入的圖片可編輯其替代文字。

儲存條目會如常發佈變更。編輯器會拒絕儲存指向不存在 /media/… 檔案的內容。

從 CLI

jenks admin media upload ~/Pictures/acme-workshop.jpg --alt "Jenks running an AI workshop at Acme"
jenks admin media upload https://example.com/talk-poster.png     # the server fetches it
jenks admin media ls                                            # newest first, with "used by"
jenks admin media alt 2026/10/acme-workshop-3f9a1c2b7d.jpg "New alt text"
jenks admin media rm 2026/10/acme-workshop-3f9a1c2b7d.jpg

CLI 會按原樣上傳檔案（不進行縮放），因此請先以合適尺寸匯出大型相片。 然後在條目中參照印出的網址：

image: /media/2026/10/acme-workshop-3f9a1c2b7d.jpg
imageAlt: Jenks running an AI workshop at Acme
gallery:
  - src: /media/2026/10/acme-team-0c1d2e3f4a.webp
    alt: The Acme leadership team at the kick-off
    caption: Kick-off, October 2026

從 AI 代理（MCP）

管理用 MCP 伺服器提供 admin_upload_media、admin_list_media、admin_update_media 與 admin_delete_media。

• Local（jenks mcp --admin）：以 path 傳入你電腦上的檔案——本機伺服器會為代理讀取它。
• Remote（/mcp/admin）：以 url（要匯入的 https 位址）或 data（base64）搭配 filename 傳入。

向代理發出的典型請求：「Upload ~/Desktop/xero-talk.jpg with alt text 'Jenks speaking at Xerocon', then make it the cover image of xero-developer-evangelist.」

從 REST

curl -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -F file=@acme-workshop.jpg -F alt="Jenks running an AI workshop at Acme" \
  https://jenksguo.pages.dev/api/admin/media

對 /api/admin/media 的 GET、PATCH 與 DELETE 可列出、更新與刪除。請參閱 管理 API 參考。

安全刪除

刪除是永久的：與內容不同，檔案沒有 git 歷史。主控台與 API 會拒絕刪除仍被已發佈內容使用的檔案， 並顯示其使用位置。請先移除參照，或在可接受破圖的情況下強制刪除。

「used by」檢查會讀取此環境上次部署的內容。dev 與 production 共用同一個媒體庫（因此在 dev 預覽時 上傳的檔案，在你升版後仍可使用），所以僅由尚未升版的 dev 內容使用的檔案，可能在 production 主控台中 看起來未被使用。