Payload 配置

Payload 是一个基于配置、代码优先的 CMS 和应用框架。Payload Config 是 Payload 所有功能的核心，通过简单直观的 API 实现对应用的深度配置。Payload Config 是一个完全类型化的 JavaScript 对象，可以无限扩展。

从数据库选择到管理面板的外观，一切都通过 Payload Config 完全控制。你可以在这里定义字段、添加本地化、启用认证、配置访问控制等等。

Payload Config 通常是一个位于项目根目录下的 payload.config.ts 文件：

import { buildConfig } from 'payload'

export default buildConfig({
  // 你的配置写在这里
})

Payload Config 采用强类型设计，直接与 Payload 的 TypeScript 代码库集成。这意味着你的 IDE（如 VSCode）会在编写配置时提供类型提示等有用信息。

配置选项

要编写你的 Payload 配置，首先确定你想要使用的 数据库，然后通过 字段 使用 集合 或 全局数据 来定义你的数据结构。

以下是一个最简单的 Payload 配置示例：

import { buildConfig } from 'payload'
import { mongooseAdapter } from '@payloadcms/db-mongodb'

export default buildConfig({
  secret: process.env.PAYLOAD_SECRET,
  db: mongooseAdapter({
    url: process.env.DATABASE_URI,
  }),
  collections: [
    {
      slug: 'pages',
      fields: [
        {
          name: 'title',
          type: 'text',
        },
      ],
    },
  ],
})

以下是可用的配置选项：

* 星号表示该属性是必填项。

TypeScript 配置

Payload 提供了多种 TypeScript 设置供你使用。这些设置用于为你的 Collections 和 Globals 自动生成 TypeScript 接口，并确保 Payload 在所有 Local API 方法中使用你的 Generated Types。

要自定义 TypeScript 设置，请在 Payload Config 中使用 typescript 属性：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  typescript: {
    // highlight-line
    // ...
  },
})

以下是可用的配置选项：

配置文件位置

对于 Payload 命令行脚本，我们需要能够定位到你的 Payload 配置文件。默认情况下，我们会在以下位置检查是否存在 payload.config.ts：

1. 当前工作目录的根目录
2. tsconfig 中的 compilerOptions 设置*
3. dist 目录*

* 开发环境和生产环境下的配置文件位置检测方式不同。详情见下文。

开发模式

在开发模式下，如果在根目录未找到配置文件，Payload 会尝试读取你的 tsconfig.json，并尝试在 rootDir 指定的目录中查找配置文件：

{
  // ...
  // highlight-start
  "compilerOptions": {
    "rootDir": "src"
  }
  // highlight-end
}

生产模式

在生产模式下，Payload 会首先尝试在 tsconfig.json 的 outDir 目录中查找配置文件，如果未找到，则会回退到 rootDir 指定的目录：

{
  // ...
  // highlight-start
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  }
  // highlight-end
}

如果以上位置都未找到配置文件，Payload 最后会检查 dist 目录。

自定义配置文件位置

除了上述自动检测机制外，你还可以为 Payload 配置文件指定自定义位置。这在配置文件不在标准位置，或者你需要在多个配置之间切换时非常有用。为此，Payload 提供了一个环境变量来绕过所有自动配置检测。

要使用自定义配置文件位置，请设置 PAYLOAD_CONFIG_PATH 环境变量：

{
  "scripts": {
    "payload": "PAYLOAD_CONFIG_PATH=/path/to/custom-config.ts payload"
  }
}

遥测数据

Payload 会收集完全匿名的通用使用情况遥测数据。这些数据对我们非常重要，能帮助我们准确了解增长情况，并指导我们如何将软件发展得更好。收集的遥测数据还能帮助我们准确展示增长趋势，这对我们寻求投资以建设和扩展团队至关重要。如果我们能准确展示增长情况，就能更有效地继续将 Payload 作为免费开源软件进行维护。要禁用遥测功能，你可以在 Payload 配置中设置 telemetry: false。

有关我们跟踪内容的更多信息，请查看我们的隐私政策。

跨域资源共享 (CORS)

跨域资源共享 (CORS) 可以通过以下方式配置：使用允许发起 CORS 请求的 URL 白名单数组、接受来自任何域的请求的通配符字符串 (*)，或者包含以下属性的对象：

以下示例展示如何允许来自任何域的请求：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  cors: '*', // highlight-line
})

以下示例展示如何在 Access-Control-Allow-Headers 中附加新头 (x-custom-header)：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  // highlight-start
  cors: {
    origins: ['http://localhost:3000'],
    headers: ['x-custom-header'],
  },
  // highlight-end
})

TypeScript

你可以从 Payload 导入类型，以便更轻松地编写配置并确保类型安全。有两个主要类型代表 Payload 配置：Config 和 SanitizedConfig。

Config 类型代表完整形式的原始 Payload 配置。只有最基本的属性被标记为必需。SanitizedConfig 类型代表经过完全清理后的 Payload 配置。通常，这仅在 Payload 内部使用。

import type { Config, SanitizedConfig } from 'payload'

服务端 vs 客户端

Payload Config 仅存在于服务端，不允许包含任何客户端代码。这样，你可以在任何服务器环境或独立脚本中加载 Payload Config，而无需使用 Bundlers 或 Node.js 加载器来处理仅客户端模块（例如 scss 文件或 React 组件），且不会出现任何错误。

在幕后，基于 Next.js 的管理面板会生成一个 ClientConfig，它会剥离所有仅限服务端的代码，并用 React 组件丰富配置。

兼容性标志

Payload Config 可以接受兼容性标志，以便在较旧数据库上运行最新版本。你应该仅在需要时使用这些标志，并在启用前确认确实需要它们。

allowLocalizedWithinLocalized

Payload 的本地化功能是按字段逐个实现的。由于你可以在其他字段中嵌套字段，理论上可以将本地化字段嵌套在另一个本地化字段中——但这将是冗余且不必要的。考虑到从父字段开始的整个数据结构都将被本地化，没有理由在已本地化的父字段内再定义本地化字段。

默认情况下，如果父字段已本地化，Payload 会从子字段中移除 localized: true 属性。仅当你有一个来自 3.0 版本之前的现有 Payload MongoDB 数据库，并且希望保留嵌套的本地化字段而不进行迁移时，才将此兼容性标志设置为 true。

自定义 bin 脚本

通过 bin 配置属性，你可以向 npx payload 注入自定义脚本。以 pnpm payload seed 为例：

第一步：在与 payload.config.ts 相同的目录下创建 seed.ts 文件，内容如下：

import type { SanitizedConfig } from 'payload'

import payload from 'payload'

// 脚本必须导出一个名为 "script" 的函数，该函数接受 sanitized config
export const script = async (config: SanitizedConfig) => {
  await payload.init({ config })
  await payload.create({
    collection: 'pages',
    data: { title: 'my title' },
  })
  payload.logger.info('成功完成数据播种！')
  process.exit(0)
}

第二步：将 seed 脚本添加到 bin 配置中：

export default buildConfig({
  bin: [
    {
      scriptPath: path.resolve(dirname, 'seed.ts'),
      key: 'seed',
    },
  ],
})

现在你可以通过以下命令运行该脚本：

pnpm payload seed