安装指南

软件要求

Payload 需要以下软件环境：

• 任意 JavaScript 包管理器（pnpm、npm 或 yarn - 推荐使用 pnpm）
• Node.js 20.9.0 或更高版本
• 任意兼容的数据库（MongoDB、Postgres 或 SQLite）

使用 create-payload-app 快速开始

要最快地搭建一个新的 Payload 应用，可以使用 create-payload-app。运行以下命令：

npx create-payload-app

然后只需按照提示操作！你将获得一个包含完整 Payload 应用的新文件夹。之后可以开始配置你的应用。

添加到现有应用

将 Payload 添加到现有的 Next.js 应用非常简单。你可以在 Next.js 项目文件夹内运行 npx create-payload-app 命令，或者按照以下步骤手动安装 Payload。

如果你还没有 Next.js 应用，但仍想从一个空白 Next.js 项目开始，可以使用 npx create-next-app 创建新的 Next.js 应用 - 然后按照以下步骤安装 Payload。

1. 安装相关包

首先，你需要将所需的 Payload 包添加到项目中，可以通过运行以下命令完成：

pnpm i payload @payloadcms/next @payloadcms/richtext-lexical sharp graphql

接下来，安装一个数据库适配器。Payload 需要数据库适配器来建立数据库连接。Payload 支持所有类型的数据库，但最常用的是 MongoDB 和 Postgres。

要安装数据库适配器，可以运行以下任意一条命令：

• 安装 MongoDB 适配器：

  pnpm i @payloadcms/db-mongodb
  

• 安装 Postgres 适配器：

  pnpm i @payloadcms/db-postgres
  

• 安装 SQLite 适配器：

  pnpm i @payloadcms/db-sqlite
  

2. 将 Payload 文件复制到你的 Next.js 应用文件夹中

Payload 直接安装在你的 Next.js /app 文件夹中，你需要将一些文件放入该文件夹才能使 Payload 运行。你可以从 GitHub 上的 空白模板 复制这些文件。将所需的 Payload 文件放入 /app 文件夹后，你的目录结构应该类似这样：

app/
├─ (payload)/
├── // Payload 文件
├─ (my-app)/
├── // 你的应用文件

关于 (payload) 目录的精确参考，请查看 项目结构。

Payload 需要在你的 /app 文件夹中的文件不会重新生成，也永远不会改变。一旦你放置好它们，就无需再次修改。这些文件不需要编辑，它们只是从 @payloadcms/next 导入 Payload 的依赖项，用于 REST/GraphQL API 和管理面板。

你可以随意命名 (my-app) 文件夹。名称无关紧要，只是为了让你自己的目录结构更清晰。常见的名称可能是 (frontend)、(app) 或类似的。更多详情。

3. 将 Payload 插件添加到 Next.js 配置

Payload 提供了一个 Next.js 插件，用于确保与 Payload 依赖的一些包（如 mongodb 或 drizzle-kit）的兼容性。

要在 next.config.js 中添加 Payload 插件，请使用 withPayload：

import { withPayload } from '@payloadcms/next/withPayload'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 你的 Next.js 配置放在这里
  experimental: {
    reactCompiler: false,
  },
}

// 确保用 `withPayload` 插件
// 包裹你的 `nextConfig`
export default withPayload(nextConfig) // highlight-line

要导入 Payload 插件，你需要确保你的 next.config 文件配置为使用 ESM。

你可以通过以下两种方式之一实现：

1. 将你的项目设置为使用 ESM，即在 package.json 文件中添加 "type": "module"
2. 给你的 Next.js 配置文件添加 .mjs 扩展名

无论采用哪种方式，如果你的 next.config 文件中使用了 require 和 export，都需要将它们转换为 import / export 语法（如果尚未这样配置的话）。

4. 创建 Payload 配置并添加到 TypeScript 配置

最后，你需要创建一个 Payload 配置。通常 Payload 配置位于仓库根目录或 /app 文件夹旁，文件名为 payload.config.ts。

以下是 Payload 所需的最基本配置：

import sharp from 'sharp'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { buildConfig } from 'payload'

export default buildConfig({
  // 如需使用富文本编辑器，在此传入你的编辑器
  editor: lexicalEditor(),

  // 在此数组中定义和配置你的 collections
  collections: [],

  // Payload 密钥 - 应该是一个复杂且安全的字符串，不可猜测
  secret: process.env.PAYLOAD_SECRET || '',
  // 你使用的数据库适配器应放在这里
  // 示例中使用的是 Mongoose，但你也可以使用 Postgres
  db: mongooseAdapter({
    url: process.env.DATABASE_URI || '',
  }),
  // 如需调整图片大小、裁剪、设置焦点等
  // 请确保安装并传入该配置
  // 这是可选的 - 如果不需要这些功能，
  // 就不需要它！
  sharp,
})

虽然这只是最基本的配置，但你还可以在此控制更多选项。要查看完整配置及其所有选项，请点击这里。

创建 Payload 配置后，更新你的 tsconfig，添加指向该配置的 path：

{
  "compilerOptions": {
    "paths": {
      "@payload-config": ["./payload.config.ts"]
    }
  }
}

5. 启动！

完成以上步骤后，就可以启动 Payload 了。在你的应用文件夹中启动项目。默认情况下，Next.js 的开发脚本是 pnpm dev（如果使用 npm 则是 npm run dev）。

启动后，你可以访问 http://localhost:3000/admin 创建你的第一个 Payload 用户！