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 媒体命令。继续参阅处理内容，以发布使用所选媒体的条目。