上傳並使用圖片與檔案

什麼是媒體庫

上傳的檔案儲存在 Cloudflare R2 bucket 中，並從 https://jenksguo.xyz/media/… 提供服務。 支援：WebP、JPEG、PNG、GIF、AVIF 與 SVG 圖片，MP4 與 WebM 影片，以及 PDF——每個檔案上限 25 MB。 實際的檔案類型會從檔案本身讀取，因此僅改檔名無法偽裝成圖片。

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

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

在主控台中

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

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

• 封面圖片——於「Details」中選擇「Choose or upload a cover image」。它會顯示在條目頁頂部。
• 圖庫——「Add photo or video」可加入會顯示在內文旁的項目，每個都有 alt 文字與可選的說明文字。
• 佐證檔案——在 proof 列中，用回形針附加已上傳的 PDF（例如論文）。
• 文內圖片——編輯器工具列中的圖片按鈕可插入圖片；你也可以將圖片直接拖曳或貼入文字中。 選取已插入的圖片可編輯其 alt 文字。

儲存條目即如常發布變更。若內容指向不存在的 /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 會原樣上傳檔案（不會調整大小），因此請先將大型照片以合適尺寸匯出。 然後在條目中引用列印出的 url：

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。

• 本機（jenks mcp --admin）：傳入 path 及你電腦上的檔案——本機伺服器會為代理讀取它。
• 遠端（/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.xyz/api/admin/media

在 /api/admin/media 上以 GET、PATCH 與 DELETE 進行列表、更新與刪除。請參見 admin API reference。

安全刪除

刪除是永久性的：與內容不同，檔案沒有 git 歷史。主控台與 API 會拒絕刪除仍被已發布內容 使用的檔案，並顯示其使用位置。請先移除參照；若可接受圖片損壞，也可強制刪除。

「used by」檢查會讀取此環境上次部署的內容。dev 與 production 共享同一個媒體庫（因此在 dev 預覽時上傳的檔案，在你升級後仍能繼續運作），所以僅被未升級之 dev 內容使用的檔案， 在 production 主控台中可能會顯示為未使用。