媒體庫

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

存取媒體庫

透過管理側邊欄點擊 Media 開啟媒體庫。媒體庫顯示所有已上傳的檔案，包括預覽、檔案名稱和上傳日期。

上傳檔案

從媒體庫上傳

1. 點擊管理側邊欄中的 Media

2. 點擊 Upload 或將檔案拖曳到上傳區域

3. 從電腦中選擇一個或多個檔案

4. 等待上傳完成

從內容編輯器上傳

1. 在富文本編輯器中，點擊圖片按鈕

2. 在媒體選擇器中點擊 Upload

3. 從電腦中選擇檔案

4. 新增替代文字並點擊 插入

支援的檔案類型

EmDash 支援常見的 Web 檔案類型：

儲存後端

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",
      }),
    }),
  ],
});

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",
      }),
    }),
  ],
});

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

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",
      }),
    }),
  ],
});

上傳工作原理

EmDash 使用簽署 URL 進行安全上傳：

1. 用戶端向 API 請求上傳 URL

2. 伺服器產生帶有過期時間的簽署 URL

3. 用戶端使用簽署 URL 直接上傳到儲存空間

4. 伺服器將檔案中繼資料記錄到資料庫

這種方式將大型檔案從應用程式伺服器分離，並支援直接上傳到雲端儲存。

組織媒體

資料夾

建立資料夾來組織您的媒體：

1. 在媒體庫中點擊 New Folder

2. 輸入資料夾名稱

3. 點擊 建立

4. 將檔案拖入資料夾進行組織

搜尋

使用搜尋框按名稱尋找檔案。搜尋可比對部分檔案名稱。

篩選

按以下條件篩選媒體：

• 類型 - 圖片、文件、影片、音訊
• 日期 - 上傳日期範圍
• 資料夾 - 特定資料夾

在內容中使用媒體

在富文本編輯器中

1. 將游標放在您要插入圖片的位置

2. 點擊工具列中的圖片按鈕

3. 從媒體庫選擇圖片或上傳新圖片

4. 輸入替代文字

5. 點擊 插入

作為精選圖片

1. 在編輯器中開啟內容項目

2. 在側邊欄找到 Featured Image 欄位

3. 點擊 選擇圖片

4. 從媒體庫選擇或上傳

5. 點擊 儲存

在自訂欄位中

對於設定為圖片或檔案類型的欄位，點擊該欄位開啟媒體選擇器。

在範本中顯示媒體

從內容資料中存取媒體 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 給瀏覽器提供請求優先級提示。

刪除媒體

1. 選擇要刪除的檔案

2. 點擊 刪除

3. 確認刪除

媒體 API

透過管理 API 以程式方式存取媒體。

上傳檔案

以 multipart 表單資料形式上傳媒體：

POST /_emdash/api/media
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

file=<binary file data>

上傳成功後回傳儲存的媒體項目：

{
	"success": true,
	"data": {
		"item": {
			"id": "01ABC123",
			"filename": "hero-image.jpg",
			"mime_type": "image/jpeg",
			"storage_key": "media/abc123/hero-image.jpg",
			"width": 1200,
			"height": 800
		}
	}
}

列出媒體

以下請求列出某個前綴下的媒體：

GET /_emdash/api/media?prefix=images/&limit=20
Authorization: Bearer YOUR_API_TOKEN

刪除媒體

以下請求刪除一個儲存的檔案：

DELETE /_emdash/api/media/images/hero.jpg
Authorization: Bearer YOUR_API_TOKEN

媒體提供者

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

可用提供者

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",
        }),
      ],
    }),
  ],
});

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,
        }),
      ],
    }),
  ],
});

使用多個提供者

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

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,
        }),
      ],
    }),
  ],
});

本機媒體庫（“Library” 分頁）始終可用，與任何已設定的提供者並存。

渲染提供者媒體

使用 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 變換）

MediaValue 類型

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

interface MediaValue {
  provider?: string;    // 提供者 ID，預設為 "local"
  id: string;           // 提供者特定的 ID
  src?: string;         // 直接 URL（用於本機媒體或純字串值）
  previewUrl?: string;  // 管理面板顯示的預覽 URL（外部提供者）
  filename?: string;    // 原始檔案名稱
  mimeType?: string;    // MIME 類型
  width?: number;       // 圖片/影片寬度
  height?: number;      // 圖片/影片高度
  alt?: string;         // 替代文字
  meta?: Record<string, unknown>; // 提供者特定的中繼資料
}

這使 EmDash 能夠正確渲染媒體，無論其託管在何處。

下一步

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