媒体库
¥Media Library
媒体库是 Strapi 的功能,可显示 Strapi 应用中上传的所有资源并允许用户管理它们。
¥The Media Library is the Strapi feature that displays all assets uploaded in the Strapi application and allows users to manage them.
计划:免费功能。
角色和权限:角色 > 插件中的最低 "访问媒体库" 权限 - 上传。
激活:默认可用并激活。
环境:在开发和生产环境中均可用。
¥ Plan: Free feature.
Role & permission: Minimum "Access the Media Library" permission in Roles > Plugins - Upload.
Activation: Available and activated by default.
Environment: Available in both Development & Production environment.


配置
¥Configuration
媒体库的一些配置选项在管理面板中可用,一些通过你的 Strapi 项目的代码处理。
¥Some configuration options for the Media Library are available in the admin panel, and some are handled via your Strapi project's code.
管理面板配置
¥Admin panel configuration
在管理面板中,可以通过全局设置使用一些媒体库设置来管理上传资源的格式、文件大小和方向。也可以直接通过媒体库配置视图。
¥In the admin panel, some Media Library settings are available via the Global Settings to manage the format, file size, and orientation of uploaded assets. It is also possible, directly via the Media Library to configure the view.
配置设置
¥Configuring settings
配置功能的路径: 设置 > 全局设置 > 媒体库。
¥Path to configure the feature: Settings > Global Settings > Media Library.
-
定义你选择的新媒体库设置:
¥Define your chosen new Media Library settings:
设置名称 指示 默认值 响应式友好上传 启用此选项将生成上传资源的多种格式(小、中、大)。
每种格式的默认大小可以是 通过代码配置。真的 尺寸优化 启用此选项将减小图片尺寸并略微降低其质量。 真的 自动定向 启用此选项将根据 EXIF 方向标签自动旋转图片。 错误的 -
单击“保存”按钮。
¥Click on the Save button.


配置视图
¥Configuring the view
配置功能的路径: 媒体库
¥Path to configure the feature: Media Library
-
单击界面右侧文件夹和资源列表上方的 按钮。
¥Click on the button just above the list of folders and assets, on the right side of the interface.
-
按照以下说明配置媒体库视图:
¥Configure the Media Library view, following the instructions below:
设置名称 指示 每页条目数 使用下拉菜单定义每页默认显示的资源数量。 默认排序顺序 使用下拉菜单定义资源显示的默认顺序。在对媒体库中的资源进行排序时可以覆盖此操作。
这两种设置都是媒体库和内容管理器媒体上传模式的默认设置。这些设置在整个 Strapi 项目中对所有用户都是全局的。
¥Both settings are used as the defaults in the Media Library and in the Content Manager's media upload modal. These settings are global across the entire Strapi project for all users.


基于代码的配置
¥Code-based configuration
媒体库由上传包在后端服务器中提供支持,可以通过提供程序进行配置和扩展。
¥The Media Library is powered in the backend server by the Upload package, which can be configured and extended through providers.
其他提供商
¥Additional providers
默认情况下,Strapi 提供一个提供程序,可将文件上传到 Strapi 项目中的本地 public/uploads/
目录。如果你想将文件上传到其他位置,可以使用其他提供者。
¥By default Strapi provides a provider that uploads files to a local public/uploads/
directory in your Strapi project. Additional providers are available should you want to upload your files to another location.
Strapi 维护的提供商如下。单击卡片将重定向到他们的 Strapi 市场或 npm 页面:
¥The providers maintained by Strapi are the following. Clicking on a card will redirect you to their Strapi Marketplace or npm page:
Amazon S3
Official provider for file uploads to Amazon S3.
Cloudinary
Official provider for media management with Cloudinary.
Local
Default provider for storing files locally on the server.
当前页面上的基于代码的配置说明详细介绍了默认上传提供商的选项。如果使用其他提供商,请参阅该提供商文档中可用的配置参数。
¥Code-based configuration instructions on the present page detail options for the default upload provider. If using another provider, please refer to the available configuration parameters in that provider's documentation.
可用选项
¥Available options
使用默认上传提供程序时,可以在 config/plugins
文件 中的 upload.config
对象中声明以下特定配置选项。所有参数都是可选的:
¥When using the default upload provider, the following specific configuration options can be declared in an upload.config
object within the config/plugins
file. All parameters are optional:
范围 | 描述 | 类型 | 默认 |
---|---|---|---|
providerOptions.localServer | 将传递给 koa-static 的选项,在此基础上构建上传服务器(参见 本地服务器配置) | 目的 | * |
sizeLimit | 最大文件大小(以字节为单位)(参见 最大文件大小) | 整数 | 209715200 (200 MB,以字节为单位,即 200 x 1024 x 1024 字节) |
breakpoints | 允许在 "响应式友好上传" 选项设置为 true 时覆盖生成响应式图片的断点大小(参见 响应式图片) | 目的 | { large: 1000, medium: 750, small: 500 } |
Upload 请求超时在服务器选项中定义,而不是在 Upload 插件选项中定义,因为它不是特定于 Upload 插件的,而是应用于整个 Strapi 服务器实例(参见 上传请求超时)。
¥The Upload request timeout is defined in the server options, not in the Upload plugin options, as it's not specific to the Upload plugin but is applied to the whole Strapi server instance (see upload request timeout).
自定义配置示例
¥Example custom configuration
以下是使用默认上传提供程序时上传插件的自定义配置示例:
¥The following is an example of a custom configuration for the Upload plugin when using the default upload provider:
- JavaScript
- TypeScript
module.exports = ({ env })=>({
upload: {
config: {
providerOptions: {
localServer: {
maxage: 300000
},
},
sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
breakpoints: {
xlarge: 1920,
large: 1000,
medium: 750,
small: 500,
xsmall: 64
},
},
},
});
export default () => ({
upload: {
config: {
providerOptions: {
localServer: {
maxage: 300000
},
},
sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
breakpoints: {
xlarge: 1920,
large: 1000,
medium: 750,
small: 500,
xsmall: 64
},
},
},
})
本地服务器
¥Local server
默认情况下,Strapi 接受本地上传文件的 localServer
配置。这些将作为 koa-static 的选项传递。
¥By default Strapi accepts localServer
configurations for locally uploaded files. These will be passed as the options for koa-static .
你可以通过创建或编辑 /config/plugins
文件 来提供它们。以下示例设置 max-age
标头:
¥You can provide them by creating or editing the /config/plugins
file. The following example sets the max-age
header:
- JavaScript
- TypeScript
module.exports = ({ env })=>({
upload: {
config: {
providerOptions: {
localServer: {
maxage: 300000
},
},
},
},
});
export default ({ env }) => ({
upload: {
config: {
providerOptions: {
localServer: {
maxage: 300000
},
},
},
},
});
最大文件大小
¥Max file size
负责解析请求的 Strapi 中间件需要配置为支持大于默认值 200MB 的文件大小。除了传递给 sizeLimit
的上传包的提供程序选项之外,还必须执行此操作。
¥The Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 200MB. This must be done in addition to provider options passed to the Upload package for sizeLimit
.
你可能还需要调整任何上游代理、负载平衡器或防火墙,以允许更大的文件大小。例如,Nginx 有一个名为 client_max_body_size
的配置设置必须进行调整,因为它的默认值只有 1mb。
¥You may also need to adjust any upstream proxies, load balancers, or firewalls to allow for larger file sizes. For instance, Nginx has a configuration setting called client_max_body_size
that must be adjusted, since its default is only 1mb.
上传包使用的中间件是 body
中间件。你可以通过在 /config/middlewares
文件中设置配置直接将配置传递给中间件:
¥The middleware used by the Upload package is the body
middleware. You can pass configuration to the middleware directly by setting it in the /config/middlewares
file:
- JavaScript
- TypeScript
module.exports = [
// ...
{
name: "strapi::body",
config: {
formLimit: "256mb", // modify form body
jsonLimit: "256mb", // modify JSON body
textLimit: "256mb", // modify text body
formidable: {
maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
},
},
},
// ...
];
export default [
// ...
{
name: "strapi::body",
config: {
formLimit: "256mb", // modify form body
jsonLimit: "256mb", // modify JSON body
textLimit: "256mb", // modify text body
formidable: {
maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
},
},
},
// ...
];
除了中间件配置外,你还可以在 /config/plugins 文件 中传递 sizeLimit
(以字节为单位的整数):
¥In addition to the middleware configuration, you can pass the sizeLimit
, which is an integer in bytes, in the /config/plugins file:
- JavaScript
- TypeScript
module.exports = {
// ...
upload: {
config: {
sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
}
}
};
export default {
// ...
upload: {
config: {
sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
}
}
};
上传请求超时
¥Upload request timeout
默认情况下,strapi.server.httpServer.requestTimeout
的值设置为 330 秒。这包括上传。
¥By default, the value of strapi.server.httpServer.requestTimeout
is set to 330 seconds. This includes uploads.
为了使互联网连接速度慢的用户能够上传大文件,可能需要增加此超时限制。建议的方法是设置 config/servers
文件 中的 http.serverOptions.requestTimeout
参数。
¥To make it possible for users with slow internet connection to upload large files, it might be required to increase this timeout limit. The recommended way to do it is by setting the http.serverOptions.requestTimeout
parameter in the config/servers
file.
另一种方法是在 Strapi 启动之前运行的 bootstrap
函数 中设置 requestTimeout
值。这在需要以编程方式更改的情况下很有用 - 例如,暂时禁用并重新启用它:
¥An alternate method is to set the requestTimeout
value in the bootstrap
function that runs before Strapi gets started. This is useful in cases where it needs to change programmatically—for example, to temporarily disable and re-enable it:
- JavaScript
- TypeScript
module.exports = {
//...
bootstrap({ strapi }) {
// Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
},
};
export default {
//...
bootstrap({ strapi }) {
// Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
},
};
响应式图片
¥Responsive Images
启用 Responsive friendly upload
管理面板设置 后,插件将生成以下响应式图片大小:
¥When the Responsive friendly upload
admin panel setting is enabled, the plugin will generate the following responsive image sizes:
名称 | 最大维度 |
---|---|
large | 1000 像素 |
medium | 750 像素 |
small | 500 像素 |
这些尺寸可以在 /config/plugins
中被覆盖:
¥These sizes can be overridden in /config/plugins
:
- JavaScript
- TypeScript
module.exports = ({ env }) => ({
upload: {
config: {
breakpoints: {
xlarge: 1920,
large: 1000,
medium: 750,
small: 500,
xsmall: 64
},
},
},
});
export default ({ env }) => ({
upload: {
config: {
breakpoints: {
xlarge: 1920,
large: 1000,
medium: 750,
small: 500,
xsmall: 64
},
},
},
});
断点更改仅适用于新图片,现有图片不会调整大小或生成新尺寸。
¥Breakpoint changes will only apply to new images, existing images will not be resized or have new sizes generated.
用法
¥Usage
使用功能的路径: 媒体库
¥Path to use the feature: Media Library
媒体库显示应用中上传的所有资源,可以通过 媒体库本身或通过 内容管理器在管理媒体字段时上传。
¥The Media Library displays all assets uploaded in the application, either via the Media Library itself or via the Content Manager when managing a media field.
上传到媒体库的资源可以使用 内容管理者 插入到内容类型中。
¥Assets uploaded to the Media Library can be inserted into content-types using the Content Manager.


从媒体库中,可以:
¥From the Media Library, it is possible to:
-
上传新资源(参见 添加资源)或创建新文件夹(参见 使用文件夹组织资源)1,
¥upload a new asset (see adding assets) or create a new folder (see organizing assets with folders) 1,
-
对资源和文件夹进行排序或设置过滤器 2 以更轻松地查找资源和文件夹,
¥sort the assets and folders or set filters 2 to find assets and folders more easily,
-
在列表视图 和网格视图 之间切换以显示资源,访问设置 至 配置视图,并进行文本搜索 3 以查找特定资源或文件夹,
¥toggle between the list view and the grid view to display assets, access settings to configure the view, and make a textual search 3 to find a specific asset or folder,
-
并查看、浏览和管理文件夹 4。
¥and view, navigate through, and manage folders 4.
单击用户界面右侧的搜索图标 以使用文本搜索并更快地找到你的资源或文件夹之一!
¥Click the search icon on the right side of the user interface to use a text search and find one of your assets or folders more quickly!
添加资源
¥Adding assets
List of media types and extensions supported by the Media Library
媒体类型 | 支持的扩展 |
---|---|
图片 | * JPEG - PNG - GIF - SVG - TIFF - ICO - DVU |
视频 | * MPEG - MP4 - MOV (Quicktime) - WMV - AVI - FLV |
声音的 | * MP3 - WAV - OGG |
文件 | * CSV - ZIP - XLS、XLSX - JSON |
-
单击媒体库右上角的添加新资源按钮。
¥Click the Add new assets button in the upper right corner of the Media Library.
-
选择是要从计算机还是从 URL 上传新资源:
¥Choose whether you want to upload the new asset from your computer or from an URL:
-
从计算机上,直接拖放资源或浏览系统上的文件,
¥from the computer, either drag & drop the asset directly or browse files on your system,
-
从 URL 中,在 URL 字段中键入或复制并粘贴 URL,确保多个 URL 用回车符分隔,然后单击“下一步”。
¥from an URL, type or copy and paste an URL(s) in the URL field, making sure multiple URLs are separated by carriage returns, then click Next.
-
-
(可选)单击编辑按钮 查看资源元数据并为资源定义文件名、替代文本和标题(参见 管理个人资源)。
¥(optional) Click the edit button to view asset metadata and define a File name, Alternative text and a Caption for the asset (see Managing individual assets).
-
(可选)通过单击“添加新资源”并返回步骤 2 来添加更多资源。
¥(optional) Add more assets by clicking Add new assets and going back to step 2.
-
单击将资源上传到库。
¥Click on Upload assets to the library.


管理个人资源
¥Managing individual assets
媒体库允许管理资源,包括修改资源的文件详细信息和位置、下载和复制资源文件的链接以及删除资源。图片文件也可以被裁剪。
¥The Media Library allows managing assets, which includes modifying assets' file details and location, downloading and copying the link of the assets file, and deleting assets. Image files can also be cropped.
编辑资源
¥Editing assets
单击资源的编辑 按钮打开 "细节" 窗口,其中提供所有可用的资源管理选项。
¥Click on the edit button of an asset to open up the "Details" window, where all the available asset management options are available.


-
在左侧,资源预览上方,控制按钮 1 允许执行各种操作:
¥On the left, above the preview of the asset, control buttons 1 allow performing various actions:
-
点击删除按钮 删除资源,
¥click on the delete button to delete the asset,
-
点击下载 按钮 下载资源,
¥click on the download button to download the asset,
-
点击复制链接按钮 将资源链接复制到剪贴板,
¥click on the copy link button to copy the asset's link to the clipboard,
-
或者,单击裁剪按钮 进入图片的裁剪模式(参见 裁剪图片)。
¥optionally, click on the crop button to enter cropping mode for the image (see Cropping images).
-
-
在右侧,资源的元数据显示在窗口顶部 2,下面的字段可用于更新资源 3 的文件名、替代文本、标题和位置(参见 使用文件夹组织资源)。
¥On the right, meta data for the asset is displayed at the top of the window 2 and the fields below can be used to update the File name, Alternative text, Caption and Location (see Organizing assets with folders) for the asset 3.
-
在底部,可以使用替换媒体按钮 4 替换资源文件,但保留其他可编辑字段的现有内容,并使用完成按钮确认对字段的任何更新。
¥At the bottom, the Replace Media button 4 can be used to replace the asset file but keep the existing content of the other editable fields, and the Finish button is used to confirm any updates to the fields.
转移资源
¥Moving assets
-
点击要移动的资源的编辑按钮。
¥Click on the edit button for the asset to be moved.
-
在弹出的窗口中,单击“位置”字段并从下拉列表中选择其他文件夹。
¥In the window that pops up, click the Location field and choose a different folder from the drop-down list.
-
单击保存以确认。
¥Click Save to confirm.
资源也可以从媒体库的主视图移动到其他文件夹(参见 使用文件夹组织资源)。这包括同时移动多个资源的能力。
¥Assets can also be moved to other folders from the main view of the Media Library (see Organizing assets with folders). This includes the ability to move several assets simultaneously.
裁剪图片
¥Cropping images
-
点击要裁剪的资源的编辑按钮。
¥Click on the edit button for the asset to be cropped.
-
在弹出的窗口中,单击裁剪按钮 进入裁剪模式。
¥In the window that pops up, click the crop button to enter cropping mode.
-
使用角落中的句柄裁剪图片以调整框架大小。框架也可以通过拖放来移动。
¥Crop the image using handles in the corners to resize the frame. The frame can also be moved by drag & drop.
-
单击裁剪 按钮验证新尺寸,并选择裁剪原始资源或复制和裁剪资源(即创建具有新尺寸的副本,同时保持原始资源不变)。或者,单击停止裁剪 按钮取消并退出裁剪模式。
¥Click the crop button to validate the new dimensions, and choose either to crop the original asset or to duplicate & crop the asset (i.e. to create a copy with the new dimensions while keeping the original asset untouched). Alternatively, click the stop cropping button to cancel and quit cropping mode.
-
单击“完成”保存对文件的更改。
¥Click Finish to save changes to the file.
删除资源
¥Deleting assets
-
点击要删除的资源的编辑按钮。
¥Click on the edit button for the asset to be deleted.
-
在弹出的窗口中,单击资源预览上方控制按钮栏中的删除按钮 。
¥In the window that pops up, click the delete button in the control buttons bar above the asset's preview.
-
单击确认。
¥Click Confirm.
还可以从媒体库的主视图中单独或批量删除资源。通过单击左上角的复选框选择资源,然后单击窗口顶部、过滤器和排序选项下方的删除图标 。
¥Assets can also be deleted individually or in bulk from the main view of the Media Library. Select assets by clicking on their checkbox in the top left corner, then click the Delete icon at the top of the window, below the filters and sorting options.
使用文件夹组织资源
¥Organizing assets with folders
媒体库中的文件夹可帮助你组织上传的资源。文件夹位于媒体库视图的顶部,或者在使用 内容管理者 时可从媒体字段弹出窗口访问。
¥Folders in the Media Library help you organize uploaded assets. Folders sit at the top of the Media Library view or are accessible from the Media field popup when using the Content Manager.
在媒体库中,可以查看文件夹列表并浏览文件夹内容、创建新文件夹、编辑现有文件夹、将资源移动到文件夹以及删除文件夹。
¥From the Media Library, it is possible to view the list of folders and browse a folder's content, create new folders, edit an existing folder, move assets to a folder, and delete a folder.
文件夹遵循资源的权限系统(参见 用户和权限功能)。目前还无法为文件夹定义特定权限。
¥Folders follow the permission system of assets (see Users & Permissions feature). It is not yet possible to define specific permissions for a folder.
默认情况下,媒体库显示在根级别创 建的文件夹和资源。单击文件夹将导航到该文件夹,并显示以下元素:
¥By default, the Media Library displays folders and assets created at the root level. Clicking a folder navigates to this folder, and displays the following elements:
-
文件夹标题和导航到父文件夹的面包屑 1
¥the folder title and breadcrumbs to navigate to a parent folder 1
-
当前文件夹包含的子文件夹 2
¥the subfolders 2 the current folder contains
-
此文件夹中的所有资源 3
¥all assets 3 from this folder


从这个专用文件夹视图,可以像在主媒体库中一样管理、过滤、排序和搜索文件夹和资源。
¥From this dedicated folder view, folders and assets can be managed, filtered, sorted and searched just like from the main Media Library.
要导航回上一级的父文件夹,请使用界面顶部的“后退”按钮。
¥To navigate back to the parent folder, one level up, use the Back button at the top of the interface.
面包屑导航还可用于返回父文件夹:单击文件夹名称可直接跳转到该文件夹,或单击 3 个点 /img.
并从下拉列表中选择父文件夹。
¥The breadcrumb navigation can also be used to go back to a parent folder: click on a folder name to directly jump to it or click on the 3 dots /img.
and select a parent folder from the drop-down list.
添加文件夹
¥Adding folders
-
单击媒体库界面右上角的添加新文件夹。
¥Click on Add new folder in the upper right of the Media Library interface.
-
在弹出的窗口中,在名称字段中输入新文件夹的名称。
¥In the window that pops up, type a name for the new folder in the Name field.
-
(可选)在位置下拉列表中,选择新文件夹的位置。默认位置是活动文件夹。
¥(optional) In the Location drop-down list, choose a location for the new folder. The default location is the active folder.
-
单击“创建”。
¥Click Create.
文件夹层次结构的深度没有限制,但请记住,可能需要一些努力才能到达深层嵌套的子文件夹,因为媒体库当前没有视觉层次结构指示。使用用户界面右侧的 搜索文件可能是查找所需资源的更快替代方法。
¥There is no limit to how deep your folders hierarchy can go, but bear in mind it might take some effort to reach a deeply nested subfolder, as the Media Library currently has no visual hierarchy indication. Searching for files using the on the right side of the user interface might be a faster alternative to finding the asset you are looking for.
将资源移动到文件夹
¥Moving assets to a folder
可以从媒体库的根视图或专用文件夹的任何视图将资源和文件夹移动到另一个文件夹。
¥Assets and folders can be moved to another folder from the root view of the Media Library or from any view for a dedicated folder.
-
通过单击文件夹名称左侧的复选框或单击资源本身,选择要移动的资源和文件夹。
¥Select assets and folder to be moved, by clicking the checkbox on the left of the folder name or clicking the asset itself.
-
点击界面顶部的 移动按钮。
¥Click the Move button at the top of the interface.
-
在“将元素移动到”弹出窗口中,从“位置”下拉列表中选择新文件夹。
¥In the Move elements to pop-up window, select the new folder from the Location drop-down list.
-
单击移动。
¥Click Move.


编辑文件夹
¥Editing folders
创建后,可以重命名、移动或删除文件夹。
¥Once created, a folder can be renamed, moved or deleted.
-
在媒体库的文件夹部分,将鼠标悬停在要编辑的文件夹上,然后单击其编辑按钮 。
¥In the Folders part of the Media library, hover the folder to be edited and click its edit button .
-
在弹出的窗口中,分别使用名称字段和位置下拉列表更新名称和位置。
¥In the window that pops up, update the name and location with the Name field and Location drop-down list, respectively.
-
单击“保存”。
¥Click Save.
删除文件夹
¥Deleting folders
删除文件夹可以从媒体库的文件夹列表中完成,也可以在编辑单个文件夹时完成。
¥Deleting a folder can be done either from the list of folders of the Media Library, or when editing a single folder.
-
单击文件夹名称左侧的复选框。可以选择多个文件夹。
¥Click the checkbox on the left of the folder name. Multiple folders can be selected.
-
单击文件夹列表上方的 删除按钮。
¥Click the Delete button above the Folders list.
-
在确认对话框中,单击确认。
¥In the Confirmation dialog, click Confirm.
编辑时也可以删除单个文件夹:将鼠标悬停在文件夹上,单击其编辑图标 ,然后在弹出的窗口中单击删除文件夹按钮并确认删除。
¥A single folder can also be deleted when editing it: hover the folder, click on its edit icon , and in the window that pops up, click the Delete folder button and confirm the deletion.
使用 REST API
¥Usage with the REST API
媒体库功能有一些可以通过 Strapi 的 REST API 访问的端点:
¥The Media Library feature has some endpoints that can accessed through Strapi's REST API: