E EmDash CMS Everything Guides, use cases, plugins, templates
繁體中文

媒體庫

本頁內容

媒體庫儲存可重複使用的圖片、文件、影片與音訊。編輯者可以一次上傳檔案，從內容欄位與 Portable Text 中選取它們，並查看哪些內容項目引用了本機媒體項目。

開啟媒體庫

在管理側邊欄中選取 Media。主庫包含尚未放入資料夾的資料夾與檔案。選取資料夾以瀏覽其檔案，或在網格檢視與清單檢視之間切換。

若網站有外部媒體提供方，每個提供方會顯示為另一個來源。提供方能力各不相同：某個來源可能支援瀏覽與選取，但不支援資料夾、本機圖片編輯或刪除。

上傳檔案

從庫中上傳

  1. 選取 Media，然後選取 Upload Files。

  2. 選取 Browse files 並選取一個或多個檔案。也可以將檔案拖到上傳區域或媒體庫上。

  3. 上傳進行時保持對話方塊開啟。每列會回報 Queued、Uploading、Complete 或 Upload failed。

  4. 對於失敗的檔案，選取其重試動作。您可以取消未完成的上傳、移除失敗列，或清除已完成列而不影響已完成的檔案。

  5. 當佇列中沒有未完成的上傳時，選取 Done。

檔案一新增就開始上傳。新的本機檔案會進入主庫，即使上傳前開啟的是另一個資料夾。

在編輯內容時上傳

圖片、檔案、圖庫與 Portable Text 圖片欄位使用媒體選擇器。開啟欄位，選取 Upload files，然後選取或放下檔案。完成的上傳會成為目前選取的一部分；失敗的上傳保持可見，以便您重試或移除。

對於圖庫，請檢視 Selected media，並用移動控制項設定順序，然後選取 Add images。對於單一圖片或檔案，在上傳完成後選取 Select 或 Insert image。

接受的檔案與大小限制

本機媒體庫預設接受這些檔案群組：

  • PNG、JPEG、GIF、WebP 與 AVIF 圖片；
  • 常見影片格式，如 MP4、WebM 與 QuickTime 影片；
  • 常見音訊格式，如 MP3、WAV 與 Ogg 音訊；以及
  • PDF 文件。

SVG 被排除在預設上傳清單之外，因為 SVG 檔案可能包含作用中內容。當內容模型需要更窄的選取或其他格式時，圖片或檔案欄位可以定義自己的可接受檔案類型清單。EmDash 透過媒體類型（如 image/png 或 application/pdf）識別每個檔案，並在儲存內容時再次檢查欄位清單。變更瀏覽器的檔案選擇器不會略過該伺服器檢查。

預設最大值為每個檔案 50 MB。網站開發者可用 maxUploadSize 變更。提供方可能施加額外的格式或大小限制，並會在上傳列中回報該失敗。

尋找與整理檔案

搜尋符合部分檔案名稱。類型篩選將結果限制為圖片、文件、影片或音訊。檔案名稱搜尋涵蓋整個本機庫，即使資料夾已開啟；在無搜尋的情況下瀏覽資料夾僅顯示指派給該資料夾的檔案。

編輯者可在主庫中選取 Add new folder。透過將卡片或列拖到可見資料夾來移動本機檔案，或開啟檔案、變更 Location 並選取 Save。將 Main library 用作位置可將檔案從其目前資料夾中移除。

作者可以移動自己上傳的本機檔案。編輯者可以移動任何本機檔案。外部提供方項目不能指派到媒體庫資料夾。

刪除資料夾會將其檔案移回主庫。它不會刪除檔案、變更其 URL，也不會移除其內容引用。

為內容選取媒體

Portable Text 圖片

將游標放在 Portable Text 欄位中，開啟區塊選單並選取 Image。選取或上傳圖片，然後選取 Insert image。之後選取圖片區塊以新增替代文字、說明、顯示尺寸與對齊方式。

圖片與檔案欄位

選取欄位動作（如 Select image 或 Select file），然後選取一項並確認。欄位的 MIME 類型規則會限制顯示哪些庫項目與媒體來源。

部落格範本的 featured_image 欄位將所選媒體值與文章一起儲存。儲存項目會將該引用儲存到草稿；發佈後可在公開內容查詢中使用。

圖庫欄位

選取一張或多張圖片，在 Selected media 下排列，然後確認。圖庫保留自己的順序以及每張圖片的替代文字與說明，即使多個位置引用媒體庫項目。

編輯內容中使用的圖片

選定的本機圖片提供不同範圍的動作：

  • Replace 為本欄位、區塊或圖庫位置選取不同的媒體庫項目。使用原項目的其他項目不會改變。
  • Edit asset 開啟底層媒體庫項目。中繼資料變更與破壞性圖片變更可能影響該項目的其他用途。
  • Remove 清除此內容引用。媒體庫項目仍然可用。

當 Edit asset 建立裁切副本時，選擇器會為目前用途選取新副本。Portable Text 與圖庫圖片會保留該用途的替代文字、說明、版面配置與位置。當 Edit asset 取代原件時，媒體 ID 保持不變，因此該項目的每次使用都會收到變更後的圖片。

外部提供方圖片與檔案欄位提供 Replace 與 Remove，但不會開啟本機資產編輯器。

取代本機圖片

Replace image 在現有媒體庫項目背後上傳新位元組。當引用該項目的每個位置都應顯示新版本圖片時使用它。

該動作適用於就緒的 JPEG、PNG 與 WebP 項目。作者可以取代自己上傳的圖片；編輯者可以取代任何本機圖片。

  1. 開啟 Media 並選取本機圖片。

  2. 停留在 Details 並選取 Replace image。

  3. 選取同格式的非空圖片。例如 JPEG 必須取代為 JPEG，但新圖片可以有不同尺寸或長寬比。

  4. 閱讀確認，然後選取 Replace image。

EmDash 保留媒體 ID、檔案名稱、URL、替代文字、說明與資料夾。因此現有內容引用會繼續運作並顯示取代結果。取代會清除已儲存的焦點，因為其座標可能無法描述新圖片。

當只需變更一個欄位或圖片區塊時，請改用內容編輯器中的 Replace。

設定焦點

焦點標記圖片中在版面配置裁切為方形、橫向、直向或其他固定形狀時應保持可見的部分。

  1. 在 Media 中開啟本機圖片，或從內容中使用的圖片選取 Edit asset。

  2. 選取 Edit image，然後選取 Focal point。

  3. 將標記選取或拖到圖片的重要部分。方向鍵可在無指標的情況下移動已聚焦的標記。

  4. 檢查直向、方形與橫向預覽，然後選取 Save。

選取 Reset 可移除自訂點。為欄位或圖庫選取圖片時，EmDash 會將資產的目前焦點複製到該內容值。已使用該圖片的內容會保留其儲存的點，直到您再次選取該圖片。從內容欄位開啟 Edit asset 會用您儲存的點更新目前用途。

裁切本機圖片

裁切適用於 EmDash 儲存的就緒 JPEG、PNG 與 WebP 圖片。外部提供方圖片無法在本機資產編輯器中裁切。

  1. 開啟圖片並選取 Edit image，然後選取 Crop。

  2. 選取 Original、Freeform、Square、4:3、3:2 或 16:9。固定比例在調整大小時保持形狀。Freeform 允許寬度與高度獨立變化。

  3. 移動並調整裁切框大小。可以用指標拖曳，或聚焦框及其控點並使用方向鍵。按住 Shift 與方向鍵可增大步進。

  4. 選取如何儲存結果：

    • Create cropped copy 建立新的媒體庫項目並保持來源不變。
    • Replace original 保留媒體 ID，並在所有使用處變更圖片。

Replace original 僅在 Original 長寬比下可用。對 Freeform 與其他比例使用 Create cropped copy。裁切副本保留在與來源相同的資料夾中，並獲得唯一檔案名稱。

裁切動畫 WebP 會建立靜態 WebP。裁切結果不保留動畫。

查看檔案使用位置

開啟本機檔案並選取 Used in，以列出引用它的內容項目與網站設定。每個內容結果會標明包含引用的集合與欄位，並可開啟項目進行編輯。回收站中的項目會在清單中識別。Site Settings 結果會標明選取該檔案的設定：Logo、Favicon 或 Default Social Image。

Used in 檢查這些引用：

  • 圖片與檔案欄位
  • 中繼器內的圖片欄位
  • blocks 欄位內的圖片、檔案與 Portable Text 欄位
  • Portable Text 欄位中的圖片與圖庫區塊
  • 網站標誌、網站圖示與預設社群圖片

當使用涵蓋完整且檔案沒有任何這些引用時，清單顯示 No tracked references found。在涵蓋完成之前，空清單顯示 No usage to show yet。

媒體使用追蹤必須處於作用中狀態，內容結果才能完整。無論追蹤是否作用中，都會列出網站設定。管理員為網站一次開啟追蹤：

  1. 完成目前內容編輯。暫停寫入內容的指令碼、匯入與其他工具，然後等待進行中的寫入完成。

  2. 開啟 Settings，然後開啟 Media usage tracking，選取 Enable tracking 並確認準備步驟。

  3. 在狀態顯示 Setting up 時保持編輯暫停。EmDash 會準備每個集合，以便將來的儲存可以更新其使用記錄。它會暫時拒絕內容、架構、修訂、匯入與 MCP 寫入，以便在該準備與追蹤變為作用中之間不會發生變更。

  4. 當狀態變為 Indexing existing content 時，可以恢復正常編輯。在 EmDash 掃描現有項目時保持設定頁開啟。

  5. 等待 Ready。若離開頁面，稍後返回時掃描會從已儲存的進度繼續。

一旦啟用，媒體使用追蹤無法關閉。擷取變為作用中後，新的內容變更會被追蹤；背景掃描會新增已存在項目中的引用。

若 Used in 檢視回報索引正在執行、過時、部分或不完整，請將其結果視為不完整。管理員可返回 Media usage tracking 查看目前狀態與復原指引。

在範本中轉譯圖片

圖片欄位傳回媒體值而非純 URL。使用 emdash/ui 的 Image 轉譯該值，以便本機與提供方支援的圖片使用適當的 URL、尺寸、焦點、回應式變體與低品質預留位置：

---
import { getEmDashEntry } from "emdash";
import { Image } from "emdash/ui";

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.redirect("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

僅對頁面頂部可見的主圖使用 priority。它請求 eager 載入並向瀏覽器提供高擷取優先順序提示。其他圖片應保留元件的延遲載入預設值。

若欄位有深色模式對應項，Image 會轉譯兩個來源並根據造訪者的配色方案選取一個。欄位與範本設定請參見深色模式圖片。

範本無需另一次媒體庫查詢即可取得與內容引用一起儲存的媒體中繼資料。若自訂整合需要提供方的最新中繼資料，請明確請求該項目，並避免在集合頁上對每張圖片進行一次提供方查詢。欄位類型參考描述了儲存的檔案與圖片值。

設定儲存與提供方

本機庫透過網站設定的儲存轉接器儲存檔案。Node.js 網站可以使用本機磁碟或 S3 相容儲存；Cloudflare 網站通常使用 R2 繫結。轉接器決定位元組的儲存位置，而媒體庫保持相同的創作工作流程。設定與正式環境持續性要求請參見媒體儲存。

Cloudflare Images 與 Cloudflare Stream 可註冊為外部媒體提供方。它們在選擇器中顯示為來源，且 Image 理解提供方支援的圖片值。提供方項目仍由該服務管理，因此在 EmDash 資產編輯器中，這些項目無法使用本機資料夾、焦點、裁切與取代。

安全刪除媒體

在媒體庫中開啟檔案，選取 Delete，並確認永久刪除。作者可以刪除自己上傳的本機檔案；編輯者可以刪除任何本機檔案。僅當該來源公開刪除功能且目前使用者有權限時，才會從提供方刪除提供方項目。

有關自動化上傳與媒體管理，請參見媒體端點參考或 CLI 媒體命令。繼續參閱處理內容，以發佈使用所選媒體的項目。