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/payloadPayload是一款开源的全栈 Next.js 框架既能当无头 CMSHeadless CMS也能用于构建强大的应用。它的Local API让你在React Server ComponentsRSC中直连数据库查询无需经过 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 相同的全部操作且选项更多操作说明payload.create()创建文档支持直接传filePath上传文件payload.find()/findByID()条件查询 / 按 ID 查询payload.count()/findDistinct()计数 / 去重查询payload.update()更新单个或批量where更新payload.delete()删除单个或批量删除payload.findGlobal()/updateGlobal()Global 全局文档读写payload.auth()/login()等认证相关操作常用选项速览完整列表见 overview.mdxdepth控制关系字段自动填充的深度select/populate精准选取字段减少数据传输overrideAccess默认true跳过访问控制重要user关闭 override 后可指定以哪个用户的权限执行disableErrors出错时不抛异常find返回空数组pagination: false关闭分页计数适合取全部数据从前端触发后端Server FunctionsLocal API 只能在服务端跑那客户端按钮点击如何操作数据答案是 Next.jsServer Functions旧称 Server Actions。参考 docs/local-api/server-functions.mdxuse 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 服务端渲染公开页面时这通常没问题但两种场景必须小心需要权限校验的页面设置overrideAccess: false并传入当前用户让 Payload 按配置执行鉴权用户触发的写操作在 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.tsxLocal 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考