媒体库
🌐 Media Library
Page summary:媒体库集中管理所有上传的资源，提供搜索、过滤和文件夹组织功能。本说明文档包括供应商选项、上传工作流程，以及在内容中插入媒体的说明。
媒体库是 Strapi 的一个功能，它显示在 Strapi 应用中上传的所有资源，并允许用户进行管理。
配置
🌐 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.
配置设置
🌐 Configuring settings
配置此功能的路径： 设置 > 全局设置 > 媒体库。
-
定义你选择的新媒体库设置：
| 设置名称 | 说明 | 默认值 | | -------------------------- | ----------------------- |---------------| | 上传时自动生成 AI 字幕和替代文本！ | 启用此选项将开启 AI 驱动的元数据生成 GrowthThis feature is available with a Growth plan. EnterpriseThis feature is available with an Enterprise plan. | 已启用 | | 响应式友好上传 | 启用此选项将为上传的资源生成多种格式（小、中、大）。
每种格式的默认大小可以通过 代码进行配置。 | 是 | | 尺寸优化 | 启用此选项将减小图片大小，并略微降低其质量。 | 是 | | 自动方向 | 启用此选项将根据 EXIF 方向标签自动旋转图片。 | 否 | -
点击 保存 按钮。
当你的图库中的图片缺少标题或替代文本时，AI 元数据设置会报告缺失的数量，并提供一个生成元数据按钮，后台生成缺失的元数据。请检查结果，AI 也可能会出错。
🌐 When images in your library lack a caption or an alternative text, the AI metadata setting reports how many, and offers a Generate metadata button to generate the missing metadata in the background. Please review the results, AI can make mistakes.
基于代码的配置
🌐 Code-based configuration
媒体库由上传包在后端服务器中提供支持，可以通过提供程序进行配置和扩展。
🌐 The Media Library is powered in the backend server by the Upload package, which can be configured and extended through providers.
恢复以前的媒体库
🌐 Restoring the previous Media Library
5.54.0+本页描述的媒体库是自 Strapi v5.54.0 起的默认界面。要恢复以前的界面，请在 config/features 文件 中将 useLegacyMediaLibrary 属性设置为 true：
🌐 The Media Library described on this page is the default UI since Strapi v5.54.0. To restore the previous interface, set the useLegacyMediaLibrary property to true in the config/features file:
- JavaScript
- TypeScript
module.exports = ({ env }) => ({
useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});
export default ({ env }) => ({
useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});
从服务器代码中，用 strapi.features.isEnabled('useLegacyMediaLibrary') 读取这个配置设置。
🌐 From server code, read this configuration setting with strapi.features.isEnabled('useLegacyMediaLibrary').
提供者
🌐 Providers
媒体库支持供应商添加来自各种第三方的上传支持。
🌐 The Media Library supports providers to add upload support from various third parties.
Strapi 维护的提供者如下。点击卡片将重定向到带有配置示例的文档页面：
🌐 The providers maintained by Strapi are the following. Clicking on a card will redirect you to a docs page with a configuration example:
如果你需要安装其他提供商或创建自己的提供商，请参考以下指南：
🌐 If you need to install other providers or create your own, please refer to the following guide:
本页面上的基于代码的配置说明详细列出了默认上传提供商的选项。如果使用其他提供商，请参阅该提供商文档中可用的配置参数。
🌐 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.
私有存储提供商
🌐 Private storage providers
当配置的提供者是私有的（例如，带有 ACL: 'private' 的 S3 存储桶）时，Strapi 返回的每个文件 URL 都是一个会在 signedUrlExpires 后过期的签名 URL。媒体字段在每次读取时都会重新签名，但富文本和区块字段会直接在它们的值中嵌入 URL。
🌐 When the configured provider is private (for example, an S3 bucket with ACL: 'private'), every file URL Strapi returns is a signed URL that expires after signedUrlExpires. Media fields are re-signed on every read, but richtext and blocks fields embed the URL directly in their value.
Strapi 会在数据库中存储 richtext 和 blocks 字段的未签名 URL，每次在管理面板或者通过 REST 和 Document Service API 读取条目时都会重新签名。这同样适用于嵌套在组件和动态区域中的 richtext 和 blocks 属性。在这种行为引入之前写入的行，如果仍然保存着已签名的 URL，会在下次应用启动时自动重写。
🌐 Strapi stores the unsigned URL for richtext and blocks fields in the database, and signs it again each time the entry is read, in the admin panel and through the REST and Document Service APIs. This also applies to richtext and blocks attributes nested in components and dynamic zones. Rows written before this behavior was introduced, which still hold a signed URL, are rewritten automatically the next time the application starts.
使用每文件 path 提供商选项上传的文件不能从富文本或区块字段重新签名：URL 被识别为属于该提供商，但仅凭 URL 无法重建存储键，并且签名链接会返回 403 错误。媒体字段也有同样的限制。
🌐 A file uploaded with a per-file path provider option cannot be re-signed from a richtext or blocks field: the URL is recognized as belonging to the provider, but its storage key cannot be rebuilt from the URL alone, and the signed link returns a 403 error. Media fields have the same limitation.
可用选项
🌐 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 | 文件的最大 大小（字节）（参见 最大文件大小） | 整数 | 1000000000(1 GB 的字节数) |
breakpoints | 当“响应式友好上传”选项设置为 true 时，允许你覆盖生成响应式图片的断点尺寸（参见 响应式图片） | 对象 | { large: 1000, medium: 750, small: 500 } |
sharp | 配置 sharp 图片处理选项（参见 sharp 配置） | 对象 | { cache: false, concurrency: 1 } |
security | 配置上传文件的验证规则以增强媒体安全（参见 security） | 对象 | - |
concurrentUploadRequests | 管理面板并行上传到服务器的文件数量（参见 并发文件上传）。必须是大于等于 1 的整数。 | 整数 | 1 |
concurrentUploadSize | 服务器在单次上传请求中并行处理的文件数量（参见 并发文件上传）。必须是整数，且 >= 1。 | 整数 | 1 |
- 上传请求超时是在服务器选项中定义的，而不是在上传插件选项中，因为它不是上传插件特有的，而是应用于整个 Strapi 服务器实例（参见 上传请求超时）。
- 如果你希望覆盖图片功能以生成自定义文件名，请参考 Plugins 扩展 文档。
示例自定义配置
🌐 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
},
sharp: {
cache: true,
concurrency: 4,
},
security: {
allowedTypes: ['image/*', 'application/*'],
deniedTypes: ['application/x-sh', 'application/x-dosexec']
},
concurrentUploadSize: 5,
},
},
});
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
},
sharp: {
cache: true,
concurrency: 4,
},
security: {
allowedTypes: ['image/*', 'application/*'],
deniedTypes: ['application/x-sh', 'application/x-dosexec']
},
concurrentUploadSize: 5,
},
},
})
本地服务器
🌐 Local server
默认情况下，Strapi 接受用于本地上传文件的 localServer 配置。这些将作为 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 Cloud 上，上传大小限制是在基础设施层面强制执行的。无法通过 strapi::body 中间件配置提高。有关每个计划的值以及基于内存的图片上传建议，请参见 Strapi Cloud 的上传大小限制。
🌐 On Strapi Cloud, upload size limits are enforced at the infrastructure level. They cannot be raised via the strapi::body middleware config. See Upload size limits for Strapi Cloud for per-plan values and the memory-based recommendation for image uploads.
负责解析请求的 Strapi 中间件需要配置以支持大于默认 1 GB 的文件大小。这必须在传递给 sizeLimit 的 Upload 包的提供者选项之外进行。
🌐 The Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 1 GB. This must be done in addition to provider options passed to the Upload package for sizeLimit.
你可能还需要调整任何上游代理、负载均衡器或防火墙以允许更大的文件大小。例如， Nginx 有一个名为 client_max_body_size 的配置设置必须进行调整，因为其默认值仅为 1MB。
上传包使用的中间件是 the body middleware。你可以通过在 /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
}
}
};
安全
🌐 Security
上传插件根据文件的实际 MIME 类型而不是声明的文件扩展名来验证文件。只有符合定义的安全规则的文件才会被上传。
🌐 The Upload plugin validates files based on their actual MIME type rather than the declared file extension. Only files matching the defined security rules are uploaded.
security 配置提供了两个选项：allowedTypes 或 deniedTypes，它们让你可以控制哪些文件类型可以或不能被上传。
🌐 The security configuration provides 2 options: allowedTypes or deniedTypes, which let you control which file types can or cannot be uploaded.
使用 create-strapi-app 脚手架创建的应用在生成的 config/plugins.* 文件中包含一个预配置的 security 块。完整列表请参见下面的 create-strapi-app 生成的安全默认值 详细信息块。
🌐 Apps scaffolded with create-strapi-app include a pre-configured security block in the generated config/plugins.* file. See the Security defaults generated by create-strapi-app details block below for the full lists.
由 create-strapi-app 生成的安全默认设置：
新项目将这两个列表声明为独立变量，并将它们与其他生成的插件配置一起传递给 upload 插件：
🌐 New projects declare the 2 lists as separate variables and pass them to the upload plugin, alongside the other generated plugin configuration:
- JavaScript
- TypeScript
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,
},
},
},
});
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 上传
🌐 SVG uploads
自从 Strapi 5.52.2+ 起，image/svg+xml 是由 create-strapi-app 生成的 deniedTypes 的一部分，所以即使 SVG 符合 allowedTypes 中的 image/* 通配符，也会被拒绝上传。显式的 deniedTypes 条目总是优先于 allowedTypes 中的通配符。
SVG 文件可以嵌入浏览器可执行的内容，比如脚本和事件处理器，这就是为什么默认会被拒绝。这只影响新生成的项目。现有项目会保持当前配置，除非你自己添加相同的条目。
🌐 SVG files can embed browser-active content such as scripts and event handlers, which is why they are denied by default. This affects newly generated projects only. Existing projects keep their current configuration unless you add the same entry yourself.
要接受 SVG 上传，请从你的 config/plugins.* 文件中的 deniedTypes 删除 image/svg+xml（参见 security）。将生成的文件托管在与应用不共享 cookies 或本地存储的域名上，或者使用 Content-Disposition: attachment 头，这样上传的 SVG 就无法在你的网站上下文中运行脚本。
🌐 To accept SVG uploads, remove image/svg+xml from deniedTypes in your config/plugins.* file (see security). Serve the resulting files from a domain that does not share cookies or local storage with your application, or with a Content-Disposition: attachment header, so an uploaded SVG cannot run scripts in the context of your site.
你可以单独使用 allowedTypes 和 deniedTypes，也可以一起使用，以微调接受哪些文件。文件必须符合允许的类型，并且不得符合任何拒绝的类型。如果你在 allowedTypes 中使用例如 * 的通配符，你可以通过在 deniedTypes 中指定例外来缩小验证范围。
🌐 You can use allowedTypes and deniedTypes separately or together to fine-tune which files are accepted. Files must match an allowed type and must not match any denied type. If you use a wildcard like * in allowedTypes, you can narrow down the validation by specifying exceptions in deniedTypes.
模糊 MIME 类型的文件类型检测
🌐 File type detection for ambiguous MIME types
当浏览器为文件报告通用 MIME 类型（比如 application/octet-stream）时，Strapi 的媒体库会通过检查文件的实际内容字节来进行文件类型检测。这可以确保文件分类和过滤的准确性，尤其是像 Windows 系统上的 .mov 文件，浏览器经常会把它们报告为通用 MIME 类型。
🌐 When browsers report generic MIME types for files (such as application/octet-stream), Strapi's Media Library performs file-type detection by examining the file's actual content bytes. This ensures accurate file classification and filtering, particularly for formats like .mov files on Windows systems, which are often reported with generic MIME types by the browser.
文件类型检测用于：
🌐 The file type detection is used for:
- 在媒体库预览和网格中分类媒体
- 在内容管理器中验证媒体字段约束（例如
allowedTypes: ['video/*']）
服务器仍然是安全边界。虽然管理面板会在客户端进行文件类型检测以提升用户体验，但后台会在存储之前验证文件的 MIME 类型。这意味着即使浏览器最初错误地识别了文件类型，服务器也会检测到正确的 MIME 类型并进行存储。
🌐 The server remains the security boundary. While the admin panel performs client-side file type detection for better UX, the backend validates the file's MIME type before storage. This means that even if the browser initially misidentifies a file type, the correct MIME type is detected and stored on the server.
你可以通过创建或编辑 /config/plugins 文件 来提供它们。以下是如何结合 allowedTypes 和 deniedTypes 的示例：
🌐 You can provide them by creating or editing the /config/plugins file. The following is an example of how to combine allowedTypes and deniedTypes:
- JavaScript
- TypeScript
module.exports = {
// ...
upload: {
config: {
security: {
allowedTypes: ['image/*', 'application/*'],
deniedTypes: ['application/x-sh', 'application/x-dosexec']
},
}
}
};
export default {
// ...
upload: {
config: {
security: {
allowedTypes: ['image/*', 'application/*'],
deniedTypes: ['application/x-sh', 'application/x-dosexec']
},
}
}
};
上传请求超时
🌐 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;
},
};
并发文件上传
🌐 Concurrent file uploads
批量上传由两个选项控制，这两个选项设置 Strapi 同时处理多少文件：
🌐 Bulk uploads are controlled by 2 options that set how many files Strapi handles at the same time:
| 参数 | 描述 | 类型 | 默认值 |
|---|---|---|---|
concurrentUploadRequests | 管理面板同时上传到服务器的文件数量。 | 整数 | 1 |
concurrentUploadSize | 服务器在单个上传请求中同时处理的文件数量。 | 整数 | 1 |
两者默认都是 1，所以文件会一次上传和处理一个。提高 concurrentUploadRequests 会让管理面板同时发送更多上传请求，而提高 concurrentUploadSize 会让服 务器在单个请求中一次处理更多文件。这两者都可以加快批量上传，但会增加服务器负载。
🌐 Both default to 1, so files are uploaded and processed one at a time. Raising concurrentUploadRequests makes the admin panel send more upload requests at the same time, and raising concurrentUploadSize makes the server process more files at once within a single request. Both speed up bulk uploads at the cost of higher load on the server.
- JavaScript
- TypeScript
module.exports = () => ({
upload: {
config: {
concurrentUploadRequests: 4,
concurrentUploadSize: 2,
},
},
});
export default () => ({
upload: {
config: {
concurrentUploadRequests: 4,
concurrentUploadSize: 2,
},
},
});
两个值都必须是大于或等于 1 的整数。任何其他值，包括 0，都会阻止 Strapi 启动。
🌐 Both values must be integers greater than or equal to 1. Any other value, 0 included, prevents Strapi from starting.
concurrentUploadRequests 只会被媒体库读取。concurrentUploadSize 适用于每次上传，因为服务器会强制执行它。
响应式图片
🌐 Responsive Images
当启用 Responsive friendly upload 管理面板设置 时，插件将生成以下响应式图片尺寸：
🌐 When the Responsive friendly upload admin panel setting is enabled, the plugin will generate the following responsive image sizes:
| 名称 | 最大尺寸 |
|---|---|
| 大型 | 1000px |
| 中型 | 750px |
| 小型 | 500px |
这些尺寸可以在 /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.
尖锐配置
🌐 Sharp configuration
sharp 选项配置用于生成响应式图片格式的 sharp 图片处理库。调整这些设置可以帮助在图片处理过程中减少内存使用，这对于内存受限的环境特别有用。
| 参数 | 描述 | 类型 | 默认值 |
|---|---|---|---|
cache | 启用或禁用 libvips' operation cache。禁用缓存可减少内存使用。 | 布尔值 | false |
concurrency | 设置 libvips uses for image processing的线程数。较低的值可减少峰值内存使用，但可能会降低处理速度。 | 整数 | 1 |
默认值（cache: false，concurrency: 1）已针对低内存使用进行了优化。对于内存更充足的环境，你可以启用缓存并增加并发以提高图片处理性能：
🌐 The default values (cache: false, concurrency: 1) are optimized for low memory usage. For environments with more available memory, you can enable caching and increase concurrency to improve image processing performance:
- JavaScript
- TypeScript
module.exports = ({ env }) => ({
upload: {
config: {
sharp: {
cache: true,
concurrency: 4,
},
},
},
});
export default ({ env }) => ({
upload: {
config: {
sharp: {
cache: true,
concurrency: 4,
},
},
},
});
用法
🌐 Usage
使用此功能的路径: 媒体库
媒体库显示应用中上传的所有资源，无论是通过 媒体库本身，还是在管理媒体字段时通过 内容管理器。
上传到媒体库的资源可以使用 内容管理器 插入到内容类型中。
🌐 Assets uploaded to the Media Library can be inserted into content-types using the Content Manager.
媒体库会隐藏你角色无法执行的操作，而不是显示一个禁用控件。仅有“访问媒体库”权限时，库是只读的：没有新建按钮，没有选择复选框，也没有批量操作，并且无法编辑资源详细信息面板中的字段。查看用户与权限来授予上传插件的“创建”、“更新”、“下载”和“复制链接”权限。
🌐 The Media Library hides what your role cannot do instead of displaying a disabled control. With the Access the Media Library permission alone, the library is read-only: there is no New button, no selection checkbox and no bulk action, and the fields of the asset details panel cannot be edited. See Users & Permissions to grant the Create, Update, Download and Copy link permissions of the Upload plugin.
界面概览
🌐 Interface overview
媒体库分为以下几个区域：
🌐 The Media Library is organized in the following areas:
- 左侧的文件夹树 1 列出了 Home 和完整的文件夹层级（参见 浏览文件夹）。
- 页面标题 2 显示你当前浏览的位置，可以是_首页_或某个文件夹名称，后面跟着它直接包含 的文件数量，例如显示为 11 个项目。子文件夹及其内容不计算在内，并且当筛选器激活时，这个数字不会改变。
- 新建按钮 3 可以创建文件夹或上传资源（参见添加资源和添加文件夹）。
- 工具栏 4 位于列表上方一行。可以用它来筛选、搜索和排序列表（参见查找资源），以及在网格视图和表格视图之间切换（参见切换视图）。
- 列表 5 显示当前位置的文件夹和资源。向下滚动时会加载更多资源。
列表中的每个文件夹和资源都有一个复选框可以选择它（参见 选择项目），还有一个 按钮（参见 使用项目操作菜单）。媒体库把文件夹或资源称为_项目_，有几个控件也会使用这个词。
与之前的媒体库相比有什么变化：
Strapi v5.54.0 推出了全新的媒体库。下表列出了界面的主要变化：
🌐 Strapi v5.54.0 introduces a revamped Media Library. The following table highlights the main changes in the UI:
| 在之前的界面 | 在新的媒体库 5.54.0+This feature requires Strapi version 5.54.0+ or later. |
|---|---|
| 添加新资源 和 添加新文件夹 按钮 | 一个可以同时执行两者的 新建 按钮（参见 添加资源） |
| 列表上方的面包屑 | 左侧的文件夹树（参见 浏览文件夹） |
| 文件夹卡片显示它们包含多少项目 | 仅显示文件夹名称。要直接知道一个文件夹包含多少资源，请打开它并查看页面标题 |
| 分页，带有“每页条目数”设置 | 无分页：随着滚动加载更多资源 |
| 一个用于配置视图的按钮 | 无视图配置 |
| A 按钮打开搜索栏 | 工具栏中始终显示的搜索栏（参见搜索资源） |
| 一个覆盖整个库的_详细信息_窗口 | 一个让列表仍可用的详细信息面板（参见管理单个资源） |
| 一个裁剪模式和一个焦点模式，分别打开 | 一个单一的_裁剪与焦点区域_编辑器（参见 裁剪图片和设置焦点区域） |
媒体库会把你在页面 URL 中看到的信息保存下来：当前文件夹、搜索词、筛选器、排序顺序、文件夹显示 位置以及打开的资源。复制 URL 并与同一个 Strapi 项目的其他用户分享，会让他们看到相同的列表。网格或表格的选择不包含在 URL 中，而设置为相对日期的筛选器在打开 URL 时会重新计算。
🌐 The Media Library stores what you are looking at in the page URL: the current folder, the search term, the filters, the sort order, where folders are displayed, and the open asset. Copying the URL and sharing it with another user of the same Strapi project gives them the same list. The grid or table choice is not part of the URL, and a filter set to a relative date is resolved again when the URL is opened.
切换视图
🌐 Switching views
列表可以显示为卡片网格或表格。点击工具栏中的 网格视图 或 表格视图 来切换。你的选择会在浏览器中被记录，下次访问时仍会保持相同显示方式。
表格视图为每个项目显示 名称、创建日期、最后修改 和 大小 列，标题行中还有一个 全选 复选框。缺少标题或替代文本的资源会被标记为警告图标。
🌐 The table view displays a Name, Creation date, Last modified and Size column for each item, along with a Select all checkbox in the header row. Assets missing a caption or an alternative text are flagged with a warning icon.
表格视图中的列标题是标签，而不是排序控件。使用工具栏的“排序”菜单来更改顺序（参见排序资源）。
🌐 Column headers in the table view are labels, not sort controls. Use the toolbar's Sort menu to change the order (see sorting assets).
浏览文件夹
🌐 Navigating folders
界面左侧的文件夹树列出了整个文件夹层级。没有面包屑导航：树状结构和页面标题会告诉你你的位置。
🌐 The folder tree on the left side of the interface lists the whole folder hierarchy. There is no breadcrumb: the tree and the page title tell you where you are.
- 点击树状或列表中的文件夹名称来显示其内容。
- 点击文件夹名称旁边的 按钮来展开或折叠其子文件夹。
- 点击 首页返回库的根目录。
Strapi 不会限制文件夹的最大深度。文件夹树会自动展开，显示你正在浏览的文件夹。
🌐 Strapi does not enforce a maximum folder depth. The folder tree expands automatically to reveal the folder you are browsing.
使用物品操作菜单
🌐 Using the item actions menu
资源或文件夹的 按钮会打开一个菜单，只对该项目生效，而不管列表中其他项目是否被选中。
在一个资源上，菜单提供：
🌐 On an asset, the menu offers:
- 更换媒体
- 复制媒体链接
- 下载媒体
- 移动到文件夹
- 删除
在一个文件 夹上，菜单提供了：
🌐 On a folder, the menu offers:
- 复制文件夹链接
- 重命名文件夹
- 移动到文件夹
- 删除文件夹
使用右键菜单
🌐 Using the right-click menu
在媒体库的空白部分右键点击会打开一个菜单，其中包含与 新建 按钮相同的创建操作。它们会作用于你当前正在浏览的文件夹：
🌐 Right-clicking the empty parts of the Media Library opens a menu with the same creation actions as the New button. They act on the folder you are currently browsing:
- 新建文件夹
- 文件上传
- 从网址上传文件
菜单可以在滚动列中的任何位置打开：列表、最后一行下面的空白区域、标题旁的页面头栏以及它们周围的内边距。在网格视图和表格视图中，它的行为都是一样的，可以通过 Escape 或点击其他地方来关闭。
🌐 The menu opens anywhere in the scrolling column: the list, the empty space below the last row, the page header band beside the title, and the padding around them. It behaves the same in the grid view and in the table view, and is dismissed with Escape or a click elsewhere.
任何你可以互动的东西都会保留你浏览器自己的菜单，所以在搜索栏里复制粘贴仍然可以用。这适用于新建按钮、搜索、筛选、排序、视图切换和筛选标签，以及资源卡、文件夹卡、表格行和表格视图的列头行。
🌐 Anything you can interact with keeps your browser's own menu instead, so copying and pasting still works in the search field. This covers the New button, search, filters, sorting, the view toggle and the filter badges, as well as asset cards, folder cards, table rows and the column header row of the table view.
该菜单需要上传插件的 创建 权限。没有这个权限，右键点击库时会直接显示浏览器菜单，什么选项都没有。请参见 用户与权限。
🌐 The menu requires the Create permission of the Upload plugin. Without it, right-clicking the library falls through to your browser's menu with nothing offered. See Users & Permissions.
添加资源
🌐 Adding assets
资源总是上传到你当前浏览的位置。上传前先导航到目标文件夹，或者之后再移动资源（请参见移动资源和文件夹）。
🌐 Assets are always uploaded to the location you are currently browsing. Navigate to the target folder before uploading, or move the assets afterwards (see moving assets and folders).
在一个空文件夹和新的项目中，列表会被一个 还没有资源 的信息取代，并带有一个 添加资源 按钮，点击会打开与 新建 > 文件上传 相同的文件浏览器。
🌐 In an empty folder, and in a new project, the list is replaced by a No assets yet message with an Add assets button that opens the same file browser as New > File upload.
媒体库本身不限制文件类型。哪些文件被接受取决于 security.allowedTypes 和 security.deniedTypes 选项（见 安全）以及最大文件大小（见 最大文件大小）。在使用 Strapi 5.52.2+ 及更高版本生成的项目中，默认会拒绝 SVG 文件（见 SVG 上传）。
Zip、xls、csv 和 json 文件无法预览。图片、视频和音频文件可以预览。
🌐 Zip, xls, csv, and json files are not previewed. Images, video, and audio files are previewed.
有三种添加资源的方式：从你的电脑上传、拖放到媒体库界面，或者通过网址添加。
🌐 There are 3 ways to add assets: by uploading from your computer, by dragging and dropping into the Media Library UI, or from a URL.
使用“新建”按钮从电脑上传文件
🌐 Uploading files from your computer with the New button
- 点击媒体库右上角的新建按钮。
- 点击 文件上传。
- 在你系统的文件浏览器中选择一个或多个文件，然后确认。
上传会立即开始，并且其进度会在上传对话框中显示（见后续上传进度）。
🌐 The upload starts immediately and its progress is reported in the upload dialog (see following upload progress).
通过拖放从你的电脑上传文件
🌐 Uploading files from your computer by drag and drop
- 将一个或多个文件从你的电脑拖到媒体库中。
- 查看 拖到这里上传到 覆盖层中命名的目标文件夹。
- 把文件放出来。
从你的电脑中拖放的文件总是会落在你当前正在浏览的文件夹里，不管你把它们拖到哪里。把文件拖到一个文件夹卡片上并不会把它上传到那个文件夹：你需要先进入文件夹。把已经在库里的项目拖到一个文件夹上会把它移动过去（参见移动资源和文件夹）。
🌐 Files dropped from your computer always land in the folder you are currently browsing, whatever they are dropped on. Dropping a file on a folder card does not upload it into that folder: navigate into the folder first. Dragging an item that is already in the library onto a folder does move it (see moving assets and folders).
从网址上传文件
🌐 Uploading files from a URL
- 点击媒体库右上角的新建按钮。
- 点击 从URL上传文件。
- 在“从 URL 导入”对话框的“URL(s)”字段中，输入或粘贴最多 20 个 URL，每行一个。
- 点击上传。
Strapi 会在服务器端下载每个文件，并将其添 加到当前文件夹中。上传对话框会在服务器获取每个文件时显示字节级进度：进度条在获取阶段实时前进，然后交给上传步骤并完成。 5.53.1+
当远程服务器没有包含 Content-Length 响应头时，总大小未知。该文件的进度条会保持不确定状态，直到获取完成，然后才会正常完成。
🌐 When the remote server does not include a Content-Length response header, the total size is unknown. The progress bar stays indeterminate for that file until the fetch completes, then completes normally.
URL 必须使用 http 或 https 协议，并且必须能解析到一个公共可访问的地址。解析到私有或内部地址的 URL，比如 localhost 或你自己网络上的地址，会被拒绝，以防服务器端请求伪造。
🌐 URLs must use the http or https protocol, and must resolve to a publicly reachable address. URLs that resolve to a private or internal address, such as localhost or an address on your own network, are rejected to prevent server-side request forgery.
正在跟踪上传进度
🌐 Following upload progress
上传会在一个对话框中显示，列出批次中的每个文件及其状态，例如排队中、上传中或已上传。该对话框在整个管理面板中都可用，不仅限于媒体库，因此在批量上传的同时，你可以导航到 Strapi 的其他部分。
🌐 Uploads are reported in a dialog that lists every file of the batch with its own status, such as Queued, Uploading... or Uploaded. The dialog is available throughout the admin panel, not only in the Media Library, so you can navigate to another part of Strapi while a batch uploads.
对话框可以缩小成一行摘要，也可以再次最大化。它提供了一个全部取消按钮，可以在保留已上传文件的情况下停止批处理，一个重试按钮，用于重新启动你取消的文件，以及在批处理完成后使用的关闭按钮。在批处理运行时拖入更多文件，会将它们添加到该批处理中。
🌐 The dialog can be minimized to a summary line and maximized again. It offers a Cancel all button that stops the batch while keeping the files already uploaded, a Retry button that restarts the files you cancelled, and a Close button once the batch is finished. Dropping more files while a batch is running adds them to that batch.
重试 仅在取消后显示，并且只会重新启动已取消的文件。自己失败的文件无法从对话框中重试 ：请查看该行的原因，解决问题，然后重新上传。
默认情况下，文件是一个一个上传的。增加 concurrentUploadRequests 可以同时上传多个文件。
🌐 By default, files are uploaded one at a time. Increase concurrentUploadRequests to upload several files in parallel.
使用 Strapi AI 自动生成元数据
🌐 Automatically generating metadata with Strapi AI
GrowthThis feature is available with a Growth plan. EnterpriseThis feature is available with an Enterprise plan.启用时，Strapi AI 会自动为上传到媒体库的图片生成替代文字和标题，帮助你提升内容的可访问性和 SEO。在 EnterpriseThis feature is available with an Enterprise plan. 计划中，Strapi AI 由 自带 AI 密钥插件 提供支持，并使用你自己的 AI 服务提供商。上传对话框会显示每个文件的处理结果，例如 已上传 • 元数据已生成 或 上传完成 • 跳过元数据生成。
AI 元数据生成只适用于 PNG、JPEG、WebP、HEIC 和 HEIF 图片。其他所有文件，包括 GIF、SVG 和 TIFF 图片，都会被标记为已跳过。该功能默认开启，但如果需要，可以在媒体库设置中关闭。
🌐 AI metadata generation only works with PNG, JPEG, WebP, HEIC and HEIF images. Every other file, including GIF, SVG and TIFF images, is reported as skipped. The feature is enabled by default, but can be disabled in the Media Library settings if needed.
元数据也可以为库中已经存在的图片生成，可以通过媒体库设置为每个缺少元数据的图片生成，或者对特定选择使用创建元数据批量操作（参见批量生成元数据）。
🌐 Metadata can also be generated for images that already exist in the library, either from the Media Library settings for every image that lacks one, or with the Create metadata bulk action for a specific selection (see generating metadata in bulk).
Strapi 管理的 AI 在 Growth 计划中每月包含 1,000 个积分，免费试用期间还可获得 10 个免费积分。在 Enterprise 计划中，Strapi AI 由你自己的 AI 提供商驱动，通过 自带 AI 密钥插件，你的提供商会对请求进行计费。
轻量级操作使用较少的积分，而更复杂的操作使用更多。
🌐 Lightweight actions use fewer credits, while more complex ones use more.
你可以在管理面板的 Settings Overview 中查看你的信用使用情况。当你的使用量达到每月配额的80%、90%和100%时，会发送通知。超额使用将产生额外费用。
积分在同一项目实例的所有用户之间共享。
🌐 Credits are shared across all users within the same project instance.
当你的积分用完后，你仍然可以继续使用 Strapi 管理的 AI，超出部分将按月计费。有关 Strapi AI 的更多信息，请参考专门的支持文章。
🌐 When your credits run out, you can keep using Strapi-managed AI, with overages billed monthly. For more information about Strapi AI, please refer to the dedicated support article.
查找资源
🌐 Finding assets
工具栏依次提供了一个筛选按钮、一个_搜索_栏和一个排序按钮。搜索会在整个库中查找，而筛选和排序只作用于你正在浏览的位置。
正在搜索资源
🌐 Searching assets
在工具栏的 搜索 框中输入内容以按名称查找资源和文件夹。
🌐 Type in the toolbar's Search field to find assets and folders by name.
搜索覆盖整个库，而不仅仅是你正在浏览的文件夹，并且会返回文件夹和资源。页面标题会变成_“你的搜索词”的搜索结果_，后面跟着找到的文件夹和资源数量。
🌐 The search covers the whole library, not only the folder you are browsing, and it returns both folders and assets. The page title becomes Search results for "your term" followed by the number of folders and assets found.
要退出搜索，可以点击搜索栏内的 清除按钮，或者在搜索栏中按下Esc键，或者在文件夹树中导航到某个文件夹。
当搜索没有结果时，列表会被一条 未找到结果 的信息取代，并带有一个 清除搜索按钮。
筛选资源
🌐 Filtering assets
有 3 个过滤字段可以用来缩小列表：
| 筛选字段 | 值 | 条件 |
|---|---|---|
| 类型 | 文件夹, 图片, 音频, 视频, 文档 | 是, 不是 |
| 创建日期 | 相对预设，从1天前到1年前，或者自定义范围 |
|
| 最后修改 | 相对预设，从1天前到1年前 | 恰好是, 最近, 不是最近 |
筛选列表：
🌐 To filter the list:
- 在工具栏中点击 筛选按钮。
- 点击一个筛选字段。
- 点击一个或多个值。类型 列表会保持打开，这样你可以勾选多个类型，徽章会显示它们全部，例如 类型 是 图片、视频。
- (可选) 对另一个字段重复操作。
过滤器会组合，所以只有符合所有过滤条件的项目会显示。每个已应用的过滤器都会作为徽章显示在工具栏下方。点击徽章的条件或数值部分可以更改它，点击 按钮可以移除该过滤器。
筛选器只适用于你正在浏览的位置，而不是整个库。使用搜索可以在所有文件夹中查找。
🌐 Filters apply to the location you are browsing, not to the whole library. Use the search to look across all folders.
Type 徽 章也决定了文件夹是否显示：除非 Folder 是其值之一，否则文件夹会被隐藏，而当 Folder 是其唯一值时，资源也会被隐藏。
🌐 A Type badge also decides whether folders are displayed: folders are hidden unless Folder is one of its values, and assets are hidden when Folder is its only value.
当活动筛选条件没有匹配任何项时，列表会被一个 没有项目匹配当前筛选条件 的消息替代，同时会有一个 清除筛选按钮，可以移除所有筛选条件。工具栏中没有清除全部的控制按钮：只要筛选条件匹配到某些内容，就需要一个一个地移除标签。
整理资源
🌐 Sorting assets
点击工具栏中的排序按钮即可更改列表的顺序。按钮标签总是显示当前使用的规则，例如 排序：最近更新。
🌐 Click the Sort button in the toolbar to change the order of the list. The button label always names the active rule, for instance Sort: Most recent updates.
_排序_部分提供6条互斥规则：最早上传、最新更新（默认）、A到Z、Z到A、文件大小升序和文件大小降序。
🌐 The Sort section offers 6 mutually exclusive rules: Oldest uploads, Most recent updates (the default), A to Z, Z to A, File size ascending, and File size descending.
在表格视图中，一个额外的“文件夹”部分决定文件夹是显示在顶部（默认）还是与文件混合显示，如果是混合显示，它们将遵循当前的排序规则。网格视图始终将文件夹显示在顶部，因此不会显示该部分。
🌐 In the table view, an additional Folders section decides whether folders are grouped On top, which is the default, or Mixed with files, in which case they follow the active sort rule. The grid view always groups folders on top, so it does not display that section.
当文件夹适用时，会遵循当前的排序规则：按“最早上传”会按照它们自己的创建日期排序，按“A到Z”和“Z到A”会按名称排序。对于默认的“最新更新”规则，它们保持字母顺序，同样对于两种文件大小规则也是如此，因为文件夹没有大小。
🌐 Folders follow the active sort rule when it can apply to them: Oldest uploads orders them by their own creation date, and A to Z and Z to A by name. They stay in alphabetical order for the default Most recent updates rule, and for the 2 file size rules because folders have no size.
管理个人资源
🌐 Managing individual assets
点击列表中的一个资源，在界面右侧打开它的详细信息面板。列表会在面板后面保持可见并可使用。
🌐 Click an asset in the list to open its details panel on the right side of the interface. The list stays visible and usable behind the panel.
小组安排如下：
🌐 The panel is organized as follows:
- 资源预览。图片会显示，视频和音频文件可以用浏览器自带的控件播放，PDF 会直接在页面中显示。其他文件类型会显示图标并提示“无法预览”。图片还会有一个 裁剪按钮（参见 裁剪图片和设置焦点区域）。
- 一个只读的 文件信息 部分，列出资源的 创建日期、最后更新、创建者、大小、尺寸（仅限图片）、扩展名 和 资源 ID。
- 可编辑的 文件名、位置、标题 和 替代文本 字段。标题和替代文本可以在任何文件类型上设置，不仅仅是图片，而且当这两个字段为空时，每个字段旁边都会显示一个警告。
- 底部有一排仅图标按钮： 删除此文件、 复制链接、 下载和 替换此文件，它们在保存更改按钮旁边。
编辑资源名称、标题和替代文本
🌐 Editing an asset name, caption and alternative text
要重命名一个资源，或添加或更改它的标题和替代文本：
🌐 To rename an asset, or to add or change its caption and alternative text:
- 点击列表中的资源。
- 更新 文件名、标题 或 替代文本 字段。
- 点击 保存更改。
保存更改 会保持禁用状态，直到你做出修改，而空的 文件名 会阻止保存。如果你在有未保存更改的情况下关闭面板，Strapi 会在放弃更改前让你确认。
同一面板中的 Location 字段可以将单个资源移动到另一个文件夹。有关其他选项，请参见 移动资源和文件夹。
🌐 The Location field of the same panel moves a single asset to another folder. See moving assets and folders for the other options.
裁剪图片并设置焦点区域
🌐 Cropping images and setting a focus area
一个编辑器可以同时处理裁剪和焦点区域。焦点区域，也叫焦点点，可以在前端裁剪或调整图片大小时，让最重要的部分保持可见。
🌐 One editor handles both cropping and the focus area. The focus area, also called focal point, keeps the most important part of an image visible when your front end crops or resizes it.
- 点击列表中的图片以打开其详细信息面板。
- 在预览中点击 裁剪按钮。_裁剪与聚焦区域_编辑器会打开。
- (可选) 点击编辑器右上角的 按钮，可以将图片顺时针旋转90°。再次点击可以继续旋转。裁剪和焦点区域会随图片旋转，宽度和高度字段在每次旋转90°后会互换。
- 通过拖动矩形角上的控制点来定义裁剪区域，或者在编辑面板的宽度和高度字段中输入精确的数值。
- (可选) 点击 按钮锁定宽高比，这样调整大小时两个尺寸会一起变化。
- 通过将圆圈拖动到裁剪矩形内，或者在_X_和_Y_字段中输入精确数值来定义焦点区域。
- 保存你的更改：
- 点击 应用 来裁剪原始资源。资源会保留其 ID，因此已经使用它的内容会被更新。
- 点击 另存为副本 可以保持原件不变，并在同一个文件夹中创建一个新资源。副本会继承原件的标题和替代文字。
要不更改任何内容就离开编辑器，点击 取消。
🌐 To leave the editor without changing anything, click Cancel.
- 焦点区域会存储在素材上，并通过 API 以
focalPoint值返回，这样你的前端在裁剪或调整图片大小时就可以使用它。 - 在小屏幕上，数字字段是隐藏的。请直接在图片上拖动矩形和圆形来设置裁剪和焦点区域。
替换一个资源文件
🌐 Replacing an asset file
替换会在保留资源本身的情况下更换其背后的文件，所以所有已经指向它的内容条目仍然可以正常工作。
🌐 Replacing swaps the file behind an asset while keeping the asset itself, so every content entry already pointing at it keeps working.
- 点击列表中的资源以打开其详细信息面板。
- 点击 替换此文件按钮。
- 在确认对话框中点击继续。
- 在系统的文件浏览器中选择新文件并确认。文件浏览器只会显示类型与当前资源匹配的文件。
之前的文件将被永久替换，无法恢复。如果启用了AI 元数据生成，Strapi 还会为替换的文件生成新的标题和替代文本，覆盖现有内容。确认对话框会在你继续之前提醒你这一点。
🌐 The previous file is permanently replaced and cannot be recovered. If AI metadata generation is enabled, Strapi also generates a new caption and alternative text for the replacement file, overwriting the existing ones. The confirmation dialog says so before you continue.
正在下载资源并复制链接
🌐 Downloading assets and copying links
- 点击列表中的资源以打开其详细信息面板。
- 点击 下载按钮将文件保存到你的电脑，或点击 复制链接按钮将其网址复制到剪贴板。
这两种操作也可以在资源的 操作菜单中找到，分别是 复制媒体链接 和 下载媒体。
复制媒体链接 会复制资源自身的 URL，也就是你的前端用来提供文件的链接。复制文件夹链接，在文件夹的 操作菜单中，会复制一个指向该文件夹在管理面板中的链接，但只有登录 Strapi 的人才能使用。
删除资源
🌐 Deleting assets
- 点击列表中的资源以打开其详细信息面板。
- 点击 删除此文件按钮。
- 点击 确认。
已删除的文件无法恢复。如果文件正在使用中，相关内容会中断，图片容器会变空。
🌐 Deleted files cannot be recovered. If a file is currently in use, the linked content breaks and image containers are left empty.
资源也可以与文件夹一起批量删除（参见 批量删除项目）。
🌐 Assets can also be deleted in bulk, together with folders (see deleting items in bulk).
使用批量操作
🌐 Using bulk actions
批量操作适用于选中的资源和文件夹。先选择项目，然后在批量操作栏中选择一个操作。
🌐 Bulk actions apply to a selection of assets and folders. Select the items first, then pick an action in the bulk actions bar.
选择项目
🌐 Selecting items
点击文件夹或资源的复选框来选择它。资源和文件夹可以一起选择。
🌐 Click the checkbox of a folder or an asset to select it. Assets and folders can be selected together.
以下快捷键可以加快选择速度：
🌐 The following shortcuts speed up selection:
| 快捷键 | 描述 |
|---|---|
Cmd/Ctrl + 点 击 | 将某个项目加入或移出选择。 |
Shift + 点击 | 选择从上次选择的项目到当前点击项目之间的所有项目。 |
Space | 当卡片或行被聚焦时，将其加入或移出选择。 |
Enter | 当卡片或行被聚焦时，打开资源详情面板，或进入文件夹。 |
两个快捷键修饰符都可以在卡片或整行上使用。无论你按了哪个修饰键，点击文件名总是会打开详情面板。
🌐 Both modifier shortcuts work on the card or the row itself. Clicking the file name always opens the details panel, whatever modifier you hold.
在表格视图中，标题行的 全选 复选框会选中当前显示的所有项目，如果已经全部选中，再点击则会清空选择。
🌐 In the table view, a Select all checkbox in the header row selects every item currently displayed, and empties the selection when everything is already selected.
选择一个项目会在界面底部显示批量操作栏。该栏会显示已选择的项目数量，并提供批量操作。点击 清除选择即可清空选择。
在网格视图和表格视图中，工具栏也提供了一个 全选 按钮，可以选择当前显示的所有文件夹和资源。只有已经加载的项目会被选中：向下滚动列表，然后再次点击 全选 来添加新加载的项目。不同于表格视图表头的复选框，当所有项目已经被选中时，这个按钮不会清空选择。
🌐 In the grid view as well as the table view, the bar also offers a Select all button that selects every folder and asset currently displayed. Only the items already loaded are selected: scroll further down the list, then click Select all again to add the newly loaded items. Unlike the checkbox of the table view header, the button does not empty the selection when everything is already selected.
在网格视图和表格视图之间切换时，所选内容会保留，但当你切换到其他文件夹或更改搜索、筛选条件或排序方式时，选中内容会被清空。
🌐 The selection survives switching between the grid and the table view, but it is emptied when you navigate to another folder or change the search, the filters or the sort order.
打开资源详情面板时，面板打开时工具栏会隐藏。选择会保留，关闭面板后工具栏会回来。
🌐 Opening an asset details panel hides the bar while the panel is open. The selection is kept and the bar comes back when you close the panel.
批量移动物品
🌐 Moving items in bulk
- 选择要移动的资源和文件夹。
- 点击批量操作栏中的 移动按钮。
- 在“移动元素到”对话框中，从“位置”列表中选择目标位置。库的根目录列为“媒体库”，文件夹会显示完整路径，例如“品牌资源 / 标志”。元素所在的文件夹，以及任何不能移动到的文件夹，都不会显示在列表中。
- 点击 移动。
项目也可以通过拖放来移动（参见 移动资源和文件夹）。
🌐 Items can also be moved by drag and drop (see moving assets and folders).
批量删除项目
🌐 Deleting items in bulk
- 选择要删除的资源和文件夹。
- 点击批量操作栏中的 删除按钮。
- 在对话框中点击 确认。
删除一个文件夹也会删除其中的所有内容，包括子文件夹及其资源。所有东西都无法恢复。
🌐 Deleting a folder also deletes everything it contains, including its subfolders and their assets. None of it can be recovered.
批量生成元数据
🌐 Generating metadata in bulk
GrowthThis feature is available with a Growth plan. EnterpriseThis feature is available with an Enterprise plan.当启用 Strapi AI 时，或 Strapi 通过 Bring your own AI key 插件 管理或提供支持时，批量操作栏中的 a 创建元数据 按钮会为所选图片生成标题和替代文本。
- 选择要描述的图片。
- 点击批量操作栏中的 创建元数据按钮。
元数据一次最多可以为 40 个资源生成。只支持 PNG、JPEG、WebP、HEIC 和 HEIF 图片：选中的文件夹会被忽略，其他类型的选中文件会被报告为已跳过。
🌐 Metadata can be generated for up to 40 assets at a time. Only PNG, JPEG, WebP, HEIC and HEIF images are supported: selected folders are ignored, and selected files of any other type are reported as skipped.
使用文件夹整理资源
🌐 Organizing assets with folders
媒体库中的文件夹可以帮助你整理上传的资源。在媒体库中，你可以创建新文件夹、移动资源和文件夹、重命名文件夹以及删除文件夹。要浏览它们，请参见 浏览文件夹。
🌐 Folders in the Media Library help you organize uploaded assets. From the Media Library, it is possible to create new folders, move assets and folders, rename a folder, and delete folders. To browse them, see navigating folders.
文件夹遵循资源的权限系统（参见 用户与权限功能）。目前还不能为文件夹定义特定权限。创建文件夹需要对资源具有_创建_权限，而重命名、移动或删除文件夹则需要_更新_权限。
🌐 Folders follow the permission system of assets (see Users & Permissions feature). It is not yet possible to define specific permissions for a folder. Creating a folder requires the Create permission on assets, and renaming, moving or deleting one requires the Update permission.
“重命名文件夹”、“移动到文件夹”和“删除文件夹”会显示给所有可以看到该文件夹的用户，包括没有资源“更新”权限的用户。但随后服务器会拒绝该操作。
添加文件夹
🌐 Adding folders
- 导航到需要创建文件夹的位置。
- 点击媒体库右上角的新建按钮。
- 点击 新建文件夹。
- 在“文件夹名称”字段中输入一个名字。
- 点击 创建文件夹。
对话框标题显示的是父文件夹的名称，例如“首页中的新建文件夹”。如果想在其他地方创建文件夹，可以取消操作，导航到目标父文件夹，然后重新开始。
🌐 The dialog title names the parent folder, for instance New folder in Home. To create the folder somewhere else, cancel, navigate to the intended parent, and start again.
移动资源和文件夹
🌐 Moving assets and folders
资源和文件夹可以通过三种方式移动：
🌐 Assets and folders can be moved in 3 ways:
- 通过拖放，每次可以移动几项。将一个资源或文件夹拖到列表中的文件夹上，或者拖到文件夹树中的某个文件夹上，包括首页。在文件夹树上悬停片刻会展开文件夹，这样你就可以一次性将项目拖入子文件夹。拖动所选中的一项会移动整个选择。
- 使用“移动到”对话框，可以一次移动许多项目（参见批量移动项目）。它也可用于单个项目，在其 操作菜单中为移动到文件夹。
- 在一个资源的详细信息面板中，通过更改它的 位置 字段（参见管理单个资源）。
文件夹不能移动到它自身或它的子文件夹里。拖动时无效的目标会被拒绝。
🌐 A folder cannot be moved into itself or into one of its own subfolders. Invalid destinations are refused while you drag.
拖放使用指针。要使用键盘移动项目，请改用 操作菜单的移动到文件夹操作。
重命名文件夹
🌐 Renaming folders
- 点击文件夹的 按钮。
- 点击 重命名文件夹。
- 在“文件夹名称”字段中输入新名称。
- 点击 保存。
同一个父文件夹下的文件夹名称必须是唯一的。
🌐 A folder name must be unique among the folders sharing the same parent.
删除文件夹
🌐 Deleting folders
- 点击文件夹的 按钮。
- 点击 删除文件夹。
- 点击 确认。
删除一个文件夹也会删除其中的所有内容，包括其子文件夹及其资源。这些都无法恢复，而且确认对话框也没有提示这一点。
🌐 Deleting a folder also deletes everything it contains, including its subfolders and their assets. None of it can be recovered, and the confirmation dialog does not say so.
文件夹也可以批量删除，同时删除资源（参见 批量删除项目）。
🌐 Folders can also be deleted in bulk, together with assets (see deleting items in bulk).
与 MCP 服务器的使用
🌐 Usage with the MCP server
连接到 Strapi MCP 服务器 的 AI 客户端可以通过专用工具浏览和管理媒体库：有 3 个只读工具用于列出资源、返回单个资源以及返回文件夹树，还有 7 个写入工具用于更新资源元数据、移动和删除资源，以及创建、重命名、移动和删除文件夹（见 媒体库工具）。
🌐 AI clients connected to the Strapi MCP server can browse and manage the Media Library through dedicated tools: 3 read-only tools that list assets, return a single asset and return the folder tree, and 7 write tools that update asset metadata, move and delete assets, and create, rename, move and delete folders (see Media Library tools).
与 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:
在你的代码中使用公共资源
🌐 Use public assets in your code
公共资源是指你希望外部访问的静态文件（例如，图片、视频、CSS 文件等）。
🌐 Public assets are static files (e.g., images, video, CSS files, etc.) that you want to make accessible to the outside world.
因为 API 可能需要提供静态资源，每个新的 Strapi 项目默认都会包含一个名为 /public 的文件夹。位于该目录中的任何文件，如果请求的路径不匹配任何其他已定义的路由，并且它匹配一个公共文件名（例如在 /public/ 中名为 company-logo.png 的图片可通过 /company-logo.png URL 访问），则可以被访问。
🌐 Because an API may need to serve static assets, every new Strapi project includes by default a folder named /public. Any file located in this directory is accessible if the request's path doesn't match any other defined route and if it matches a public file name (e.g. an image named company-logo.png in /public/ is accessible through /company-logo.png URL).
index.html 文件会在请求对应于文件夹名称时提供（/pictures URL 会尝试提供 public/pictures/index.html 文件）。
点文件未被公开。这意味着每个以 . 开头的文件名，例如 .htaccess 或 .gitignore，都不会被提供服务。
🌐 The dotfiles are not exposed. It means that every file name that starts with ., such as .htaccess or .gitignore, are not served.