在 Next.js 之外使用 Payload

Payload 可以完全脱离 Next.js 使用，这在运行脚本、在单独的后端服务中使用 Payload，或者在其他前端框架（如 SvelteKit、Remix、Nuxt 等）中直接通过 Payload 的 Local API 从数据库获取数据时非常有用。

注意： Payload 及其所有官方包都是完全基于 ESM 的。如果你想在自己的项目中使用 Payload，请确保以 ESM 格式编写脚本，或者动态导入 Payload 配置。

在 Next.js 之外导入 Payload 配置

Payload 提供了一种便捷的方式来运行独立脚本，这对于诸如数据库种子填充或执行一次性操作等任务非常有用。

在独立脚本中，你可以直接导入 Payload 配置并立即使用。如果需要初始化后的 Payload 实例，可以使用 getPayload 函数。这对于数据库种子填充或执行其他一次性操作等任务非常有用。

import { getPayload } from 'payload'
import config from '@payload-config'

const seed = async () => {
  // 通过传入你的配置获取 Payload 本地实例
  const payload = await getPayload({ config })

  const user = await payload.create({
    collection: 'users',
    data: {
      email: 'dev@payloadcms.com',
      password: 'some-password',
    },
  })

  const page = await payload.create({
    collection: 'pages',
    data: {
      title: 'My Homepage',
      // 其他需要填充的数据
    },
  })
}

// 调用函数来运行你的种子脚本
await seed()

然后你可以使用 payload run 命令执行该脚本。例如：如果你将这个独立脚本放在 src/seed.ts 中，可以这样执行：

payload run src/seed.ts

payload run 命令为你做了两件事：

  1. 它以与 Next.js 相同的方式加载环境变量，无需额外依赖如 dotenv。不建议使用 dotenv，因为 Next.js 加载环境变量的方式不同。通过使用 payload run，你可以确保 Payload 和 Next.js 设置之间的环境变量处理保持一致。
  2. 它初始化了 tsx，允许直接执行 TypeScript 文件，无需手动安装 tsx 或 ts-node 等工具。

故障排除

如果遇到导入相关错误，你有两个选择：

选项1：通过在 payload 命令后添加 --use-swc 启用 swc 模式：

示例：

payload run src/seed.ts --use-swc

注意：请先在项目中安装 @swc-node/register。虽然 swc 模式比默认的 tsx 模式更快，但某些导入可能会出现问题。

选项2：使用替代运行时如 bun

虽然我们不保证对替代运行时的支持，但你可以自由使用它们，并通过在 payload 命令后添加 --disable-transpile 标志来禁用 Payload 自身的转译功能：

bunx --bun payload run src/seed.ts --disable-transpile

此方法需要你的系统已安装 bun。