# 有效负载应用程序开发 Payload 是一个 Next.js 原生 CMS，采用 TypeScript 优先架构，提供管理面板、数据库管理、REST/GraphQL API、身份验证和文件存储。 ## 快速参考任务|解决方案 |详情 ---|---|--- 自动生成段 | `slugField()` | [FIELDS.md#slug-field-helper]() 按用户限制内容 |带查询的访问控制 | [ACCESS-CONTROL.md#row-level-security-with-complex-queries]() 本地API用户操作| `user` \+ `overrideAccess: false` | [QUERIES.md#access-control-in-local-api]() 草稿/发布工作流程 | `版本：{ 草稿：true }` | [COLLECTIONS.md#versioning--drafts]() 计算字段 | `virtual: true` 与 afterRead | [FIELDS.md#virtual-fields]() 条件字段 | `admin.condition` | [FIELDS.md#条件字段]() 自定义字段验证 | `验证`函数| [FIELDS.md#text-field]() 过滤关系列表|字段 | 上的“filterOptions” [FIELDS.md#relationship]() 选择特定字段 | `选择` 参数 | [QUERIES.md#local-api]() 自动设置作者/日期 | beforeChange 钩子 | [HOOKS.md#collection-hooks]() 防止钩环 | `req.context` 检查 | [HOOKS.md#hook-context]() 级联删除 | beforeDelete 钩子 | [HOOKS.md#collection-hooks]() 地理空间查询 |带有“near”/“within”的“point”字段 | [FIELDS.md#point-geolocation]() 反向关系| `join` 字段类型 | [FIELDS.md#join-fields]() Next.js 重新验证 | afterChange 中的上下文控制 | [HOOKS.md#nextjs-revalidation-with-context-control]() 按关系查询|嵌套属性语法 | [QUERIES.md#nested-properties]() 复杂查询 |与/或逻辑| [QUERIES.md#andor-logic]() 交易 |将 `req` 传递给操作 | [ADAPTERS.md#threading-req-through-operations]() 后台工作 |带有任务的作业队列 | [ADVANCED.md#jobs-queue]() 自定义 API 路由 |集合自定义端点 | [ADVANCED.md#custom-endpoints]() 云存储|存储适配器插件 | [ADAPTERS.md#storage-adapters]() 多语言 | `本地化` 配置 + `本地化：true` | [ADVANCED.md#localization]() 创建插件 | `（选项）=>（配置）=> 配置` | [PLUGIN-DEVELOPMENT.md#plugin-architecture]() 插件包设置 |带有SWC的封装结构| [PLUGIN-DEVELOPMENT.md#plugin-package-struct]() 将字段添加到集合 |地图集、传播领域 | [PLUGIN-DEVELOPMENT.md#adding-fields-to-collections]() 插件挂钩 |保留数组中现有的钩子 | [PLUGIN-DEVELOPMENT.md#adding-hooks]() 检查字段类型 |类型保护功能 | [FIELD-TYPE-GUARDS.md]() ## 快速入门 npx create-payload-app@latest my-app cd 我的应用程序 PNPM开发 ### 最小配置 import { buildConfig } from "payload"; 从“@payloadcms/db-mongodb”导入{mongooseAdapter}；从“@payloadcms/richtext-lexical”导入{ lexicalEditor }；从“路径”导入路径；从“url”导入{ fileURLToPath }； const 文件名 = fileURLToPath(import.meta.url); const dirname = path.dirname(filename); export default buildConfig({ 管理员：{ user: "users", 导入映射：{ baseDir: 路径.resolve(目录名), }, }, collections: [Users, Media], 编辑器： lexicalEditor(), secret: process.env.PAYLOAD_SECRET, 打字稿：{ 输出文件：path.resolve(dirname, "payload-types.ts"), }, 数据库：猫鼬适配器（{ url: process.env.DATABASE_URL, }), }); ## 基本模式 ### 基础收藏 import type { CollectionConfig } from "payload"; export const Posts: CollectionConfig = { slug：“帖子”，管理员：{ useAsTitle: "title", defaultColumns: ["title", "author", "status", "createdAt"], }, 字段：[ { name: "title", type: "text", required: true }, { name: "slug", type: "text", unique: true, index: true }, { name: "content", type: "richText" }, { 名称：“作者”，类型：“关系”，关系：“用户” }， ], 时间戳：真， }; 有关更多集合模式（验证、上传、草稿、实时预览），请参阅 [COLLECTIONS.md]()。 ### 常用字段 // 文本字段 { 名称：'标题'，类型：'文本'，必需：true } // 关系 { 名称：'作者'，类型：'关系'，relationTo：'用户'，必需：true } // Rich text { 名称：'内容'，类型：'richText'，必需：true } // 选择 { name: 'status', type: 'select', options: ['draft', 'published'], defaultValue: 'draft' } // 上传 { 名称：'图像'，类型：'上传'，relationTo：'媒体' } 对于所有字段类型（数组、块、点、连接、虚拟、条件等），请参阅 [FIELDS.md]()。 ### 钩子示例 export const Posts: CollectionConfig = { slug: "posts", 钩子：{ 更改前：[ 异步（{数据，操作}）=> { if (操作 === "创建") { data.slug = slugify(data.title); } 返回数据； }, ], }, 字段：[{名称：“标题”，类型：“文本”}]， }; 对于所有钩子模式，请参阅 [HOOKS.md]()。有关访问控制，请参阅 [ACCESS-CONTROL.md]()。 ### 具有类型安全的访问控制 import type { Access } from "payload"; 从“@/payload-types”导入类型{User}； // Type-safe access control 导出 const adminOnly: Access = ({ req }) => { const user = req.user 作为用户； return user?.roles?.includes("admin") ||错误的; }; // Row-level access control 导出 const ownPostsOnly: Access = ({ req }) => { const user = req.user 作为用户； if (!user) 返回 false； if (user.roles?.includes("admin")) return true; 返回{ 作者: { 等于: user.id }, }; }; ### 查询示例 // 本地API const posts = 等待有效负载.find({ collection: "posts", 其中：{ 状态：{等于：“已发布”}， "author.name": { 包含: "john" }, }, depth: 2, 限制：10， sort: "-createdAt", }); // 查询已填充的关系 const post = await payload.findByID({ 集合：“帖子”， id：“123”， depth: 2, // Populates relationships (default is 2) }); // 返回: { 作者: { id: "user123", name: "John" } } // 如果没有深度，关系仅返回 ID const post = await payload.findByID({ 集合：“帖子”， id: "123", depth: 0, }); // 返回：{ 作者：“user123” } 有关所有查询运算符和 REST/GraphQL 示例，请参阅 [QUERIES.md]()。 ### 获取有效负载实例 // 在 API 路由 (Next.js) 中从“有效负载”导入{ getPayload } 从“@payload-config”导入配置 export async function GET() { const payload = await getPayload({ config }) const posts = await payload.find({ 集合：'帖子'， }) 返回 Response.json(帖子) } // 在服务器组件中从“有效负载”导入{ getPayload } 从“@payload-config”导入配置 export default async function Page() { const 负载 = 等待 getPayload({ config }) const { docs } =等待payload.find({ collection: 'posts' }) return

{docs.map(post =>

{post.title}

)}

} ### Logger Usage // ✅ 有效：单个字符串 payload.logger.error("Something went wrong"); // ✅ Valid: object with msg and err payload.logger.error({ msg: "Failed to process", err: error }); // ❌ 无效：不要将错误作为第二个参数传递 payload.logger.error("Failed to process", error); // ❌ 无效：使用 `err` 而不是 `error`，使用 `msg` 而不是 `message` Payload.logger.error({ message: "失败", error: 错误 }); ## 安全陷阱 ### 1\. Local API Access Control (CRITICAL) **By default, Local API operations bypass ALL access control** , even when passing a user. // ❌ 安全 BUG：传递用户但忽略他们的权限等待有效负载.find({ 集合：“帖子”， user: someUser, // 访问控制被绕过！ }); // ✅ SECURE: Actually enforces the user's permissions await payload.find({ 集合：“帖子”，用户：某个用户， overrideAccess: false, // REQUIRED for access control }); **何时使用每个：** * `overrideAccess: true` (default) - Server-side operations you trust (cron jobs, system tasks) * `overrideAccess: false` \- 代表用户操作时（API 路由、webhooks）请参阅 [QUERIES.md#access-control-in-local-api]()。 ### 2\. Transaction Failures in Hooks **没有`req`的钩子中的嵌套操作会破坏事务原子性。** // ❌ DATA CORRUPTION RISK: Separate transaction 钩子：{ 更改后：[ 异步 ({ doc, req }) => { 等待 req.payload.create({ 集合：“审核日志”，数据: { docId: doc.id }, // 缺少 req - 在单独的事务中运行！ }); }, ]; } // ✅ ATOMIC：同一事务钩子：{ 更改后：[ 异步 ({ doc, req }) => { 等待 req.payload.create({ 集合：“审核日志”，数据: { docId: doc.id }, req, // Maintains atomicity }); }, ]; } 请参阅 [ADAPTERS.md#threading-req-through-operations]()。 ### 3\.无限钩环 **触发相同钩子的钩子触发操作会创建无限循环。** // ❌无限循环钩子：{ 更改后：[ 异步 ({ doc, req }) => { await req.payload.update({ 集合：“帖子”， id: 文档 ID, 数据：{视图：doc.views + 1}，要求， }); // Triggers afterChange again! }, ]; } // ✅ SAFE: Use context flag 钩子：{ 更改后：[ async ({ doc, req, context }) => { if (context.skipHooks) return; 等待 req.payload.update({ 集合：“帖子”， id: 文档 ID, data: { views: doc.views + 1 }, 上下文：{skipHooks：true}，要求， }); }, ]; } 请参阅 [HOOKS.md#context]()。 ## 项目结构源代码/ ├── 应用程序/ │ ├── (frontend)/ │ │ └── page.tsx │ └──（有效负载）/ │ └── admin/[[...段]]/page.tsx ├── 收藏/ │ ├── 帖子.ts │ ├── 媒体.ts │ └── 用户.ts ├── 全局变量/ │ └── Header.ts ├── 组件/ │ └── 自定义字段.tsx ├── 挂钩/ │ └── slugify.ts └── payload.config.ts ## 类型生成 // 负载.config.ts export default buildConfig({ 打字稿：{ 输出文件：path.resolve(dirname, "payload-types.ts"), }, // ... }); // 用法从“@/payload-types”导入类型{Post，User}； ## 参考文档 * **[FIELDS.md]()** \- 所有字段类型、验证、管理选项 * **[FIELD-TYPE-GUARDS.md]()** \- 用于运行时字段类型检查和缩小的类型保护 * **[COLLECTIONS.md]()** \- 集合配置、身份验证、上传、草稿、实时预览 * **[HOOKS.md]()** \- 集合钩子、字段钩子、上下文模式 * **[ACCESS-CONTROL.md]()** \- 集合、字段、全局访问控制、RBAC、多租户 * **[ACCESS-CONTROL-ADVANCED.md]()** \- 上下文感知、基于时间、基于订阅的访问、工厂函数、模板 * **[QUERIES.md]()** \- 查询运算符、Local/REST/GraphQL API * **[ENDPOINTS.md]()** \- 自定义 API 端点：身份验证、帮助程序、请求/响应模式 * **[ADAPTERS.md]()** \- 数据库、存储、电子邮件适配器、交易 * **[ADVANCED.md]()** \- 身份验证、作业、端点、组件、插件、本地化 * **[PLUGIN-DEVELOPMENT.md]()** \- 插件架构、monorepo 结构、模式、最佳实践 ## 资源 * llms-full.txt： * Docs: * GitHub： * 示例： * 模板：

有效负载

包含技能