媒體庫 | EmDash CMS Everything

EmDash 包含一個用於管理圖片、文件和其他檔案的媒體庫。本指南涵蓋在內容中上傳、尋找和使用媒體。

存取媒體庫

在管理側邊欄中點擊媒體開啟媒體庫。主庫顯示未指派到資料夾的資料夾和檔案。開啟資料夾檢視其檔案。

使用位置

在 EmDash 的媒體庫中開啟一個檔案，檢視參照它的內容項目。在 EmDash 掃描現有內容期間，清單包含截至目前找到的參照，可能不完整。

開啟媒體使用追蹤

如果媒體使用追蹤已關閉，管理員可以開啟它：

完成所有內容編輯。如果另一個應用程式直接寫入內容資料庫，請暫停它並等待進行中的寫入完成。
開啟設定 → 媒體使用追蹤，選擇啟用追蹤，然後確認。
當頁面顯示正在索引現有內容時，編輯和其他資料庫寫入可以恢復。
保持頁面開啟直到顯示就緒。如果離開，返回以從儲存的進度繼續。

一旦開啟媒體使用追蹤，就不能關閉。

上傳檔案

從媒體庫

在管理側邊欄中開啟媒體。
選擇上傳檔案，然後瀏覽檔案選擇一個或多個檔案。你也可以將檔案拖放到媒體庫的任何位置。
上傳自動開始。對話方塊顯示每個檔案的狀態，並允許取消或重試個別檔案。

從內容編輯器

在內容編輯器中開啟圖片、檔案或相簿欄位。
搜尋、按類型篩選、瀏覽資料夾或在可用的媒體來源之間切換。
選擇現有媒體，或選擇上傳檔案並從電腦中選擇檔案。你也可以將檔案拖放到選擇器上。每個上傳都會以其目前狀態出現在結果中。
如果上傳失敗，在該項目上選擇重試或移除。成功的上傳變成一個已選媒體卡片。
對於相簿，使用已選媒體下的箭頭控制項設定回傳順序。
選擇選擇器操作，如選擇、插入圖片或新增 3 張圖片。

支援的檔案類型

EmDash 預設接受以下檔案類型：

類別	副檔名
圖片	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`
文件	`.pdf`
影片	`.mp4`, `.webm`, `.mov`
音訊	`.mp3`, `.wav`, `.ogg`

圖片和檔案欄位可以允許其他 MIME 類型，包括用於 SVG 檔案的 image/svg+xml。

儲存後端

EmDash 支援多個儲存後端。在 Astro 設定中配置儲存：

本機儲存

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: local({
        directory: "./uploads",
        baseUrl: "/_emdash/api/media/file",
      }),
    }),
  ],
});

檔案儲存在 ./uploads 目錄中。適合開發和單伺服器部署。

Cloudflare R2

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      storage: r2({
        binding: "MEDIA_BUCKET",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

需要在 wrangler.jsonc 中設定的 R2 儲存桶：

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

S3 相容

import { defineConfig } from "astro/config";
import emdash, { s3 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: "https://s3.amazonaws.com",
        bucket: "my-media-bucket",
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "us-east-1",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

適用於 Cloudflare R2（透過 S3 API）、MinIO 和其他 S3 相容服務。

上傳的運作方式

管理介面使用上傳目標流程：

用戶端請求上傳目標，EmDash 建立一個待處理的媒體項目。
用戶端將檔案上傳到回傳的目標。
用戶端確認上傳。
EmDash 驗證儲存的檔案並將媒體項目標記為就緒。

S3 相容儲存回傳簽署 URL，以便檔案可以繞過應用程式執行階段。本機儲存和原生 R2 回傳同源串流端點。

尋找媒體

搜尋

使用搜尋方塊按名稱尋找檔案。搜尋符合部分檔案名稱。

按類型篩選

使用類型篩選器顯示圖片、文件、影片或音訊檔案。

在資料夾中整理媒體

編輯者可以從主庫選擇新增資料夾。選擇資料夾名稱開啟資料夾。沒有搜尋詞時，資料夾頁面只顯示指派給該資料夾的媒體。檔案名稱搜尋涵蓋整個庫，包括其他資料夾和主庫。

要將本機檔案移入可見資料夾，將其網格卡片或清單列拖到資料夾上。你也可以開啟媒體詳情，選擇一個位置，然後選擇儲存。使用位置將檔案回傳到主庫或不用拖曳移動它。

作者可以移動他們上傳的本機檔案。編輯者可以移動任何本機檔案。外部提供者的檔案不能指派到資料夾。

上傳進入主庫。使用上述任一方法在上傳後將它們移入資料夾。

刪除資料夾將其媒體回傳到主庫。媒體檔案、URL 和內容參照保持不變。

在內容中使用媒體

在富文字編輯器中

將游標放在你想要圖片的位置
點擊工具列中的圖片按鈕
在選擇器中找到圖片或上傳新的。
選擇插入圖片。
在圖片設定中新增替代文字。

作為精選圖片

在編輯器中開啟內容項目
在側邊欄中找到精選圖片欄位
點擊選擇圖片
從選擇器中選擇圖片或上傳一個。
選擇選擇，然後儲存。

在自訂欄位中

對於設定為圖片或檔案類型的欄位，選擇欄位操作開啟同樣的媒體選擇器。欄位的 MIME 類型規則限制你可以選擇的來源和檔案。

編輯選定的圖片資產

本機圖片欄位、富文字圖片和相簿圖片提供三個操作：

取代變更目前欄位、區塊或相簿位置中使用的圖片。
編輯資產開啟所選媒體庫項目的媒體詳情。你可以在內容編輯器中更新其替代文字、標題、焦點或裁剪。
移除清除目前內容參照。媒體庫項目仍然可用。

建立裁剪副本為目前使用選擇新副本。富文字和相簿圖片保留其每次使用的替代文字、標題、版面配置和位置。取代原始保持相同的媒體參照，並在該資產使用的所有地方變更圖片。

外部提供者的圖片和檔案欄位提供取代和移除，但不提供編輯資產。

取代圖片

使用取代圖片更新現有本機媒體項目背後的檔案。作者可以取代他們上傳的圖片，編輯者可以取代任何本機圖片。此操作適用於儲存在本機磁碟、Cloudflare R2 或 S3 相容儲存上的 JPEG、PNG 和 WebP 圖片。

開啟媒體，然後從本機庫中選擇一張圖片。
留在詳情，然後選擇取代圖片。
選擇與現有檔案相同格式的非空圖片。
檢視警告，然後選擇取代圖片確認。

取代可以使用與現有圖片不同的尺寸或長寬比。EmDash 保留媒體 ID、檔案名稱、URL、替代文字、標題和位置，因此每個現有參照都使用取代。取代檔案會清除其焦點。

取代圖片從你的電腦上傳另一個檔案。要裁剪目前圖片，從裁剪編輯器選擇取代原始。

設定焦點

焦點在卡片、相簿或其他版面配置將本機圖片裁剪為固定形狀時，保持圖片的重要部分可見。

開啟媒體並從本機庫中選擇一張圖片，或在內容編輯器中為本機圖片選擇編輯資產。
選擇編輯圖片，然後焦點。
點擊或拖曳標記到圖片的重要部分。你也可以使用方向鍵。
檢查方形、橫向和縱向預覽，然後選擇儲存。

選擇重設以移除自訂焦點。儲存的點在你為內容欄位或相簿選擇圖片時被複製。已經使用該圖片的其他內容保留其儲存的點，直到你再次選擇該圖片。當你從內容欄位或相簿編輯資產時，該目前使用以儲存的焦點重新整理。

裁剪圖片

裁剪適用於上傳到 EmDash 的 JPEG、PNG 和 WebP 圖片。它適用於本機儲存、Cloudflare R2 和 S3 相容儲存。外部媒體提供者的圖片不能在媒體庫中裁剪。

開啟媒體，然後從本機庫中選擇一張圖片。
選擇編輯圖片，然後裁剪。
選擇原始、自由形式或常見長寬比。固定比例在調整大小時保持鎖定。自由形式允許你獨立變更寬度和高度。
在圖片上移動裁剪框。對於固定比例，拖曳角來調整大小。自由形式還提供四個邊緣把手。三分法網格保持可見。你可以聚焦框架或把手並使用方向鍵。按住 Shift 進行更大的步幅。
選擇裁剪操作之一：
- 建立裁剪副本建立一個獨立的媒體項目並保持原始不變。在你想使用它的每個內容項目中選擇裁剪副本。
- 取代原始在媒體項目使用的所有地方取代圖片。現有內容項目保持相同的媒體參照，不會被重寫或重新發布。

裁剪 WebP 檔案會產生靜態 WebP 圖片。如果來源是動畫的，裁剪結果不保留動畫。

在範本中顯示媒體

從內容資料存取媒體 URL：

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <img
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
  />
)}

響應式圖片

對於 EmDash 媒體欄位，使用 emdash/ui 的 Image 元件：

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
    priority
  />
)}

priority 用於首屏主圖。它設定 loading="eager" 和 fetchpriority="high"：loading 控制是否延遲載入，fetchpriority 為瀏覽器提供請求優先順序提示。

當欄位值攜帶暗色對應版本時，Image 算繪兩者並顯示與訪客色彩配置相符的那個。暗色模式涵蓋在欄位上啟用插槽以及元件依賴的 <html> 類別慣例。

EmDash 安裝一個按需產生調整後變體的圖片端點。在 Cloudflare Workers 上，該端點使用 IMAGES 繫結。圖片變換涵蓋繫結的來源以及缺少時的情況。

刪除媒體

選擇要刪除的檔案
點擊刪除
確認刪除

媒體 API

使用 REST API 上傳、列出、更新、刪除和整理本機媒體。媒體端點參考記錄了直接多部分上傳和上傳目標流程、請求參數、回應格式、權限和資料夾操作。

媒體提供者

除本機儲存外，EmDash 還支援用於專業圖片和影片託管的外部媒體提供者。媒體提供者在媒體選擇器中顯示為分頁，讓編輯者從多個來源中選擇。

可用提供者

Cloudflare Images

Cloudflare Images 提供帶自動最佳化、調整大小和格式轉換的圖片託管。

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

功能：

從管理介面直接瀏覽和上傳圖片
自動圖片最佳化和格式轉換
基於 URL 的變換（調整大小、裁剪、格式）
用於響應式圖片的靈活變體

Cloudflare Stream

Cloudflare Stream 提供帶 HLS/DASH 自適應串流的影片託管。

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

功能：

從管理介面瀏覽、搜尋和上傳影片
HLS 和 DASH 自適應串流
自動縮圖產生
大檔案直接上傳

使用多個提供者

你可以設定多個提供者。每個提供者在媒體選擇器中顯示為分頁：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages, cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
        }),
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
        }),
      ],
    }),
  ],
});

本機媒體庫（「庫」分頁）始終與任何設定的提供者一起可用。

算繪提供者媒體

使用 Image 元件算繪媒體：

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

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
  />
)}

元件自動：

從儲存的值中偵測提供者
算繪最佳化的 <img> 元素
套用提供者特定的最佳化（如 Cloudflare Images 變換）

檔案值和目前中繼資料

檔案欄位儲存參照和中繼資料快照。url、filename、mimeType 和 size 等快取欄位是選擇性的，因為持久化的值可能省略它們：

interface FileValue {
  id: string;
  url?: string;
  src?: string;
  filename?: string;
  mimeType?: string;
  size?: number;
  provider?: string;
  meta?: Record<string, unknown>;
}

getEmDashEntry() 和 getEmDashCollection() 回傳此儲存的值，無需額外的媒體查詢。要取得目前中繼資料，請明確使用設定的提供者的 get() 方法。使用 getEmbed() 取得提供者特定的算繪 URL：

---
const file = post.data.attachment;
const provider = file
  ? Astro.locals.emdash?.getMediaProvider(file.provider ?? "local")
  : undefined;
const current = file ? await provider?.get?.(file.id) : null;
const embed = file && provider ? await provider.getEmbed(file) : null;
---

經過驗證的 HTTP 用戶端可以透過 GET /_emdash/api/media/:id 查詢本機媒體或透過 GET /_emdash/api/media/providers/:providerId/:itemId 查詢其他提供者。

對於本機檔案 URL，使用儲存的 meta.storageKey 與公開 URL 輔助工具。這尊重設定的 R2 或 S3 公開網域，而無需查詢媒體表格：

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

提供者查詢可能涉及網路或資料庫工作。避免在未登入的集合頁面上每個檔案進行一次查詢；除非請求需要最新的中繼資料，否則使用儲存的快照和算繪元件。

MediaValue 類型

媒體欄位儲存包含提供者資訊的 MediaValue 物件：

interface MediaValue {
  provider?: string;
  id: string;
  src?: string;
  previewUrl?: string;
  filename?: string;
  mimeType?: string;
  width?: number;
  height?: number;
  focalX?: number;
  focalY?: number;
  alt?: string;
  meta?: Record<string, unknown>;
}

這允許 EmDash 無論媒體託管在何處都能正確算繪。

下一步

內容操作 - 在內容中使用媒體
建立部落格 - 在部落格文章中新增圖片
查詢內容 - 在範本中顯示媒體