Media Library（媒体库）

页面摘要： Media Library（媒体库）集中管理所有已上传的资源，提供搜索、筛选和文件夹组织功能。本文档包含提供方选项、上传工作流，以及在内容中插入媒体的说明。

Media Library（媒体库）是 Strapi 的一项功能，用于显示 Strapi 应用中上传的所有资源，并允许用户对其进行管理。

• 套餐：免费功能
• 角色与权限：在「角色 > 插件 - 上传（Upload）」中至少具备「访问 Media Library（媒体库）」权限
• 启用：默认可用且已启用
• 环境：在开发（Development）和生产（Production）环境中均可用

配置

Media Library（媒体库）的部分配置选项可在管理面板中设置，部分则需要通过 Strapi 项目代码进行处理。

管理面板配置

在管理面板中，部分 Media Library（媒体库）设置可通过全局设置（Global Settings）进行配置，用于管理已上传资源的格式、文件大小和方向。

配置设置

配置该功能的路径： 设置 > 全局设置 > Media Library（媒体库）。

1. 定义你选择的新 Media Library（媒体库）设置：

   设置名称	说明	默认值
   上传时自动生成 AI 说明文字和替代文本！	启用该选项将开启 AI 驱动的元数据生成 （Growth 计划）	已启用
   响应式友好上传	启用该选项将为上传的资源生成多种格式（小、中、大）。
   每种格式的默认尺寸可通过代码配置。	True
   大小优化	启用该选项将减小图片大小并略微降低其质量。	True
   自动方向	启用该选项将根据 EXIF 方向标签自动旋转图片。	False

2. 点击 保存（Save） 按钮。

基于代码的配置

Media Library（媒体库）在后端服务器中由 Upload 包提供支持，可通过提供方（providers）进行配置和扩展。

恢复先前的 Media Library（媒体库）{#use-legacy-media-library}

（v5.54.0+）

本页描述的 Media Library（媒体库）是 Strapi v5.54.0 起的默认 UI。要恢复先前的界面，请在 config/features 文件中将 useLegacyMediaLibrary 属性设为 true：

JavaScript

module.exports = ({ env }) => ({
  useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});

TypeScript

export default ({ env }) => ({
  useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});

提供方（Providers）

Media Library（媒体库）支持通过提供方（providers）添加来自各类第三方的上传支持。

Strapi 维护的提供方如下。点击卡片将跳转到带有配置示例的文档页面：

• Amazon S3 — 用于将文件上传到 Amazon S3 的官方提供方。
• Cloudinary — 用于通过 Cloudinary 进行媒体管理的官方提供方。
• Local — 默认提供方，用于在服务器本地存储文件。

如果你需要安装其他提供方或创建自己的提供方，请参阅以下指南：

• Media Library Providers（媒体库提供方） — 了解如何添加其他提供方或创建你自己的提供方。

私有存储提供方

当配置的提供方为私有（例如设置了 ACL: 'private' 的 S3 存储桶）时，Strapi 返回的每个文件 URL 都是签名 URL，会在 signedUrlExpires 之后过期。媒体字段在每次读取时都会重新签名，但富文本（richtext）和块（blocks）字段会直接将 URL 嵌入其值中。

Strapi 将富文本（richtext）和块（blocks）字段的未签名 URL 存储在数据库中，并在每次读取条目时（在管理面板中，以及通过 REST 和 Document Service API）重新签名。这也适用于嵌套在组件和动态区域（dynamic zones）中的富文本（richtext）和块（blocks）属性。在此行为引入之前写入、仍持有签名 URL 的行，会在应用下次启动时自动重写。

:::caution 通过每个文件 path 提供方选项上传的文件，无法从富文本（richtext）或块（blocks）字段重新签名：该 URL 被识别为属于该提供方，但仅凭 URL 无法重建其存储键，签名链接会返回 403 错误。媒体字段存在相同的限制。 :::

可用选项

使用默认上传提供方时，可在 the config/plugins file 内的 upload.config 对象中声明以下特定配置选项。所有参数均为可选：

(1 GB，以字节计) | | breakpoints | 允许你覆盖「响应式友好上传」选项设为 true 时生成响应式图片的尺寸断点（见 响应式图片） | Object | { large: 1000, medium: 750, small: 500 } | | sharp | 配置 sharp 图像处理选项（见 sharp 配置） | Object | { cache: false, concurrency: 1 } | | security | 配置上传文件的校验规则以增强媒体安全性（见 security） | Object | - | | concurrentUploadRequests | 管理面板向服务器并行上传的文件数量（见 concurrent file uploads）。必须为 >= 1 的整数。 | Integer | 1 | | concurrentUploadSize | 服务器在单个上传请求中并行处理的文件数量（见 concurrent file uploads）。必须为 >= 1 的整数。 | Integer | 1 |

自定义配置示例

以下是使用默认上传提供方时 Upload 插件的自定义配置示例：

JavaScript

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb，以字节计
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
});

TypeScript

export default () => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb，以字节计
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
})

本地服务器

默认情况下，Strapi 接受针对本地上传文件的 localServer 配置。这些配置将作为 koa-static 的选项传递。

你可以通过创建或编辑 the /config/plugins file 来提供这些配置。以下示例设置了 max-age 响应头：

JavaScript

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

TypeScript

export default ({ env }) => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

最大文件大小

负责解析请求的 Strapi 中间件需要进行配置，以支持大于默认 1 GB 的文件大小。除了传递给 Upload 包的 sizeLimit 提供方选项外，还必须进行此项配置。

:::caution 你可能还需要调整任何上游代理、负载均衡器或防火墙，以允许更大的文件大小。例如，Nginx 有一个名为 client_max_body_size 的配置项需要调大，因为其默认值仅为 1mb。 :::

Upload 包使用的中间件是 the body middleware。你可以通过在 /config/middlewares 文件中进行设置，直接向该中间件传递配置：

JavaScript

module.exports = [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // 修改表单体
      jsonLimit: "256mb", // 修改 JSON 体
      textLimit: "256mb", // 修改文本体
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // 多部分数据，在此修改上传文件大小限制
      },
    },
  },
  // ...
];

TypeScript

export default [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // 修改表单体
      jsonLimit: "256mb", // 修改 JSON 体
      textLimit: "256mb", // 修改文本体
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // 多部分数据，在此修改上传文件大小限制
      },
    },
  },
  // ...
];

除了中间件配置外，你还可以在 /config/plugins file 中传递 sizeLimit（以字节为单位的整数）：

JavaScript

module.exports = {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb，以字节计
    }
  }
};

TypeScript

export default {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb，以字节计
    }
  }
};

安全性

Upload 插件根据实际 MIME 类型而非声明的文件扩展名来校验文件。只有符合定义的安全规则的文件中才会被上传。

security 配置提供 2 个选项：allowedTypes 或 deniedTypes，让你可以控制哪些文件类型可以或不可以被上传。

使用 create-strapi-app 脚手架创建的应用，会在生成的 config/plugins.* 文件中包含一个预配置的 security 块。完整列表见下方 create-strapi-app 生成的安全默认值 详情块。

由 create-strapi-app 生成的安全默认值：

新项目将这 2 个列表声明为独立变量，并连同其他生成的插件配置一起传递给 upload 插件：

JavaScript

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

TypeScript

import type { Core } from '@strapi/strapi';

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

export default config;

SVG 上传

自 Strapi （v5.52.2+） 起，image/svg+xml 是 create-strapi-app 生成的 deniedTypes 的一部分，因此即使它匹配 allowedTypes 中的 image/* 通配符，SVG 上传也会被拒绝。明确的 deniedTypes 条目始终优先于 allowedTypes 中的通配符。

SVG 文件可以嵌入浏览器活动内容（如脚本和事件处理器），这就是默认拒绝它们的原因。这仅影响新生成的项目。现有项目会保留其当前配置，除非你自行添加相同的条目。

要接受 SVG 上传，请从你的 config/plugins.* 文件中的 deniedTypes 移除 image/svg+xml（见 security）。将生成的文件通过不与你的应用共享 Cookie 或本地存储的域名提供，或使用 Content-Disposition: attachment 响应头，这样上传的 SVG 就无法在你的站点上下文中运行脚本。

歧义 MIME 类型的文件类型检测

当浏览器为文件报告通用 MIME 类型（如 application/octet-stream）时，Strapi 的 Media Library（媒体库）会通过检查文件实际内容字节来执行文件类型检测。这确保了准确的文件分类和筛选，尤其是对于 Windows 系统上的 .mov 文件等格式——浏览器通常会为它们报告通用 MIME 类型。

文件类型检测用于：

• 在 Media Library（媒体库）预览和网格中对媒体进行分类
• 校验媒体字段约束（例如 allowedTypes: ['video/*']）（在内容管理器（Content Manager）中）

你可以通过创建或编辑 the /config/plugins file 来提供这些配置。以下是如何组合 allowedTypes 和 deniedTypes 的示例：

JavaScript

module.exports = {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

TypeScript

export default {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

上传请求超时

默认情况下，strapi.server.httpServer.requestTimeout 的值设为 330 秒。这其中包括上传。

为了让网络连接较慢的用户能够上传大文件，可能需要提高此超时限制。推荐的方法是在 the config/servers file 中设置 http.serverOptions.requestTimeout 参数。

另一种方法是在 the bootstrap function（Strapi 启动前运行的函数）中设置 requestTimeout 值。这在需要以编程方式更改时很有用，例如临时禁用再重新启用它：

JavaScript

module.exports = {

  //...

  bootstrap({ strapi }) {
    // 将 requestTimeout 设为 1,800,000 毫秒（30 分钟）：
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

TypeScript

export default {

  //...

  bootstrap({ strapi }) {
    // 将 requestTimeout 设为 1,800,000 毫秒（30 分钟）：
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

并发文件上传 {#concurrent-file-uploads}

批量上传由 2 个选项控制，它们决定 Strapi 同时处理多少个文件：

两者默认值都是 1，因此文件一次上传和处理一个。提高 concurrentUploadRequests 会让管理面板同时发送更多上传请求，提高 concurrentUploadSize 会让服务器在单个请求内一次处理更多文件。两者都能加快批量上传速度，代价是服务器负载更高。

JavaScript

module.exports = () => ({
  upload: {
    config: {
      // highlight-start
      concurrentUploadRequests: 4,
      concurrentUploadSize: 2,
      // highlight-end
    },
  },
});

TypeScript

export default () => ({
  upload: {
    config: {
      // highlight-start
      concurrentUploadRequests: 4,
      concurrentUploadSize: 2,
      // highlight-end
    },
  },
});

响应式图片

当 管理面板设置中的 Responsive friendly upload 启用时，插件会生成以下响应式图片尺寸：

这些尺寸可在 /config/plugins 中覆盖：

JavaScript

module.exports = ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

TypeScript

export default ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

:::caution 断点更改仅适用于新图片，现有图片不会被调整大小，也不会生成新的尺寸。 :::

Sharp 配置

sharp 选项配置用于生成响应式图片格式的 sharp 图像处理库。调整这些设置有助于减少图像处理过程中的内存使用，这对于内存受限的环境特别有用。

默认值（cache: false、concurrency: 1）针对低内存使用进行了优化。对于可用内存更多的环境，你可以启用缓存并提高并发数，以提升图像处理性能：

JavaScript

module.exports = ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

TypeScript

export default ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

使用 {#usage}

使用该功能的路径： Media Library（媒体库）

Media Library（媒体库）显示应用中上传的所有资源，无论是通过 Media Library（媒体库）本身，还是通过 内容管理器（Content Manager）管理媒体字段时上传的。

上传到 Media Library（媒体库）的资源可以通过 内容管理器（Content Manager） 插入到内容类型（content-types）中。

界面概览

Media Library（媒体库）由以下区域组成：

• 左侧的文件夹树 > **提示：**此处原本是一个交互式组件（ScreenshotNumberReference），在静态 Markdown 中无法渲染。可参考原始在线文档查看对应内容。 列出 首页（Home） 和完整的文件夹层级（见 浏览文件夹）。
• 页面标题 > **提示：**此处原本是一个交互式组件（ScreenshotNumberReference），在静态 Markdown 中无法渲染。可参考原始在线文档查看对应内容。 命名你当前浏览的位置，即 首页（Home） 或某个文件夹名称，后跟它直接包含的文件数量，显示为例如 11 items（11 个项目）。子文件夹及其内容不计入，且筛选处于活动状态时该数字不会改变。
• 新建（New） 按钮 > **提示：**此处原本是一个交互式组件（ScreenshotNumberReference），在静态 Markdown 中无法渲染。可参考原始在线文档查看对应内容。 用于创建文件夹或上传资源（见 添加资源 和 添加文件夹）。
• 工具栏 > **提示：**此处原本是一个交互式组件（ScreenshotNumberReference），在静态 Markdown 中无法渲染。可参考原始在线文档查看对应内容。 横跨列表上方的整行。用它来筛选、搜索和排序列表（见 查找资源），并在网格视图和表格视图之间切换（见 切换视图）。
• 列表 > **提示：**此处原本是一个交互式组件（ScreenshotNumberReference），在静态 Markdown 中无法渲染。可参考原始在线文档查看对应内容。 显示当前位置的文件夹和资源。滚动时会加载更多资源。

列表中的每个文件夹和资源都有一个复选框用于选择它（见 选择项目）和一个 按钮（见 使用项目操作菜单）。Media Library（媒体库）将文件夹或资源称为 项目（item），多个控件使用了这个词。

与先前 Media Library（媒体库）相比有哪些变化：

Strapi v5.54.0 引入了焕新的 Media Library（媒体库）。下表突出了 UI 中的主要变化：

切换视图

列表以卡片网格或表格两种形式显示。点击工具栏中的 网格视图（Grid view） 或 表格视图（Table view） 进行切换。你的选择会被浏览器记住，供下次访问使用。

表格视图为每个项目显示 名称（Name）、创建日期（Creation date）、最后修改（Last modified） 和 大小（Size） 列，以及表头行中的 全选（Select all） 复选框。缺少说明文字或替代文本的资源会带有警告图标标记。

浏览文件夹 {#navigating-folders}

界面左侧的文件夹树列出了完整的文件夹层级。没有面包屑：文件夹树和页面标题告诉你所在位置。

• 点击文件夹树或列表中的文件夹名称，以显示其内容。
• 点击文件夹名称旁的 按钮，以展开或折叠其子文件夹。
• 点击 首页（Home），返回库的根目录。

Strapi 不强制限制最大文件夹深度。文件夹树会自动展开以显示你正在浏览的文件夹。

使用项目操作菜单 {#item-actions}

资源或文件夹的 按钮会打开一个仅作用于该项目本身的菜单，无论列表中还选中了什么。

对于资源，菜单提供：

• 替换媒体（Replace media）
• 复制媒体链接（Copy link to media）
• 下载媒体（Download media）
• 移动到文件夹（Move to folder）
• 删除（Delete）

对于文件夹，菜单提供：

• 复制文件夹链接（Copy link to folder）
• 重命名文件夹（Rename folder）
• 移动到文件夹（Move to folder）
• 删除文件夹（Delete folder）

使用右键菜单 {#right-click-menu}

在 Media Library（媒体库）的空白处点击右键，会打开一个与 新建（New） 按钮相同创建操作的菜单。它们作用于你当前正在浏览的文件夹：

• 新建文件夹（New folder）
• 文件上传（File upload）
• 通过 URL 上传文件（File upload from URL）

菜单在滚动列的任意位置打开：列表、最后一行下方的空白区域、标题旁页面标题带及其周围的留白。它在网格视图和表格视图中表现一致，通过 Escape 或点击其他地方可关闭。

任何你可以交互的元素都会保留你浏览器自身的菜单，因此在搜索字段中复制粘贴仍然有效。这包括 新建（New） 按钮、搜索、筛选、排序、视图切换和筛选标记，以及资源卡片、文件夹卡片、表格行和表格视图的列表头行。

添加资源

资源始终上传到你当前正在浏览的位置。上传前请导航到目标文件夹，或事后移动资源（见 移动资源与文件夹）。

在空文件夹中，以及在新项目中，列表会被一条 暂无资源（No assets yet） 消息取代，并带有一个 添加资源（Add assets） 按钮，该按钮会打开与 新建（New） > 文件上传（File upload） 相同的文件浏览器。

添加资源有 3 种方式：从你的计算机上传、拖放到 Media Library（媒体库）UI，或从 URL 上传。

通过新建按钮从计算机上传文件

1. 点击 Media Library（媒体库）右上角的 新建（New） 按钮。
2. 点击 文件上传（File upload）。
3. 在系统的文件浏览器中选择一个或多个文件并确认。

上传会立即开始，其进度在上传对话框中报告（见 跟踪上传进度）。

通过拖放从计算机上传文件

1. 从你的计算机将一个或多个文件拖到 Media Library（媒体库）上。
2. 检查 拖放到此处上传至（Drop here to upload to） 覆盖层中命名的目标文件夹。
3. 释放文件。

:::caution 从计算机拖放的文件始终落在你当前正在浏览的文件夹中，无论它们被拖到什么上面。将文件拖放到文件夹卡片上并不会将其上传到该文件夹内：请先导航进入该文件夹。将库中已有的项目拖到文件夹上确实会移动它（见 移动资源与文件夹）。 :::

通过 URL 上传文件

1. 点击 Media Library（媒体库）右上角的 新建（New） 按钮。
2. 点击 通过 URL 上传文件（File upload from URL）。
3. 在 导入自 URL（Import from URL） 对话框的 URL(s) 字段中，输入或粘贴最多 20 个 URL，每行一个。
4. 点击 上传（Upload）。

Strapi 会在服务器端下载每个文件并将其添加到当前文件夹。上传对话框会报告服务器端获取每个文件时的字节级进度：进度条在获取阶段实时推进，然后交接给上传步骤并完成。（v5.53.1+）

:::caution URL 必须使用 http 或 https 协议，且必须解析为可公开访问的地址。解析为私有或内部地址（如 localhost 或你自己网络上的地址）的 URL 会被拒绝，以防止服务器端请求伪造（server-side request forgery）。 :::

跟踪上传进度 {#upload-progress}

上传会在一个对话框中报告，该对话框列出批次中每个文件及其自身状态，例如排队中（Queued）、上传中…（Uploading...）或已上传（Uploaded）。该对话框在整个管理面板中都可用，而不仅在 Media Library（媒体库）中，因此你可以在批次上传时导航到 Strapi 的其他部分。

对话框可最小化为一行摘要，也可再次最大化。它提供 取消全部（Cancel all） 按钮（停止批次但保留已上传的文件）、重试（Retry） 按钮（重启你取消的文件），以及批次完成后出现的 关闭（Close） 按钮。在批次运行时拖入更多文件会将它们加入该批次。

:::caution 重试（Retry） 仅在取消后显示，且它只重启被取消的文件。自身失败的文件无法从对话框重试：请在其所在行阅读原因、修复问题，然后重新上传。 :::

默认情况下，文件一次上传一个。提高 concurrentUploadRequests 可并行上传多个文件。

使用 Strapi AI 自动生成元数据 {#ai-powered-metadata-generation}

（Growth 计划）

启用后，Strapi AI 会自动为上传到 Media Library（媒体库）的图片生成替代文本和说明文字，帮助你提升内容的可访问性和 SEO。上传对话框会报告每个文件的结果，例如 已上传 • 已生成元数据（Uploaded • Metadata generated） 或 上传完成 • 已跳过元数据生成（Upload complete • Metadata generation skipped）。

AI 元数据生成仅适用于 PNG、JPEG、WebP、HEIC 和 HEIF 图片。所有其他文件（包括 GIF、SVG 和 TIFF 图片）都会报告为已跳过。该功能默认启用，但如有需要在 Media Library 设置 中可禁用。

也可以为库中已存在的图片生成元数据，既可以从 Media Library 设置 为每张缺失的图片生成，也可以使用 创建元数据（Create metadata） 批量操作针对特定选择生成（见 批量生成元数据）。

查找资源

工具栏依次提供一个 筛选（Filter） 按钮、一个 搜索（Search） 字段和一个 排序（Sort） 按钮。搜索覆盖整个库，而筛选和排序应用于你正在浏览的位置。

搜索资源

在工具栏的 搜索（Search） 字段中键入内容，按名称查找资源和文件夹。

搜索覆盖整个库，而不仅仅是你正在浏览的文件夹，并且会同时返回文件夹和资源。页面标题变为 "你的词" 的搜索结果（Search results for "your term"），后跟找到的文件夹和资源数量。

要退出搜索，请点击搜索字段内的 清除（Clear） 按钮，在搜索字段中按下 Esc 键，或导航到文件夹树中的某个文件夹。

当搜索未返回任何内容时，列表会被一条 未找到结果（No results found） 消息取代，并带有一个 清除搜索（Clear search） 按钮。

筛选资源

提供 3 个筛选字段来缩小列表范围：

• 对于预设：恰好是（is exactly）、在过去（within the last）、不在过去（not within the last）
• 对于自定义日期范围：是（is）、不是（is not） | | 最后修改（Last modified） | 相对预设，从 1 天前到 1 年前 | 恰好是（is exactly）、在过去（within the last）、不在过去（not within the last） |

要筛选列表：

1. 点击工具栏中的 筛选（Filter） 按钮。
2. 点击一个筛选字段。
3. 点击一个或多个值。类型（Type） 列表保持打开状态，以便你可以勾选多个类型，标记会列出全部，例如 类型是 图片, 视频（Type is Picture, Video）。
4. （可选）对另一个字段重复上述操作。

筛选条件会组合，因此只显示符合每个筛选条件的项目。每个已应用的筛选条件会作为标记添加到工具栏下方。点击标记的条件或值部分可更改它，点击 按钮可移除该筛选。

当活动筛选未匹配任何内容时，列表会被一条 没有项目匹配当前筛选（No items matched current filters） 消息取代，并带有一个 清除筛选（Clear filters） 按钮，可移除全部筛选。工具栏中没有「全部清除」控件：只要筛选仍匹配到内容，就需逐个移除标记。

排序资源

点击工具栏中的 排序（Sort） 按钮可更改列表顺序。按钮标签始终命名当前活动规则，例如 排序：最近更新（Sort: Most recent updates）。

排序（Sort） 部分提供 6 个互斥规则：最早上传（Oldest uploads）、最近更新（Most recent updates，默认）、A 到 Z（A to Z）、Z 到 A（Z to A）、文件大小升序（File size ascending）和文件大小降序（File size descending）。

在表格视图中，还有一个额外的 文件夹（Folders） 部分，决定文件夹是分组在顶部（On top，默认），还是与文件混合（Mixed with files），后者情况下它们遵循活动排序规则。网格视图始终将文件夹分组在顶部，因此不显示该部分。

管理单个资源 {#managing-assets}

点击列表中的资源，可打开其位于界面右侧的详情面板。面板后方列表保持可见且可用。

面板组织如下：

• 资源的预览。图片会显示，视频和音频文件可使用浏览器自身控件播放，PDF 会内联渲染。任何其他文件类型会显示其图标和 无可用的预览（No preview available）。图片还会获得一个 裁剪（Crop） 按钮（见 裁剪图片和设置焦点区域）。
• 只读的 文件信息（File info） 部分，列出资源的 创建日期（Creation date）、最后更新（Last updated）、创建者（Created by）、大小（Size）、尺寸（Dimensions）（仅图片）、扩展名（Extension） 和 资源 ID（Asset ID）。
• 可编辑的 文件名（File name）、位置（Location）、说明文字（Caption） 和 替代文本（Alternative text） 字段。说明文字和替代文本可在任何文件类型上设置，不仅限于图片，当这 2 个字段为空时，其旁会显示警告。
• 底部一排仅图标的按钮： 删除此文件（Delete this file）、 复制链接（Copy link）、 下载（Download） 和 替换此文件（Replace this file），旁边是 保存更改（Save changes） 按钮。

编辑资源名称、说明文字和替代文本 {#editing-assets}

要重命名资源，或添加/更改其说明文字和替代文本：

1. 点击列表中的资源。
2. 更新 文件名（File name）、说明文字（Caption） 或 替代文本（Alternative text） 字段。
3. 点击 保存更改（Save changes）。

裁剪图片和设置焦点区域 {#cropping-images}

一个编辑器同时处理裁剪和焦点区域。焦点区域（也称为 focal point）会在你的前端裁剪或调整图片大小时，使图片最重要的部分保持可见。

1. 点击列表中的图片以打开其详情面板。
2. 点击预览上的 裁剪（Crop） 按钮。裁剪与焦点区域（Crop & Focus area） 编辑器打开。
3. 通过拖动矩形角落的手柄，或在编辑器面板的宽度和高度字段中键入精确值，定义裁剪区域。
4. （可选）点击 按钮锁定宽高比，使其同时调整两个维度。
5. 通过拖动裁剪矩形内的圆形，或在 X 和 Y 字段中键入精确值，定义焦点区域。
6. 保存你的更改：
   • 点击 应用（Apply） 裁剪原始资源。资源保持其 ID，因此已使用它的内容会更新。
   • 点击 另存为副本（Save as copy） 保留原始资源不变，并在同一文件夹中创建新资源。副本继承原始资源的说明文字和替代文本。

要不做任何更改离开编辑器，点击 取消（Cancel）。

替换资源文件

替换会交换资源背后的文件，同时保留资源本身，因此每个已指向它的内容条目继续正常工作。

1. 点击列表中的资源以打开其详情面板。
2. 点击 替换此文件（Replace this file） 按钮。
3. 在确认对话框中点击 继续（Continue）。
4. 在系统文件浏览器中选择新文件并确认。文件浏览器仅提供类型与当前资源匹配的文件。

下载资源与复制链接

1. 点击列表中的资源以打开其详情面板。
2. 点击 下载（Download） 按钮将文件保存到你的计算机，或点击 复制链接（Copy link） 按钮将其 URL 复制到剪贴板。

这两个操作也可从资源的 操作菜单中获得，即 复制媒体链接（Copy link to media） 和 下载媒体（Download media）。

删除资源

1. 点击列表中的资源以打开其详情面板。
2. 点击 删除此文件（Delete this file） 按钮。
3. 点击 确认（Confirm）。

资源也可以批量删除，与文件夹一起（见 批量删除项目）。

使用批量操作

批量操作应用于资源和文件夹的选择集。先选择项目，然后在批量操作栏中选择一个操作。

选择项目 {#selecting-items}

点击文件夹或资源的复选框以选择它。资源和文件夹可以一起选择。

以下快捷键可加快选择：

两个修饰键快捷键都作用于卡片或行本身。无论你按住哪个修饰键，点击文件名始终会打开详情面板。

在表格视图中，表头行的 全选（Select all） 复选框会选择当前显示的所有项目，并在已全选时清空选择。

选择一个项目会在界面底部显示批量操作栏。该栏报告已选择多少项目并提供批量操作。点击 清除选择（Clear selection） 可清空选择。

在网格视图和表格视图中，该栏还提供 全选（Select all） 按钮，选择当前显示的所有文件夹和资源。只会选择已加载的项目：进一步向下滚动列表，然后再次点击 全选（Select all） 以添加新加载的项目。与表格视图表头的复选框不同，该按钮在已全选时不会清空选择。

批量移动项目 {#bulk-move}

1. 选择要移动的资源和文件夹。
2. 点击批量操作栏中的 移动（Move） 按钮。
3. 在 将元素移动到（Move elements to） 对话框中，在 位置（Location） 列表中选择目标位置。库的根目录在那里列为 Media Library（媒体库），文件夹带有其完整路径，例如 品牌资源 / 标志（Brand assets / Logos）。项目已所在的文件夹，以及任何无法移动到的文件夹，都不会列出。
4. 点击 移动（Move）。

项目也可以通过拖放移动（见 移动资源与文件夹）。

批量删除项目 {#bulk-delete}

1. 选择要删除的资源和文件夹。
2. 点击批量操作栏中的 删除（Delete） 按钮。
3. 在对话框中点击 确认（Confirm）。

批量生成元数据 {#bulk-metadata}

（Growth 计划）

当 Strapi AI 启用时，批量操作栏中的 创建元数据（Create metadata） 按钮会为所选图片生成说明文字和替代文本。

1. 选择要描述的图片。
2. 点击批量操作栏中的 创建元数据（Create metadata） 按钮。

元数据一次最多可为 40 个资源生成。仅支持 PNG、JPEG、WebP、HEIC 和 HEIF 图片：所选文件夹会被忽略，所选任何其他类型的文件会报告为已跳过。

使用文件夹组织资源

Media Library（媒体库）中的文件夹可帮助你组织已上传的资源。从 Media Library（媒体库）中，可以创建新文件夹、移动资源和文件夹、重命名文件夹以及删除文件夹。要浏览它们，见 浏览文件夹。

:::caution 重命名文件夹（Rename folder）、移动到文件夹（Move to folder） 和 删除文件夹（Delete folder） 会显示给每个能看到该文件夹的用户，包括没有资源 更新（Update） 权限的用户。然后该操作会被服务器拒绝。 :::

添加文件夹

1. 导航到必须创建文件夹的位置。
2. 点击 Media Library（媒体库）右上角的 新建（New） 按钮。
3. 点击 新建文件夹（New folder）。
4. 在 文件夹名称（Folder name） 字段中键入名称。
5. 点击 创建文件夹（Create folder）。

移动资源与文件夹 {#moving-assets}

资源和文件夹可以通过 3 种方式移动：

• 通过拖放，一次几个项目。将资源或文件夹拖到列表中的某个文件夹上，或拖到文件夹树的某个文件夹上，包括 首页（Home）。在树中的文件夹上悬停片刻会展开它，这样你可以一个手势将项目放入子文件夹。拖动选择集中的一个项目会移动整个选择集。
• 使用 将元素移动到（Move elements to） 对话框，一次处理多个项目（见 批量移动项目）。它也可用于单个项目，即其 操作菜单中的 移动到文件夹（Move to folder）。
• 从资源的详情面板中，通过更改其 位置（Location） 字段（见 管理单个资源）。

重命名文件夹

1. 点击文件夹的 按钮。
2. 点击 重命名文件夹（Rename folder）。
3. 在 文件夹名称（Folder name） 字段中键入新名称。
4. 点击 保存（Save）。

删除文件夹

1. 点击文件夹的 按钮。
2. 点击 删除文件夹（Delete folder）。
3. 点击 确认（Confirm）。

文件夹也可以批量删除，与资源一起（见 批量删除项目）。

与 MCP 服务器的配合使用

连接到 Strapi MCP 服务器 的 AI 客户端可以通过专用工具浏览和管理 Media Library（媒体库）：3 个只读工具用于列出资源、返回单个资源和返回文件夹树，7 个写入工具用于更新资源元数据、移动和删除资源，以及创建、重命名、移动和删除文件夹（见 Media Library 工具）。

与 REST API 的配合使用

Media Library（媒体库）功能有一些可通过 Strapi 的 REST API 访问的端点：

• 使用 REST API 上传 — 了解如何使用 Strapi 的 REST API 通过你的代码上传文件。

在你的代码中使用公共资源 {#public-assets}

公共资源是你希望让外部世界可访问的静态文件（例如图片、视频、CSS 文件等）。

因为每个 API 可能需要提供静态资源，每个新的 Strapi 项目默认都包含一个名为 /public 的文件夹。位于此目录中的任何文件，如果请求的路径不匹配任何其他已定义的路由，并且匹配公共文件名（例如 /public/ 中名为 company-logo.png 的图片可通过 /company-logo.png URL 访问），则是可访问的。

:::caution 点文件（dotfiles）不会被暴露。这意味着每个以 . 开头的文件名，如 .htaccess 或 .gitignore，都不会被提供。 :::