安装

软件要求

Payload 需要以下软件：

  • 任何 JavaScript 包管理器（Yarn、NPM 或 pnpm - 推荐使用 pnpm）
  • Node.js 版本 20.9.0+
  • 任何兼容的数据库（MongoDB 或 Postgres）

重要： 在继续之前，请确保您已满足上述要求。

使用 create-payload-app 快速开始

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

  1. 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。

注意： Payload 需要 Next.js 版本 15 或更高。

1. 安装相关包

首先，您需要将所需的 Payload 包添加到您的项目中，运行以下命令：

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

注意： 如果您使用的是 NPM，可能需要使用遗留对等依赖项安装：npm i --legacy-peer-deps。

接下来，安装一个数据库适配器。Payload 需要数据库适配器来建立数据库连接。Payload 可以与所有类型的数据库一起工作，但最常见的是 MongoDB 和 Postgres。

要安装数据库适配器，您可以运行以下命令之一：

注意： 新的数据库适配器每天都在增加。请查看文档以获取最新的可用列表。

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

Payload 直接安装在您的 Next.js /app 文件夹中，您需要将一些文件放入该文件夹中以便 Payload 运行。您可以从 GitHub 上的Blank Template) 复制这些文件。一旦您在 /app 文件夹中放置了所需的 Payload 文件，您应该拥有如下结构：

  1. app/
  2. ├─  (payload)/
  3. │   ├── // Payload files
  4. ├─  (my-app)/
  5. │   ├── // Your app files

《对于 (payload) 目录的确切参考，请查看项目结构。》

您可能需要将所有现有的前端文件，包括您现有的根布局，复制到您自己新创建的路由组中，例如 (my-app)。

Payload 需要在您的 /app 文件夹中的文件不会重新生成，并且永远不会改变。一旦您将它们放入其中，您就再也不需要重新访问它们。它们不应该被编辑，并且只是从 @payloadcms/next 导入 REST/GraphQL API 和管理面板的 Payload 依赖项。

您可以将 (my-app) 文件夹命名为任何您想要的名称。名称并不重要，只会用于澄清您的目录结构。常见的名称可能是 (frontend)、(app) 或类似名称。更多细节。

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

Payload 有一个 Next.js 插件，它使用该插件确保与 Payload 依赖的一些包兼容，如 mongodb 或 drizzle-kit。

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

  1. import { withPayload } from '@payloadcms/next/withPayload'
  3. /* @type {import('next').NextConfig} */
  4. const nextConfig = {
  5.   // Your Next.js config here
  6.   experimental: {
  7.     reactCompiler: false
  8.   }
  9. }
  11. // Make sure you wrap your `nextConfig`
  12. // with the `withPayload` plugin
  13. export default withPayload(nextConfig)

重要： Payload 是一个完全的 ESM 项目，这意味着 withPayload 函数是一个 ECMAScript 模块。

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

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

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

无论哪种情况，如果您的 next.config 文件中的所有 require 和 export 尚未设置为 import / export，则需要进行转换。

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

最后，您需要创建一个Payload 配置。通常 Payload 配置位于您的仓库根目录，或紧邻您的 /app 文件夹，并且被命名为 payload.config.ts。

以下是 Payload 至少需要的内容：

  1. import sharp from 'sharp'
  2. import { lexicalEditor } from '@payloadcms/richtext-lexical'
  3. import { mongooseAdapter } from '@payloadcms/db-mongodb'
  4. import { buildConfig } from 'payload'
  6. export default buildConfig({
  7.   // If you'd like to use Rich Text, pass your editor here
  8.   editor: lexicalEditor(),
  10.   // Define and configure your collections in this array
  11.   collections: [],
  13.   // Your Payload secret - should be a complex and secure string, unguessable
  14.   secret: process.env.PAYLOAD_SECRET  ||  '',
  16.   // Whichever Database Adapter you're using should go here
  17.   // Mongoose is shown as an example, but you can also use Postgres
  18.   db: mongooseAdapter({
  19.     url: process.env.DATABASE_URI  ||  '',
  20.   }),
  22.   // If you want to resize images, crop, set focal point, etc.
  23.   // make sure to install it and pass it to the config.
  24.   // This is optional - if you don't need to do these things,
  25.   // you don't need it!
  26.   sharp,
  27. })

虽然这只是最基本的配置，但您可以在这里控制的选项有很多。要参考完整配置及其所有选项，请点击这里。

一旦您有了 Payload 配置，更新您的 tsconfig 以包含指向它的 path：

  1. {
  2.   "compilerOptions": {
  3.     "paths": {
  4.       "@payload-config": [
  5.         "./payload.config.ts"
  6.       ]
  7.     }
  8.   },
  9. }

5. 启动它！

到达这一点后，是时候启动 Payload 了。在应用程序的文件夹中启动您的项目以开始。默认情况下，Next.js 开发脚本是 pnpm dev（如果使用 NPM，则为 npm run dev）。

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

关于您提到的网页链接，由于网络原因，解析并没有成功。这可能与链接有关，也可能与网络有关。如果您需要这些网页的解析内容，建议您检查网页链接的合法性，并适当重试。如果链接无误且网络稳定，但问题仍然存在，可能需要进一步的技术支持。如果您不需要这些链接的解析内容，上述安装指南应该可以帮助您开始使用 Payload。