Payload CMS 全栈框架上手指南：在 Next.js `/app` 目录中原生运行的 Headless CMS 与后端框架

Payload CMS 全栈框架上手指南：在 Next.js/app目录中原生运行的 Headless CMS 与后端框架

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload

Payload 是一个开源的、Next.js 原生的全栈应用框架，它可以直接安装进你现有的/app目录，同时扮演"无头 CMS"与"应用框架"两个角色，让 TypeScript 后端、可视化后台和前端页面同处一个项目。本指南以仓库根目录 README.md 为骨架，结合仓库内的官方文档、CLI 源码与模板实现，带你掌握从零初始化、一键云部署、模板选型到核心功能落地（认证、版本、本地化、富文本、权限、钩子）的完整路径。

什么是 Payload：首个 Next.js 原生的 CMS

按 README.md 的定位，Payload 是"首个可以直接安装进现有/app目录的 Next.js 原生 CMS"，官方称之为无头 CMS 的新时代开端。它本质上同时具备两种能力：

• 应用框架（App Framework）：提供完整的 TypeScript 后端与数据层，支持Auth、Versions/Drafts、Localization、Hooks、Access Control等后端能力；
• 无头 CMS（Headless CMS）：自带一套完全基于 React 的可视化后台（Admin Panel），并暴露 REST 与 GraphQL API。

相比传统 CMS（README 中直接对比的对象是"旧式 WordPress 代码"），它提供的核心差异点包括：

仓库的版本状态也可以佐证其技术栈：核心包payload的 package.json 声明为 "Node, React, Headless CMS and Application Framework built on Next.js"，并在关键字中列出 admin panel、graphQL、self hosted、next.js、typescript 等；整个 monorepo 采用 pnpm workspace 组织（见 pnpm-workspace.yaml），核心包源码位于 packages/payload/src。

快速开始：用 create-payload-app 启动一个新项目

先决条件

在运行快速开始命令前，官方安装文档 docs/getting-started/installation.mdx 列出了以下软件要求，请先核对环境：

• Node.js24.15.0及以上；
• Next.js16.2.6及以上（并非所有 Next.js 15/16 版本都兼容，务必使用上述支持范围）；
• TypeScript6.0.3及以上（旧版本不保证类型可用）；
• 任一 JavaScript 包管理器（pnpm、npm 或 yarn 2+；官方偏好 pnpm，yarn 1.x 不被支持）；
• 任一兼容数据库（MongoDB、Postgres 或 SQLite，docs/database/overview.mdx 列出了完整的适配器列表）。

一条命令完成脚手架

仓库根目录的 README.md 给出的快速开始命令为：

pnpx create-payload-app@latest

若想获得功能最全的起点，README 建议直接使用 website 模板：

pnpx create-payload-app@latest -t website

运行后按交互提示即可得到一个新的、可运行的 Payload 项目目录。create-payload-app的本质是一个独立 CLI 包，其源码位于 packages/create-payload-app，使用说明见 packages/create-payload-app/README.md，支持以下常用参数：

$ npx create-payload-app $ npx create-payload-app my-project $ npx create-payload-app -n my-project -t website OPTIONS -n my-payload-app 设置项目名 -t template_name 选择特定模板 --use-npm 用 npm 安装依赖 --use-yarn 用 yarn 安装依赖 --use-pnpm 用 pnpm 安装依赖 --no-deps 不安装任何依赖 -h 显示帮助

可选模板包括blank（空白模板）、blank-tanstack（TanStack Start 空白模板）、website（网站模板）、ecommerce（电商模板）、plugin（Payload 插件开发模板）、payload-demo、payload-website等。此外，当在已兼容的 Next.js、TanStack Start 或常规 TanStack Router 项目内不带项目名运行该 CLI 时，它会把 Payload 直接初始化进当前项目（纯 Router 项目会在确认后转换为 TanStack Start 项目）——这一点与仓库中 packages/create-payload-app/src/commands.ts 导出的initNext、initTanStack两条初始化路径相互印证。

在已有 Next.js 应用中手动安装

如果你希望在既有项目中集成 Payload，可以跳过脚手架手动安装，官方流程见 docs/getting-started/installation.mdx，核心分五步：

第 1 步：安装依赖包。先安装核心运行时与 Next.js 集成层：

pnpm i payload @payloadcms/next

再按需安装可选包：@payloadcms/richtext-lexical（富文本编辑器，不用富文本可不装）、sharp（上传集合的图片缩放/裁剪/焦点，仅在需要时）、graphql（仅在要用 GraphQL API 时）。注意：若使用 npm，可能需要npm i --legacy-peer-deps。

第 2 步：安装数据库适配器，三选一：

pnpm i @payloadcms/db-mongodb # MongoDB pnpm i @payloadcms/db-postgres # Postgres pnpm i @payloadcms/db-sqlite # SQLite

第 3 步：把 Payload 所需文件放入/app。Payload 直接运行在 Next.js 的/app目录里，你需要在其中放置一组位于(payload)路由组内的文件（可参照空白模板templates/blank）。这些文件只负责从@payloadcms/next引入 REST/GraphQL API 与 Admin Panel，安装后不需要再改动；你自己的前端文件则放进自建的另一个路由组，例如(my-app)、(frontend)、(app)，目录名随意，仅用于理清结构：

app/ ├─ (payload)/ │ └── // Payload 文件（一次性放好，不再改动） └─ (my-app)/ └── // 你的应用文件

仓库 test/__helpers 与 templates/blank 中保留了大量该结构的实际实现可供对照；本仓库根目录下的app/(payload)与app/(app)正是这套布局的活例子。

第 4 步：接入withPayload并创建配置。在next.config中包裹官方插件：

import { withPayload } from '@payloadcms/next/withPayload' const nextConfig = { // 你的 Next.js 配置 } export default withPayload(nextConfig)

由于 Payload 是完整 ESM 项目，withPayload是 ECMAScript 模块：要么在package.json中加入"type": "module"，要么把 Next 配置文件名改为.mjs后缀，并把其中所有require改为import。然后创建最小可用的payload.config.ts：

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: [], // 在此定义集合 secret: process.env.PAYLOAD_SECRET || '', // 高复杂度、不可猜测的密钥 db: mongooseAdapter({ // 此处以 Mongoose 为例，也可换 Postgres/SQLite url: process.env.DATABASE_URL || '', }), sharp, // 上传图片裁剪/焦点（可选） })

随后在tsconfig.json中声明指向配置文件的路径别名：

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

第 5 步：启动。运行pnpm dev（或npm run dev），访问http://localhost:3000/admin创建第一个 Payload 用户即可开始使用。

一键部署：Cloudflare Workers 与 Vercel 的无服务器方案

README 明确提供了两种"一键部署"路径，两者都基于无服务器架构、免去自建基础设施的繁琐：

• Cloudflare：完全自包含，一键部署到Workers，上传走R2，数据库用全局复刻的 D1。仓库内对应的数据库适配器为 packages/db-d1-sqlite，并有配套模板 templates/with-cloudflare-d1 可供参考。
• Vercel：一体化方案，一键部署Next.js前端，配合Neon数据库与Vercel Blob媒体存储。对应存储适配器见 packages/storage-vercel-blob，并参考模板 templates/with-vercel-website、templates/with-vercel-mongodb、templates/with-vercel-postgres。

这也是 README 反复强调"部署在无服务器环境也毫无障碍"的能力基础——由于 Payload 构建在 Next.js 之上，其路由、认证 Cookie 与数据库查询都以服务端可运行方式实现。模板中诸如 templates/with-cloudflare-d1、templates/with-postgres 均给出了真实的云环境配置样例，动手前可以逐一对照。

模板生态：生产级全栈起点

README 着重强调模板的价值：这些是生产就绪、端到端的方案，用于加速上线任何类型的网站、电商店铺、博客或作品集，前端统一基于React Server Components与Tailwind构建。仓库根目录templates下实际维护了多套模板：

• website（templates/website）：README 强烈推荐新手以此入门——它演示了"一切"：自定义富文本块、按需重新验证（on-demand revalidation）、实时预览（live preview）等，且自带基于 Tailwind 的前端，全部放在同一个/app目录；
• ecommerce（templates/ecommerce）：电商全栈模板；
• blank / blank-tanstack：空白与 TanStack Start 空白起点（templates/blank、templates/blank-tanstack）；
• with-cloudflare-d1 / with-postgres / with-vercel-mongodb / with-vercel-postgres / with-vercel-website：面向特定部署目标（见templates目录），可直接作为云端/数据库配置参考。

模板会持续扩充。除了官方模板，社区还可以通过给仓库添加payload-templatetopic 让更多开发者发现自己的模板。

示例目录：从认证到多租户的完整范式

除模板外，仓库的 examples 目录还提供了一批可独立运行的示例，覆盖多种集成方式。运行任意一个示例同样走 CLI 通道：

npx create-payload-app --example example_name

仓库内实际收录的示例包括：astro（与 Astro 站点搭配）、auth、custom-components、custom-server、draft-preview（草稿与预览）、email、form-builder（表单构建器）、live-preview（实时预览）、localization（本地化多语言）、multi-tenant（多租户）、remix、tailwind-shadcn-ui（Tailwind + shadcn/ui）与whitelabel（白标）等，详见 examples。例如：

• 想学习认证与授权的最佳实践，直接研读 examples/auth 下含登录、会话管理的完整工程；
• 想理解"前端编写内容 + 后台实时预览"的完整闭环，参考 examples/live-preview，其配套能力还沉淀为@payloadcms/live-preview、@payloadcms/live-preview-react、@payloadcms/live-preview-vue三个官方包（packages/live-preview 等）。

核心功能清单与底层依据

README 的 "Payload Features" 是理解产品能力边界的重要索引，下面把每一项映射到仓库内可直接查阅的源码与文档，形成一条"官方宣称 → 实现证据"的对照链：

README 还强调"在服务端组件中直接查询数据库，无需 REST/GraphQL"。这一点在实际工程中通过 REST API（docs/rest-api/overview.mdx）与 GraphQL（docs/graphql/overview.mdx）之外的本地/直接查询能力实现，类型安全则来自"全 TypeScript + 数据自动类型生成"（docs/typescript/generating-types.mdx）。安全方面，README 提到的 HTTP-only Cookie、CSRF 防护等更细内容可继续参考 docs/authentication/cookies.mdx 与 docs/production/preventing-abuse.mdx。

插件生态：按需扩展的官方与社区插件

Payload 的可扩展性在插件系统上体现得最彻底——你可以安装插件来增删功能，也可以开发并分发自己的插件（为自己的仓库打上payload-plugintopic 方便他人发现）。当前仓库 monorepo 内置了大量官方插件包（见packages目录），覆盖常见业务场景：

• 站点能力：SEO（packages/plugin-seo）、重定向（packages/plugin-redirects）、搜索（packages/plugin-search）、嵌套文档（packages/plugin-nested-docs）；
• 业务集成：电商（packages/plugin-ecommerce）、Stripe 支付（packages/plugin-stripe）、表单构建器（packages/plugin-form-builder）、多租户（packages/plugin-multi-tenant）；
• 运维与工具：导入导出（packages/plugin-import-export）、Sentry 错误监控（packages/plugin-sentry）、MCP（Model Context Protocol，packages/plugin-mcp，支持 AI 工具直接对接后台能力）。

配套的存储适配器（packages/plugin-cloud-storage 及storage-s3、storage-azure、storage-gcs、storage-r2、storage-vercel-blob等）与邮件适配器（packages/email-nodemailer、packages/email-resend）进一步扩大了开箱即用的范围。每类插件的接入文档与使用范式可在 docs/plugins 下按名查阅。

迁移与文档地图

如果你正从旧版本升级：README 指向 v3 迁移指南，仓库内的 docs/migration-guide 同时维护了 v3（docs/migration-guide/v3.mdx）与 v4（docs/migration-guide/v4.mdx）两套指南，版本差异与破坏性变更可以在这里逐项核对。更完整的全量文档则以结构化 mdx 形式存放在 docs 目录，涵盖配置（docs/configuration）、数据库（docs/database）、字段（docs/fields）、队列（docs/jobs-queue）、查询（docs/queries）、上传（docs/upload）、性能与生产部署（docs/performance、docs/production）等主题，均可直接在仓库内翻阅。

参与贡献与获取帮助

• 贡献：本仓库的贡献指南见 CONTRIBUTING.md，同时仓库还维护了面向 AI 与开发者的协作说明（AGENTS.md、CLAUDE.md）；
• 示例与问题排查：examples 提供大量可运行的集成示例；遇到疑难可以先查阅 docs/troubleshooting/troubleshooting.mdx；
• 社区：官方鼓励通过仓库 Discussions、Issues 以及 Discord 服务器交流，README 明确表示"你遇到的困难很可能别人已经解决过"，先检索再提问是最高效的方式。

总而言之，Payload 的定位可以一句话概括：它是"Next.js 原生的全栈 CMS 框架"——要么用pnpx create-payload-app@latest数秒内获得一个全新项目，要么借助withPayload手动接入既有 Next.js 应用，再按需选择模板、示例、官方插件与数据库/存储适配器组合出适合业务形态的架构。结合本仓库内随时可读的文档、源码与测试，你完全有能力在理解其底层机制的前提下，把它作为自身产品的长期技术底座。

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload