媒體庫

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

開啟媒體庫

在管理後台側邊欄中選取 Media。Main library 包含資料夾，以及尚未放入任何資料夾的檔案。選取某個資料夾即可瀏覽其中的檔案，也可以在格狀檢視和清單檢視之間切換。

如果站台設定了外部媒體提供方，每個提供方都會顯示為另一個來源。各提供方的能力各不相同：某個來源可能支援瀏覽和選取，但不支援資料夾、本機圖片編輯或刪除。

上傳檔案

從媒體庫上傳

加入檔案後上傳會立即開始。新的本機檔案會進入 Main library，即使上傳之前開啟的是另一個資料夾。

在編輯內容時上傳

圖片、檔案、圖庫和 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 修改它。提供方可能會施加額外的格式或大小限制，並在上傳列中回報該失敗。

尋找與整理檔案

搜尋支援檔名的部分比對。類型篩選器可將結果限定為圖片、文件、影片或音訊。檔名搜尋會涵蓋整個本機媒體庫，即使某個資料夾處於開啟狀態；不搜尋而直接瀏覽資料夾時，只顯示指派到該資料夾的檔案。

編輯者可以在 Main library 中選取 Add new folder。要移動本機檔案，可將其卡片或列拖曳到可見的資料夾上，或者開啟該檔案，變更 Location，然後選取 Save。將 Main library 用作位置，即可把檔案從其目前的資料夾中移出。

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

刪除資料夾會把其中的檔案移回 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 項目。作者可以取代自己上傳的圖片；編輯者可以取代任何本機圖片。

EmDash 會保留媒體 ID、檔名、URL、替代文字、說明文字和資料夾。因此，現有的內容引用會繼續有效，並顯示取代後的圖片。取代會清除已儲存的焦點，因為其座標可能不再適用於新圖片。

如果只有一個欄位或圖片區塊需要變更，請改在內容編輯器中使用 Replace。

設定焦點

當版面配置把圖片裁切以填滿方形、橫向、直向或其他固定形狀時，焦點用來標記圖片中應保持可見的部分。

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

裁切本機圖片

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

只有 Original 長寬比才提供 Replace original。對於 Freeform 和其他比例，請使用 Create cropped copy。裁切副本與其來源項目位於同一資料夾，並會獲得唯一的檔名。

裁切動畫 WebP 會產生靜態 WebP。裁切結果不會保留動畫。

查看檔案的使用位置

開啟本機檔案並選取 Used in，即可列出引用它的內容條目和站台設定。每個內容結果會指出包含該引用的集合和欄位，並可開啟條目進行編輯。已移至垃圾桶的條目會在清單中標明。Site Settings 結果會指出選用該檔案的設定：Logo、Favicon 或 Default Social Image。

Used in 會檢查以下引用：

• 圖片和檔案欄位
• 重複項（repeater）內的圖片欄位
• blocks 欄位內的圖片、檔案和 Portable Text 欄位
• Portable Text 欄位中的圖片、圖庫和影片區塊
• 站台標誌、favicon 和預設社群圖片

當使用情況的涵蓋範圍已經完整，並且該檔案沒有上述任何引用時，清單顯示 No tracked references found。在涵蓋範圍完整之前，空清單會顯示 No usage to show yet。

必須先啟用媒體使用追蹤，內容結果才可能是完整的。無論追蹤是否啟用，站台設定都會被列出。管理員只需為站台啟用一次追蹤：

追蹤一經啟用就無法關閉。新的內容變更在擷取生效後會被追蹤；背景掃描會補充來自已存在條目的引用。

如果 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.rewrite("/404");
---

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

只對頁面頂部可見的主圖使用 priority。它會要求預先載入，並向瀏覽器給出高擷取優先順序的提示。其他圖片應保留該元件預設的延遲載入。

如果欄位有對應的深色模式圖片，Image 會算繪兩個來源，並根據訪客的配色方案選擇其一。欄位和範本的設定請參閱深色圖片變體。

範本無需再次查詢媒體庫，即可取得與內容引用一同儲存的媒體中繼資料。如果自訂整合需要提供方的最新中繼資料，請明確要求該項目，並避免在集合頁面上為每張圖片各查詢一次提供方。欄位型別參考介紹了已儲存的檔案和圖片值。

在範本中算繪檔案

媒體庫中檔案欄位的值不帶現成的 URL。請把它的 meta.storageKey 傳給 Astro.locals.emdash.getPublicMediaUrl()，它會回傳公開 URL，並遵循已設定的 R2 或 S3 公開網域，同時無需查詢媒體資料表。沒有儲存鍵的舊值會把 URL 保存在 url 中，而透過 URL 新增的檔案（以 provider: "external" 儲存）則保存在 src 中。

對於來自已註冊媒體提供方（例如 Cloudflare Stream）的檔案，src 保存的是預覽圖而不是檔案本身，因此這種方法不適用於它。

下面的頁面算繪儲存在 video 檔案欄位中的影片：

---
import { getEmDashEntry } from "emdash";

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

const file = entry.data.video;
const storageKey = typeof file?.meta?.storageKey === "string" ? file.meta.storageKey : undefined;
const url = storageKey
  ? Astro.locals.emdash?.getPublicMediaUrl?.(storageKey)
  : file?.provider === "external"
    ? file.src
    : file?.url;
---

{url && <video src={url} controls preload="metadata" />}

同一個 URL 也可用於下載連結，或任何需要檔案位址的其他元素。值中的檔案名稱、MIME 類型和大小，是選取該檔案時儲存的內容。

設定儲存與提供方

本機媒體庫透過站台設定的儲存轉接器來儲存檔案。Node.js 站台可以使用本機磁碟或 S3 相容儲存；Cloudflare 站台通常使用 R2 繫結。轉接器決定位元組內容存放在哪裡，而媒體庫保持相同的創作工作流程。設定和正式環境的持久化需求請參閱選擇媒體儲存。

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

安全刪除媒體

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

關於自動化上傳和媒體管理，請參閱媒體端點參考或 CLI 媒體指令。繼續閱讀處理內容，以發佈使用所選媒體的條目。