E EmDash CMS Everything Guides, use cases, plugins, templates
简体中文

媒体库

本页内容

媒体库用于存放可复用的图片、文档、视频和音频。编辑者只需上传一次文件，就可以在内容字段和 Portable Text 中选择它们，并查看哪些内容条目引用了某个本地媒体项。

打开媒体库

在管理后台侧边栏中选择 Media。Main library 包含文件夹，以及尚未放入任何文件夹的文件。选择某个文件夹即可浏览其中的文件，也可以在网格视图和列表视图之间切换。

如果站点配置了外部媒体提供方，每个提供方都会显示为另一个来源。各提供方的能力各不相同：某个来源可能支持浏览和选择，但不支持文件夹、本地图片编辑或删除。

上传文件

从库中上传

  1. 选择 Media，然后选择 Upload Files。

  2. 选择 Browse files，并选取一个或多个文件。你也可以把文件拖到上传区域或媒体库上。

  3. 文件上传期间请保持对话框打开。每一行会显示 Queued、Uploading、Complete 或 Upload failed。

  4. 对于上传失败的文件，请选择其重试操作。你可以取消未完成的上传、移除失败的行，或清除已完成的行，这些操作都不会影响已经完成的文件。

  5. 当队列中没有未完成的上传时，选择 Done。

添加文件后上传会立即开始。新的本地文件会进入 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 项目。作者可以替换自己上传的图片；编辑者可以替换任何本地图片。

  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，并在该图片被使用的所有位置更改图片。

只有 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。

必须先启用媒体使用追踪，内容结果才可能是完整的。无论追踪是否启用，站点设置都会被列出。管理员只需为站点启用一次追踪：

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

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

只对页面顶部可见的主图使用 priority。它会请求预先加载，并向浏览器给出高获取优先级的提示。其他图片应保留该组件默认的懒加载。

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

模板无需再次查询媒体库，即可获得与内容引用一同存储的媒体元数据。如果自定义集成需要提供方的最新元数据，请明确请求该项目，并避免在集合页面上为每张图片各查询一次提供方。字段类型参考介绍了已存储的文件和图片值。

配置存储与提供方

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

Cloudflare Images 和 Cloudflare Stream 可以注册为外部媒体提供方。它们会作为来源出现在选择器中，并且 Image 能识别由提供方支持的图片值。提供方的项目仍由该服务管理，因此在 EmDash 的资源编辑器中，这些项目无法使用本地文件夹、焦点、裁剪和替换。

安全删除媒体

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

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