配置概览

Payload 是一个基于配置的、代码优先的内容管理系统和应用框架。Payload 配置是 Payload 工作的核心，它允许您通过简单直观的 API 深入配置您的应用程序。Payload 配置是一个完全类型的 JavaScript 对象，可以无限扩展。

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

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

import { buildConfig } from 'payload'
export default buildConfig({
  // 您的配置在这里
})

Payload 配置是强类型的，并且直接与 Payload 的 TypeScript 代码库相关联。这意味着您的 IDE（例如 VSCode）在您编写配置时会提供有用的信息，如类型提示建议。

提示： 您的 Payload 配置的位置可以自定义。更多细节。

配置选项

要编写您的 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',
        },
      ],
    },
  ],
})

注意： 更多复杂的例子，请查看 Payload 仓库中的模板和示例目录。

以下是可用的选项：

* 星号表示属性是必需的。

注意： 一些属性从客户端捆绑包中移除。更多细节。

TypeScript 配置

Payload 提供了多种 TypeScript 设置，您可以利用这些设置。这些设置用于为您的集合和全局自动生成 TypeScript 接口，并确保 Payload 使用您的生成类型用于所有本地 API方法。

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

import { buildConfig } from 'payload'
export default buildConfig({
  // ...
  typescript: {
    // ...
  }
})

以下是可用的选项：

配置位置

对于 Payload 命令行脚本，我们需要能够定位您的 Payload 配置。默认情况下，我们会检查多种位置是否存在 payload.config.ts，包括：

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

* 配置位置检测在开发和生产环境之间有所不同。详见下文。

重要： 确保您的 tsconfig.json 正确配置，以便 Payload自动检测您的配置位置。如果它不存在或未指定正确的 compilerOptions，Payload 将默认使用当前工作目录。

开发模式

在开发模式下，如果配置文件不在根目录找到，Payload 将尝试读取您的 tsconfig.json，并尝试在 rootDir 中找到配置文件：

{
  // ...
  "compilerOptions": {
    "rootDir": "src"
  }
}

生产模式

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

{
  // ...
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  }
}

如果两个位置都没有找到，Payload 最后会检查 dist 目录。

自定义配置位置

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

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

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

提示： PAYLOAD_CONFIG_PATH 可以是绝对路径，也可以是相对于当前工作目录的路径。

遥测

Payload 收集完全匿名的遥测数据，以了解一般使用情况。这些数据对我们非常重要，帮助我们准确了解我们的增长情况，以及我们可以做些什么来构建软件，使其尽可能地发挥潜力。我们收集的遥测数据还帮助我们以准确的方式展示我们的增长，这有助于我们寻求投资以构建和扩展我们的团队。如果我们要准确展示我们的增长，我们可以更有效地继续支持 Payload 作为免费和开源软件。要退出遥测，您可以在 Payload 配置中传递 telemetry: false。

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

跨源资源共享 (CORS)

可以配置跨源资源共享 (CORS)，允许来自白名单数组的 URL 的 CORS 请求，接受来自任何域的传入请求的通配符字符串 (*)，或者具有以下属性的对象：

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

import { buildConfig } from 'payload'
export default buildConfig({
  // ...
  cors: '*'
})

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

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

TypeScript

您可以从 Payload 导入类型，以帮助使编写配置更容易和类型安全。有两个主要类型代表 Payload 配置，Config 和 SanitizedConfig。

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

import type { Config, SanitizedConfig } from 'payload'

服务器与客户端

Payload 配置仅存在于服务器上，不允许包含任何客户端代码。这样，您可以在任何服务器环境或独立脚本中加载 Payload 配置，而无需使用打包器或 Node.js 加载器来处理导入仅限客户端模块（例如 scss 文件或 React 组件）的错误。

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

兼容性标志

Payload 配置可以接受兼容性标志，以便在运行最新版本时与旧数据库兼容。只有在您确实需要时才应使用这些标志，并在启用这些标志之前确认您确实需要它们。

allowLocalizedWithinLocalized

Payload 的本地化工作是在字段级别进行的。由于您可以将字段嵌套在其他字段内，您可能会在本地化字段内嵌套另一个本地化字段，但这将是多余的且不必要的。在父字段已经本地化的情况下，定义一个本地化字段在本地化父字段内是没有意义的，因为从父字段开始的整个数据结构都将被本地化。

默认情况下，如果父字段是本地化的，Payload 会从子字段中移除 localized: true 属性。只有在您有一个旧的 Payload MongoDB 数据库，并且您希望在不进行迁移的情况下保持嵌套的本地化字段时，才将此兼容性标志设置为 true。

使用自定义配置位置

如果您的 Payload 配置不在标准位置，或者您希望在多个配置之间切换，可以通过设置环境变量 PAYLOAD_CONFIG_PATH 来指定自定义配置位置。这可以通过在项目根目录下的 package.json 中的脚本部分添加环境变量来实现：

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

在这里，./custom-config/path 应替换为您的 payload.config.ts 文件的实际路径。

遥测数据

Payload 收集匿名遥测数据以帮助我们了解产品的使用情况和增长趋势。这些数据对于我们来说非常重要，因为它们帮助我们更好地了解如何改进产品，并为我们寻求投资以支持和扩展 Payload 提供支持。如果您希望退出遥测数据收集，可以在 Payload 配置文件中设置 telemetry: false。

CORS 配置

CORS 配置允许您控制哪些外部域可以访问您的 API。您可以设置一个白名单数组，或者使用通配符 '*' 来接受所有域的请求。此外，您还可以自定义 Access-Control-Allow-Headers 响应头，以允许特定的自定义头。

TypeScript 集成

Payload 提供了 TypeScript 类型支持，使得配置文件的编写更加类型安全。您可以从 Payload 导入 Config 和 SanitizedConfig 类型，以帮助您在编写配置时获得更好的类型检查和自动完成支持。

服务器与客户端的区分

Payload 配置仅在服务器端使用，不包含任何客户端代码。这意味着您可以在任何服务器环境中加载 Payload 配置，而无需担心客户端模块的导入问题。Next.js 管理面板会自动生成一个客户端配置版本，该版本剥离了服务器端代码，并添加了 React 组件。

通过这些配置选项和设置，Payload 提供了高度的灵活性和可定制性，使您能够根据您的具体需求调整和优化您的应用框架。如果您有任何疑问或需要进一步的帮助，请不要犹豫，查阅 Payload 的官方文档或社区资源。