Skip to main content

媒体库提供程序

¥Media Library providers

媒体库 功能由名为 Upload 的后端服务器包提供支持，该包利用了提供程序的使用。

¥The Media Library feature is powered by a back-end server package called Upload which leverages the use of 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:

提供者为插件的核心功能添加了扩展，例如将媒体文件上传到 AWS S3 而不是本地服务器，或者使用 Amazon SES 代替 Sendmail 发送电子邮件。

¥Providers add an extension to the core capabilities of the plugin, for example to upload media files to AWS S3 instead of the local server, or using Amazon SES for emails instead of Sendmail.

Strapi 维护的官方提供程序（可通过 市场 找到）以及许多社区维护的提供程序（可通过 npm 获取）。

¥There are both official providers maintained by Strapi — discoverable via the Marketplace — and many community maintained providers available via npm.

可以将提供程序配置为 private，以确保对资源 URL 进行签名以实现安全访问。

¥A provider can be configured to be private to ensure asset URLs will be signed for secure access.

安装提供程序​

¥Installing providers

可以使用 npm 或 yarn 使用以下格式 @strapi/provider-<plugin>-<provider> --save 安装新的提供程序。

¥New providers can be installed using npm or yarn using the following format @strapi/provider-<plugin>-<provider> --save.

例如，要为上传（媒体库）功能安装 AWS S3 提供程序：

¥For example, to install the AWS S3 provider for the Upload (Media Library) feature::

yarn add @strapi/provider-upload-aws-s3

配置提供者​

¥Configuring providers

新安装的提供程序在 /config/plugins 文件 中启用并配置。如果该文件不存在，则必须创建它。

¥Newly installed providers are enabled and configured in the /config/plugins file. If this file does not exist you must create it.

每个提供者都有不同的可用配置设置。查看 市场 或 npm 中该提供商的相应条目以了解更多信息。

¥Each provider will have different configuration settings available. Review the respective entry for that provider in the Marketplace or npm to learn more.

以下是 AWS S3 媒体库提供商的示例配置：

¥The following is an example configuration for an AWS S3 Media Library provider:

/config/plugins.js

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        baseUrl: env('CDN_URL'),
        rootPath: env('CDN_ROOT_PATH'),
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: env('AWS_ACL', 'public-read'),
            signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});
注意

  • Strapi 具有默认 security 中间件，其具有非常严格的 contentSecurityPolicy，将图片和媒体的加载限制为仅 "'self'"，有关更多信息，请参阅 提供者页面 或 中间件文档 上的示例配置。

    ¥Strapi has a default security middleware that has a very strict contentSecurityPolicy that limits loading images and media to "'self'" only, see the example configuration on the provider page or the middleware documentation for more information.

  • 当每个环境使用不同的提供程序时，请在 /config/env/${yourEnvironment}/plugins.js|ts 中指定正确的配置（请参阅 环境）。

    ¥When using a different provider per environment, specify the correct configuration in /config/env/${yourEnvironment}/plugins.js|ts (See Environments).

  • 一次只有一个电子邮件提供者处于活动状态。如果 Strapi 未选择电子邮件提供者设置，请验证 plugins.js|ts 文件是否位于正确的文件夹中。

    ¥Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the plugins.js|ts file is in the correct folder.

  • 使用在 Strapi 设置期间创建的两个电子邮件模板测试新电子邮件提供者时，模板上的发送者电子邮件默认为 no-reply@strapi.io，需要根据你的电子邮件提供者进行更新，否则将无法通过测试（请参阅 本地配置模板）。

    ¥When testing the new email provider with those two email templates created during strapi setup, the shipper email on the template defaults to no-reply@strapi.io and needs to be updated according to your email provider, otherwise it will fail the test (See Configure templates locally).

每个环境的配置​

¥Configuration per environment

配置提供程序时，你可能希望根据 NODE_ENV 环境变量更改配置或使用特定于环境的凭据。

¥When configuring your provider you might want to change the configuration based on the NODE_ENV environment variable or use environment specific credentials.

你可以在 /config/env/{env}/plugins.js|ts 配置文件中设置特定配置，它将用于覆盖默认配置。

¥You can set a specific configuration in the /config/env/{env}/plugins.js|ts configuration file and it will be used to overwrite the default configuration.

创建提供者​

¥Creating providers

要实现你自己的自定义提供程序，你必须 创建 Node.js 模块。

¥To implement your own custom provider you must create a Node.js module.

必须导出的接口取决于你为其开发提供程序的插件。以下是上传（媒体库）和电子邮件功能的模板：

¥The interface that must be exported depends on the plugin you are developing the provider for. The following are templates for the Upload (Media Library) and Email features:

module.exports = {
  init(providerOptions) {
    // init your provider if necessary

    return {
      upload(file) {
        // upload the file in the provider
        // file content is accessible by `file.buffer`
      },
      uploadStream(file) {
        // upload the file in the provider
        // file content is accessible by `file.stream`
      },
      delete(file) {
        // delete the file in the provider
      },
      checkFileSize(file, { sizeLimit }) {
        // (optional)
        // implement your own file size limit logic
      },
      getSignedUrl(file) {
        // (optional)
        // Generate a signed URL for the given file.
        // The signed URL allows secure access to the file.
        // Only Content Manager assets will be signed.
        // Returns an object {url: string}.
      },
      isPrivate() {
        // (optional)
        // if it is private, file urls will be signed
        // Returns a boolean
      },
    };
  },
};

在发送功能中，你将可以访问：

¥In the send function you will have access to:

  • providerOptions 包含用 plugins.js|ts 编写的配置

    ¥providerOptions that contains configurations written in plugins.js|ts

  • settings 包含用 plugins.js|ts 编写的配置

    ¥settings that contains configurations written in plugins.js|ts

  • options 包含你从电子邮件插件服务调用发送函数时发送的选项

    ¥options that contains options you send when you call the send function from the email plugin service

你可以查看 Strapi 维护的提供商 以了解示例实现。

¥You can review the Strapi-maintained providers for example implementations.

创建新提供商后，你可以 发布到 npm 与社区共享，或仅为你的项目共享 在本地使用它。

¥After creating your new provider you can publish it to npm to share with the community or use it locally for your project only.

本地提供者​

¥Local providers

如果你想创建自己的提供程序而不将其发布到 npm 上，你可以按照以下步骤操作：

¥If you want to create your own provider without publishing it on npm you can follow these steps:

  1. 在你的应用中创建一个 providers 文件夹。

    ¥Create a providers folder in your application.

  2. 创建你的提供者（例如 /providers/strapi-provider-<plugin>-<provider>）

    ¥Create your provider (e.g. /providers/strapi-provider-<plugin>-<provider>)

  3. 然后更新你的 package.json 以将你的 strapi-provider-<plugin>-<provider> 依赖链接到新提供商的 本地路径。

    ¥Then update your package.json to link your strapi-provider-<plugin>-<provider> dependency to the local path of your new provider.

{
  ...
  "dependencies": {
    ...
    "strapi-provider-<plugin>-<provider>": "file:providers/strapi-provider-<plugin>-<provider>",
    ...
  }
}

  1. 将 /config/plugins.js|ts 文件更新为 配置提供者。

    ¥Update your /config/plugins.js|ts file to configure the provider.

  2. 最后，运行 yarn 或 npm install 以安装新的自定义提供程序。

    ¥Finally, run yarn or npm install to install your new custom provider.

私有提供商​

¥Private providers

你可以设置私有提供者，这意味着内容管理器中显示的每个资源 URL 都将经过签名以进行安全访问。

¥You can set up a private provider, meaning that every asset URL displayed in the Content Manager will be signed for secure access.

要启用私有提供程序，你必须实现 isPrivate() 方法并返回 true。

¥To enable private providers, you must implement the isPrivate() method and return true.

在后端，Strapi 使用提供程序中实现的 getSignedUrl(file) 方法为每个资源生成签名 URL。签名的 URL 包含一个加密的签名，允许用户访问资源（但通常仅限于有限的时间和特定的限制，具体取决于提供者）。

¥In the backend, Strapi generates a signed URL for each asset using the getSignedUrl(file) method implemented in the provider. The signed URL includes an encrypted signature that allows the user to access the asset (but normally only for a limited time and with specific restrictions, depending on the provider).

请注意，出于安全原因，内容 API 将不会提供任何签名 URL。相反，使用 API 的开发者应该自己对 URL 进行签名。

¥Note that for security reasons, the content API will not provide any signed URLs. Instead, developers using the API should sign the urls themselves.

示例

¥Example

要创建私有 aws-s3 提供者：

¥To create a private aws-s3 provider:

  1. 在你的应用中创建一个 /providers/aws-s3 文件夹。请参阅 本地提供者 了解更多信息。

    ¥Create a /providers/aws-s3 folder in your application. See Local Providers for more information.

  2. 在 aws-s3 提供程序中实现 isPrivate() 方法以返回 true。

    ¥Implement the isPrivate() method in the aws-s3 provider to return true.

  3. 在 aws-s3 提供程序中实现 getSignedUrl(file) 方法，为给定文件生成签名 URL。

    ¥Implement the getSignedUrl(file) method in the aws-s3 provider to generate a signed URL for the given file.

/providers/aws-s3/index.js
// aws-s3 provider

module.exports = {
  init: (config) => {
    const s3 = new AWS.S3(config);

    return {
      async upload(file) {
        // code to upload file to S3
      },

      async delete(file) {
        // code to delete file from S3
      },

      async isPrivate() {
        return true;
      },

      async getSignedUrl(file) {
        const params = {
          Bucket: config.params.Bucket,
          Key: file.path,
          Expires: 60, // URL expiration time in seconds
        };

        const signedUrl = await s3.getSignedUrlPromise("getObject", params);
        return { url: signedUrl };
      },
    };
  },
};
Contribute to this page