企业官网建设流程全解析

Payload Local API 完全指南：在 React Server Components 中直连数据库查询

【免费下载链接】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 框架，既能当无头 CMS（Headless CMS），也能用于构建强大的应用。它的Local API让你在React Server Components（RSC）中直连数据库查询，无需经过 HTTP 层，让服务端渲染页面快如闪电。本文是面向新手的Local API 完整指南，带你掌握 Payload 最强的特性之一。

什么是 Local API？为什么它如此强大？

传统无头 CMS 的用法是：前端通过HTTP 请求调用第三方 CMS 服务，再取回数据。这一来一回的网络延迟，对服务端渲染页面来说是实打实的性能损耗。

Payload 的Local API彻底改变了这一模式：

• ✅零网络开销：直接在 Node.js 服务端执行与 REST / GraphQL 相同的操作
• ✅直连数据库：在 RSC、Seed 脚本、自定义 Route Handler 中同步读写数据
• ✅完整 TypeScript 类型推断：查询结果自动匹配你生成的类型
• ✅可开关访问控制：本地操作默认跳过 Access Control，也可按需启用

官方文档明确指出：在 RSC 等纯服务端上下文中使用 Local API，"可以快得惊人，绝对是游戏规则改变者"（详见 docs/local-api/overview.mdx）。

如何获取 payload 实例？

使用 Local API 前，你只需要拿到当前运行中的payload对象。两种获取方式：

方式一：从参数中获取（Payload 内部最常见）

在 Hooks、Access Control、字段校验等函数中，直接从req.payload或解构参数拿到payload，最简单直接。

方式二：手动导入并初始化（RSC 中的标准姿势）

import { getPayload } from 'payload' import config from '@payload-config' const payload = await getPayload({ config })

💡 开发模式下getPayload支持 HMR 热更新——你改 Payload 配置，RSC 里的查询立刻同步，无需重启。生产模式下则自动优化，代码写法完全不变。

在 RSC 中直连数据库查询：官方模板实战

Payload 官方website 模板就是最好的教材。在 getDocument.ts 中，整个查询逻辑只有寥寥数行：

async function getDocument(collection: Collection, slug: string, depth = 0) { const payload = await getPayload({ config: configPromise }) const page = await payload.find({ collection, depth, where: { slug: { equals: slug } }, }) return page.docs[0] }

注意这里还配合了 Next.js 的unstable_cache（见 getDocument.ts），按collection + slug缓存查询结果，数据库直连 + Next.js 缓存，性能直接拉满。

再看文章详情页 posts/[slug]/page.tsx：它用 React 的cache()包裹查询函数，并根据Draft Mode动态决定是否绕过访问控制（overrideAccess: draft），一行代码同时搞定了草稿预览和权限控制。

而 generateStaticParams/posts/[slug]/page.tsx#L18-L36) 则用select: { slug: true }只取需要的字段批量生成静态路由——只查要用的字段，这正是 Local APIselect选项的价值。

Local API 支持哪些操作？

Local API 覆盖了与 REST/GraphQL 相同的全部操作，且选项更多：

常用选项速览（完整列表见 overview.mdx）：

• depth：控制关系字段自动填充的深度
• select/populate：精准选取字段，减少数据传输
• overrideAccess：默认true，跳过访问控制（重要！）
• user：关闭 override 后可指定以哪个用户的权限执行
• disableErrors：出错时不抛异常，find返回空数组
• pagination: false：关闭分页计数，适合取全部数据

从前端触发后端：Server Functions

Local API 只能在服务端跑，那客户端按钮点击如何操作数据？答案是 Next.jsServer Functions（旧称 Server Actions）。参考 docs/local-api/server-functions.mdx：

'use server' import { getPayload } from 'payload' import config from '@payload-config' export async function createPost(data) { const payload = await getPayload({ config }) const post = await payload.create({ collection: 'posts', data }) return post }

客户端组件await createPost({...})即可，无需暴露完整 REST API，安全性与性能兼得。

安全提醒：overrideAccess 的正确姿势

⚠️ Local API默认跳过所有访问控制。在 RSC 服务端渲染公开页面时这通常没问题，但两种场景必须小心：

1. 需要权限校验的页面：设置overrideAccess: false并传入当前用户，让 Payload 按配置执行鉴权
2. 用户触发的写操作：在 Server Function 中检查用户角色后再执行，避免越权

官网模板的写法值得抄作业：overrideAccess: draft——只有开启草稿预览时才绕过权限（page.tsx/posts/[slug]/page.tsx#L94-L106)）。

离开 Next.js 也能用

Payload 完全支持脱离 Next.js 运行。在 docs/local-api/outside-nextjs.mdx 中可以看到，独立 Seed 脚本只需：

const payload = await getPayload({ config }) const user = await payload.create({ collection: 'users', data: {...} })

然后执行payload run src/seed.ts即可——它会自动加载环境变量（与 Next.js 一致）并初始化 TypeScript 运行时。同样的getPayload也适用于 Remix、SvelteKit、Nuxt 等框架。

关键路径速查

• 官方文档：docs/local-api/overview.mdx、docs/local-api/access-control.mdx
• 模板实战：templates/website/src/utilities/getDocument.ts、templates/website/src/app/(frontend)/posts/[slug]/page.tsx
• Local API 源码：packages/payload/src/collections/
• 类型生成：docs/typescript/generating-types.mdx

总结

一句话记住 Payload Local API 的价值：把「跨网络调 CMS」变成「同进程查数据库」。配合 RSC 的服务端渲染、Next.js 缓存和完整的 TypeScript 类型支持，Payload 让 Headless CMS 的性能短板直接消失。现在就试试把它用在你的 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