存储适配器

Payload 提供了额外的存储适配器来处理文件上传。这些适配器允许你将文件存储在不同的位置，例如 Amazon S3、Vercel Blob Storage、Google Cloud Storage 等。

服务包
Vercel Blob@payloadcms/storage-vercel-blob
AWS S3@payloadcms/storage-s3
Azure@payloadcms/storage-azure
Google Cloud Storage@payloadcms/storage-gcs
Uploadthing@payloadcms/storage-uploadthing

Vercel Blob Storage

@payloadcms/storage-vercel-blob

安装

pnpm add @payloadcms/storage-vercel-blob

使用方法

  • 配置 collections 对象来指定哪些集合应使用 Vercel Blob 适配器。slug 必须 与你现有的集合 slug 匹配。
  • 确保在 Vercel 环境变量中设置了 BLOB_READ_WRITE_TOKEN。通常在项目中添加 blob 存储后，Vercel 会自动设置此变量。
  • 启用后，此包会自动将每个集合的 disableLocalStorage 设置为 true。
  • 部署到 Vercel 时，服务器上传限制为 4.5MB。将 clientUploads 设为 true 可直接在客户端进行上传。
import { vercelBlobStorage } from '@payloadcms/storage-vercel-blob'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  plugins: [
    vercelBlobStorage({
      enabled: true, // 可选，默认为 true
      // 指定哪些集合应使用 Vercel Blob
      collections: {
        media: true,
        'media-with-prefix': {
          prefix: 'my-prefix',
        },
      },
      // 在 Vercel 项目中添加 Blob 存储后提供的令牌
      token: process.env.BLOB_READ_WRITE_TOKEN,
    }),
  ],
})

配置选项

OptionDescriptionDefault
enabled是否启用该插件true
collections应用 Vercel Blob 适配器的集合
addRandomSuffix在 Vercel Blob 存储中为上传的文件名添加随机后缀false
cacheControlMaxAgeCache-Control max-age 缓存时间（秒）365 * 24 * 60 * 60 (1年)
tokenVercel Blob 存储的读写令牌''
clientUploads直接在客户端上传以绕过 Vercel 的限制

S3 存储

@payloadcms/storage-s3

安装

pnpm add @payloadcms/storage-s3

使用方法

  • 配置 collections 对象来指定哪些集合应使用 S3 存储适配器。slug 必须 匹配你现有的集合 slug。
  • config 对象可以是任何 S3ClientConfig 对象（来自 @aws-sdk/client-s3）。这高度依赖于你的 AWS 设置。更多信息请查阅 AWS 文档。
  • 启用后，此包会自动为每个集合将 disableLocalStorage 设置为 true。
  • 部署到 Vercel 时，服务器上传限制为 4.5MB。将 clientUploads 设置为 true 可直接在客户端进行上传。你必须为存储桶允许来自你网站的 CORS PUT 方法。
  • 配置 signedDownloads（全局或在 collections 中按集合配置）以使用 预签名 URL 进行文件下载。这可以提高大文件（如视频）的性能，同时仍遵守你的访问控制。
import { s3Storage } from '@payloadcms/storage-s3'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  plugins: [
    s3Storage({
      collections: {
        media: true,
        'media-with-prefix': {
          prefix,
        },
      },
      bucket: process.env.S3_BUCKET,
      config: {
        credentials: {
          accessKeyId: process.env.S3_ACCESS_KEY_ID,
          secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        },
        region: process.env.S3_REGION,
        // ... 其他 S3 配置
      },
    }),
  ],
})

配置选项

有关 AWS S3 配置的指导，请参阅 AWS SDK 包 和 S3ClientConfig 对象。

Azure Blob 存储

@payloadcms/storage-azure

安装

pnpm add @payloadcms/storage-azure

使用方法

  • 配置 collections 对象来指定哪些集合应使用 Azure Blob 适配器。slug 必须 匹配你现有的集合 slug。
  • 启用后，此包会自动将每个集合的 disableLocalStorage 设置为 true。
  • 部署到 Vercel 时，服务器上传限制为 4.5MB。将 clientUploads 设置为 true 可直接在客户端进行上传。你必须为你的网站允许 CORS PUT 方法。
import { azureStorage } from '@payloadcms/storage-azure'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  plugins: [
    azureStorage({
      collections: {
        media: true,
        'media-with-prefix': {
          prefix,
        },
      },
      allowContainerCreate:
        process.env.AZURE_STORAGE_ALLOW_CONTAINER_CREATE === 'true',
      baseURL: process.env.AZURE_STORAGE_ACCOUNT_BASEURL,
      connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
      containerName: process.env.AZURE_STORAGE_CONTAINER_NAME,
    }),
  ],
})

配置选项

Option描述默认值
enabled是否启用该插件true
collections应用 Azure Blob 适配器的 collections
allowContainerCreate当容器不存在时是否允许创建false
baseURLAzure Blob 存储账户的基础 URL
connectionStringAzure Blob 存储连接字符串
containerNameAzure Blob 存储容器名称
clientUploads直接在客户端上传以绕过 Vercel 的限制

Google Cloud Storage

@payloadcms/storage-gcs

安装

pnpm add @payloadcms/storage-gcs

使用方法

  • 配置 collections 对象来指定哪些集合应使用 Google Cloud Storage 适配器。slug 必须 与你现有的集合 slug 匹配。
  • 启用后，此包会自动将每个集合的 disableLocalStorage 设置为 true。
  • 部署到 Vercel 时，服务器上传限制为 4.5MB。将 clientUploads 设置为 true 可直接在客户端进行上传。你必须为存储桶允许来自你网站的 CORS PUT 方法。
import { gcsStorage } from '@payloadcms/storage-gcs'
import { Media } from './collections/Media'
import { MediaWithPrefix } from './collections/MediaWithPrefix'

export default buildConfig({
  collections: [Media, MediaWithPrefix],
  plugins: [
    gcsStorage({
      collections: {
        media: true,
        'media-with-prefix': {
          prefix,
        },
      },
      bucket: process.env.GCS_BUCKET,
      options: {
        apiEndpoint: process.env.GCS_ENDPOINT,
        projectId: process.env.GCS_PROJECT_ID,
      },
    }),
  ],
})

配置选项

Option描述默认值
enabled是否启用该插件true
collections应用该存储的 collections
bucket使用的存储桶名称
optionsGoogle Cloud Storage 客户端配置。参见文档
acl上传文件的访问控制列表Private
clientUploads直接在客户端上传以绕过 Vercel 的限制。

Uploadthing 存储

@payloadcms/storage-uploadthing

安装

pnpm add @payloadcms/storage-uploadthing

使用方法

  • 配置 collections 对象来指定哪些集合应使用 uploadthing。slug 必须 匹配你现有的集合 slug 并且是 upload 类型。
  • 从 Uploadthing 获取 token 并在 options 对象中设置为 token。
  • acl 是可选的，默认为 public-read。
  • 当部署到 Vercel 时，服务器上传限制为 4.5MB。将 clientUploads 设置为 true 可直接在客户端进行上传。
export default buildConfig({
  collections: [Media],
  plugins: [
    uploadthingStorage({
      collections: {
        media: true,
      },
      options: {
        token: process.env.UPLOADTHING_TOKEN,
        acl: 'public-read',
      },
    }),
  ],
})

配置选项

选项描述默认值
token来自 Uploadthing 的 token。必填项。
acl上传文件的访问控制列表public-read
logLevelUploadthing 的日志级别info
fetch自定义 fetch 函数fetch
defaultKeyType文件操作的默认键类型fileKey
clientUploads直接在客户端上传以绕过 Vercel 的限制。

自定义存储适配器

如果需要创建自定义存储适配器，可以使用 @payloadcms/plugin-cloud-storage 包。上述存储适配器内部都使用了这个包。

安装方法

pnpm add @payloadcms/plugin-cloud-storage

使用方法

可以参考现有的存储适配器来了解如何构建。创建一个遵循 GeneratedAdapter 接口的适配器，然后将适配器传递给 cloudStorage 插件。

export interface GeneratedAdapter {
  /**
   * 要注入到基础集合和图片尺寸中的额外字段
   */
  fields?: Field[]
  /**
   * 为文件生成公开 URL
   */
  generateURL?: GenerateURL
  handleDelete: HandleDelete
  handleUpload: HandleUpload
  name: string
  onInit?: () => void
  staticHandler: StaticHandler
}

import { buildConfig } from 'payload'
import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'

export default buildConfig({
  plugins: [
    cloudStorage({
      collections: {
        'my-collection-slug': {
          adapter: theAdapterToUse, // 查看你想使用的适配器文档
        },
      },
    }),
  ],
  // 其余配置写在这里
})

插件选项

该插件可配置为适用于多个不同的 Payload 集合。标有 * 的表示该属性为必填项。

选项类型描述
collections *Record<string, CollectionOptions>对象，键设置为要启用插件的集合 slug，值设置为特定于集合的选项。
enabledboolean有条件地启用/禁用插件。默认值：true。

集合特定选项

选项类型描述
adapter *Adapter传入你想用于此集合的适配器。你也可以在某些场景下将此字段设为 null 以绕过云存储并使用本地存储进行开发。
disableLocalStorageboolean选择是否禁用此集合的本地存储。默认为 true。
disablePayloadAccessControltrue设置为 true 以禁用 Payload 的访问控制。更多
prefixstring设置为 media/images 可将文件上传到存储桶中的 media/images 文件夹内。
generateFileURLGenerateFileURL用你自定义的 URL 覆盖生成的文件 URL。

Payload 访问控制

Payload 内置了访问控制功能，该功能_即使在静态文件服务时也会运行_。系统会使用你已启用 upload 的集合中的 read 访问控制属性，允许你限制谁可以请求上传的文件。

为了保留这一特性，默认情况下，本插件_保持所有文件URL完全不变_。你的文件URL不会被更新为直接指向云存储源，因为那样会完全绕过Payload的访问控制，你将需要在云托管文件上设置公共可读性。

相反，所有上传文件仍将通过默认的 /collectionSlug/staticURL/filename 路径访问。本插件会将托管在第三方云服务上的所有文件"透传"——额外的好处是保持你现有的访问控制不变。

如果这不适用于你（你的上传集合设置了 read: () => true 或类似配置），你可以通过将 disablePayloadAccessControl 设置为 true 来禁用此功能。启用此设置后，本插件将更新你的文件URL，使其直接指向云主机。

条件性启用/禁用

条件性启用/禁用本插件的正确方法是使用 enabled 属性。

cloudStoragePlugin({
  enabled: process.env.MY_CONDITION === 'true',
  collections: {
    'my-collection-slug': {
      adapter: theAdapterToUse, // 参阅你想使用的适配器文档
    },
  },
}),