Back to Details

payloadcms

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

payloadcms — Payload CMS operator

payloadcms — Payload CMS 操作指南

Keyword: 
payload
, 
payloadcms
, 
headless cms
, 
payload config
关键词：
payload
, 
payloadcms
, 
headless cms
, 
payload config

When to use this skill

何时使用此技能

  • Set up a new Payload project (or add Payload into an existing Next.js app)
  • Define or evolve collections, globals, access control, and field schemas
  • Run/dev/test Payload locally and verify admin/API behavior
  • Plan safe content-model migrations and rollback strategy
  • Prepare production-ready Payload changes with explicit validation checks
  • 搭建新的Payload项目（或在现有Next.js应用中集成Payload）
  • 定义或优化集合、全局项、访问控制及字段schema
  • 本地运行/开发/测试Payload并验证管理面板/API行为
  • 规划安全的内容模型迁移与回滚策略
  • 准备经过明确验证检查的生产就绪Payload变更

When not to use this skill

何时不使用此技能

  • Generic API contract work with no Payload runtime context → use 
    api-design
  • Auth architecture decisions outside Payload-specific setup → use 
    authentication-setup
  • Pure DB physical schema tuning without Payload model constraints → use 
    database-schema-design
  • Broad deployment orchestration not specific to Payload runtime → use 
    deployment-automation
  • 无Payload运行时上下文的通用API契约工作 → 使用
    api-design
  • Payload特定设置之外的认证架构决策 → 使用
    authentication-setup
  • 脱离Payload模型约束的纯数据库物理schema调优 → 使用
    database-schema-design
  • 非Payload运行时专属的广泛部署编排 → 使用
    deployment-automation

Instructions

操作步骤

Step 1) Identify the operating mode

步骤1）确定操作模式

Pick one primary mode before editing anything:
ModeUse whenCore output
BootstrapNew install or first-time integrationworking local Payload app
ModelingCollection/global schema updatesreviewed model diff + migration notes
Runtime debugAdmin/API failing or misconfiguredroot-cause + verified fix
Release prepProduction rollout requestrisk/rollback + verification checklist
在进行任何编辑前选择一种主要模式：
模式适用场景核心产出
引导全新安装或首次集成可运行的本地Payload应用
建模集合/全局schema更新审核后的模型差异 + 迁移说明
运行时调试管理面板/API故障或配置错误根因分析 + 已验证的修复方案
发布准备生产环境上线请求风险/回滚方案 + 验证清单

Step 2) Preflight checks

步骤2）预检查

  1. Verify runtime/toolchain in repo (
    node
    , package manager, framework layout)
  2. Locate Payload config (
    payload.config.*
    ) and model files
  3. Confirm environment/secrets shape (
    DATABASE_URI
    , storage/auth keys)
  4. Inspect existing migration history before schema edits
  1. 验证仓库中的运行环境/工具链（
    node
    、包管理器、框架结构）
  2. 定位Payload配置文件（
    payload.config.*
    ）和模型文件
  3. 确认环境变量/密钥格式（
    DATABASE_URI
    、存储/认证密钥）
  4. 在编辑schema前检查现有迁移历史

Step 3) Execute smallest valid workflow

步骤3）执行最小有效工作流

A. Bootstrap

A. 引导

  • Install dependencies according to repo package manager
  • Generate/init Payload configuration with minimal required collections
  • Run local dev and verify both:
    • Admin UI loads
    • API responds for at least one collection
  • 根据仓库包管理器安装依赖
  • 生成/初始化包含最小必要集合的Payload配置
  • 运行本地开发服务并验证以下两项：
    • 管理UI正常加载
    • 至少一个集合的API可正常响应

B. Modeling

B. 建模

  • Edit one bounded model change at a time (field add/remove/type changes)
  • Document blast radius: affected collections, API output, admin forms, seed/import jobs
  • Prepare migration path and rollback path before merge
  • 每次仅编辑一个边界明确的模型变更（字段添加/删除/类型修改）
  • 记录影响范围：受影响的集合、API输出、管理表单、种子/导入任务
  • 在合并前准备迁移路径与回滚路径

C. Runtime debug

C. 运行时调试

  • Reproduce in local or staging with concrete failing endpoint/page
  • Check config, env bindings, access rules, and adapter wiring
  • Verify fix with explicit before/after proof (endpoint + admin behavior)
  • 在本地或 staging 环境复现具体的故障端点/页面
  • 检查配置、环境绑定、访问规则及适配器连接
  • 通过明确的前后对比验证修复效果（端点 + 管理面板行为）

D. Release prep

D. 发布准备

  • Confirm migration order and downtime assumptions
  • Add rollback notes (revert migration, restore backup, disable feature flags if used)
  • Ensure verification list is executable in CI or staging smoke tests
  • 确认迁移顺序与停机假设
  • 添加回滚说明（回滚迁移、恢复备份、若使用功能则禁用功能标志）
  • 确保验证清单可在CI或staging冒烟测试中执行

Step 4) Validation checklist

步骤4）验证清单

  • Payload server starts without schema/runtime errors
  • At least one modified collection/global is verified through API and admin
  • Migration steps are deterministic and reversible
  • Risk + rollback notes are present for production-bound changes
  • Payload服务器启动无schema/运行时错误
  • 至少一个修改后的集合/全局项通过API和管理面板验证
  • 迁移步骤可确定且可逆
  • 面向生产环境的变更需包含风险 + 回滚说明

Examples

示例

Example 1: Add a new collection safely

示例1：安全添加新集合

text
Prompt: "Add a blog-post collection to our Payload app and keep migration risk low"

Mode:
- Modeling

Expected flow:
- Locate payload config and collection directory
- Add collection schema with access defaults
- Run local checks (admin + API)
- Document migration/rollback in PR notes
text
Prompt: "为我们的Payload应用添加blog-post集合并降低迁移风险"

模式:
- 建模

预期流程:
- 定位payload配置文件和集合目录
- 添加带有默认访问规则的集合schema
- 运行本地检查（管理面板 + API）
- 在PR说明中记录迁移/回滚方案

Example 2: Debug broken admin panel route

示例2：调试故障管理面板路由

text
Prompt: "Payload admin page fails after yesterday's schema change"

Mode:
- Runtime debug

Expected flow:
- Reproduce failure
- Isolate misconfigured field/access/env issue
- Apply minimal fix
- Verify admin loads and affected API endpoint works
text
Prompt: "昨天的schema变更后Payload管理页面无法访问"

模式:
- 运行时调试

预期流程:
- 复现故障
- 隔离配置错误的字段/访问规则/环境问题
- 应用最小化修复
- 验证管理面板加载正常且受影响的API端点可正常工作

Best practices

最佳实践

  1. Keep model changes small and auditable per PR
  2. Never merge schema changes without migration + rollback notes
  3. Validate both admin UI and API surface for touched models
  4. Prefer explicit access rules over implicit defaults
  5. Treat environment binding and adapter configuration as first-class checks
  1. 每次PR中的模型变更保持小而可审计
  2. 绝不要在没有迁移 + 回滚说明的情况下合并schema变更
  3. 验证所有涉及模型的管理UI和API接口
  4. 优先使用明确的访问规则而非隐式默认值
  5. 将环境绑定和适配器配置作为首要检查项

References

参考资料