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 列出引用它的内容条目。每个结果显示包含引用的集合和字段，并可以打开条目进行编辑。已回收的条目在列表中会被标识。

媒体使用追踪必须处于活动状态，此列表才能完整。管理员为站点启用一次：

  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。它请求立即加载并给浏览器一个高 fetch-priority 提示。其他图片应保留组件默认的懒加载。

如果字段有深色模式对应项，Image 会渲染两个来源并根据访问者的颜色方案选择一个。请参阅深色模式图片了解字段和模板设置。

模板接收与内容引用一起存储的媒体元数据，无需额外的媒体库查询。如果自定义集成需要提供商的最新元数据，请显式请求该项目，避免在集合页面上每个图片进行一次提供商查找。字段类型参考描述了存储的文件和图片值。

配置存储和提供商

本地库通过站点配置的存储适配器存储文件。Node.js 站点可以使用本地磁盘或 S3 兼容存储；Cloudflare 站点通常使用 R2 绑定。适配器决定字节的存储位置，而媒体库保持相同的创作工作流程。有关配置和生产环境持久性要求，请参阅媒体存储。

Cloudflare Images 和 Cloudflare Stream 可以注册为外部媒体提供商。它们在选择器中显示为来源，Image 理解提供商支持的图片值。提供商项目仍由该服务管理，因此本地文件夹、焦点、裁剪和替换在 EmDash 资源编辑器中不可用于这些项目。

安全删除媒体

在媒体库中打开文件，选择 Delete 并确认永久删除。作者可以删除他们上传的本地文件；编辑者可以删除任何本地文件。只有当来源公开了删除功能且当前用户有权限时，提供商项目才会从其提供商中删除。

有关自动化上传和媒体管理，请参阅媒体端点参考或 CLI 媒体命令。继续阅读使用内容来发布使用所选媒体的条目。