Payload 开源仓库贡献指南解读：从 Issue 提交流程、Monorepo 开发环境到测试套件与 AI 辅助工作流

Payload 开源仓库贡献指南解读从 Issue 提交流程、Monorepo 开发环境到测试套件与 AI 辅助工作流【免费下载链接】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本篇指南以仓库根目录下的 CONTRIBUTING.md 为骨架系统拆解 Payload 核心仓库的贡献规范与本地开发全流程涵盖问题提交与安全漏洞上报、基于 pnpm 的 Monorepo 安装要求、按功能目录组织的test/集成/端到端测试套件、Docker 数据库编排、视觉回归测试、AI 编码工具Claude Code / Cursor / Copilot的上下文配置以及遵守 Conventional Commits 的 Pull Request 规范。读完你既能快速搭建出与官方一致的贡献者开发环境也能看懂仓库中test/、.claude/、.devcontainer/等目录的职责划分与真实用法。一、总览一份面向核心贡献者的“仓库作战手册”CONTRIBUTING.md 面向的是直接修改 Payload 核心代码库的开发人员而非只使用 Payload 的普通用户因此它的内容与普通开源项目的 README 有本质区别它假设你已进入 Monorepo并需要知道你会在哪个目录写测试、用哪条命令启动被测实例、怎样把数据库拉起来、以及合并代码时遵循什么样的提交规范。从仓库结构可以印证这套约定的实际落地方式test/ 下每个子目录对应一个功能主题fields、access-control、uploads、joins等并各自携带独立的 Payload 配置与测试文件根目录的 package.json 中把dev、docker:start、test:int、test:e2e、test:visual等命令全部编排为 pnpm scripts.env.example 定义了PAYLOAD_DATABASE与可选的数据库 URL 变量test/docker-compose.yml 用 Compose profiles 统一拉起 PostgreSQL、MongoDB、存储模拟器与 Redis。二、提交 Issue先检索、后上报安全漏洞走专用通道文档要求在任何新 Issue 前先检索全部 open and closed issues 确认问题是否已知或已解决若已存在则可通过表情投票reaction表达关注若确需新建则尽量完整填写 Issue Template。安全类问题潜在攻击向量、依赖漏洞禁止创建公开 Issue必须直接发送邮件至devpayloadcms.com。仓库也提供了 SECURITY.md 承载同样的安全上报入口。若核心仓库漏洞被确认具有可修复性与较高严重性官方会按贡献者的发现提供奖励。三、贡献形态与前置沟通文档、新功能与 UI/UX 设计CONTRIBUTING.md 区分了三类贡献并给出不同门槛文档贡献Documentation editsPayload 文档直接放在仓库代码库内即 docs/ 目录按access-control、admin、fields、plugins等主题组织任何改进均可直接通过 PR 提交官方会周期性地把这些文件同步部署到官网。新功能Building additional features建议先到 GitHub Discussion 发 feature request或到 Discord 讨论。原因很实际——新功能往往横跨整个仓库核心 packages/payload 与db-*、richtext-*、plugin-*等先讨论清楚架构再动手写 PR 能避免大范围返工。设计贡献Design Contributions任何影响 UI/UX 或设计系统一致性的改动都要求先提交设计提案供官方 review 与批准以防止与既有/规划中的组件风格冲突也避免实现后被迫大幅返工。这一“先对齐、再实现”的节奏与 CLAUDE.md 中对编码规范如packages/ui组件目录须为ComponentName/index.tsx index.css结构、CSS 只允许400/768/1024/1440px四个断点等的高要求是一致的。四、本地开发环境pnpm 是硬性要求按 .tool-versions 固定版本4.1 安装依赖Payload 是包含核心平台、各类插件与独立 package 的Monorepo安装必须使用pnpmYarn/npm 不可用npm add -g pnpm # 大多数系统上最简单的方式 pnpm install # 在仓库根目录执行一次如果是从极旧版本切过来的环境官方推荐执行pnpm reinstall做一次干净安装清空node_modules并重装全部依赖。根目录 package.json 中将reinstall定义为pnpm clean:all pnpm install正好对应“nuke 后重装”的语义。4.2 版本要求仓库通过版本固定文件约束运行时.tool-versions 声明pnpm 11.9.0与nodejs 24.15.0.node-version 与 .nvmrc 同步锁定 Node v24.15.0package.json 中packageManager字段同样写为pnpm11.9.0Payload 团队用 mise 管理 Node.js 版本可用node --version自查当前版本。五、AI 编码工具兼容层CLAUDE.md、Skills、Hooks 与 MCP这是 CONTRIBUTING.md 中非常有仓库特色的一节。Payload 仓库把“AI 辅助开发”当成一等配置来处理避免 AI 生成的代码偏离仓库约定。官方给出的支持矩阵如下工具ContextSkillsHooksMCPClaude Code✅✅✅✅Cursor✅✅✅✅VS Code Copilot⚠️✅❌✅为什么不用 AGENTS.md文档解释Cursor 会同时加载CLAUDE.md与AGENTS.md导致上下文重复。因此仓库里 AGENTS.md 只有一行“Please read./CLAUDE.mdfor context.”全部细则收拢进 CLAUDE.md。各能力的落点如下Context项目目的、架构与编码规范位于 CLAUDE.md。没有它AI 不知道代码库约定可能生成与现有规范不符的代码。Skills针对特定任务的指导例如如何生成翻译位于.claude/skills/name/SKILL.md。仓库中实际存在audit-dependencies、generate-translations、ui4、triage-ci-flake、e2e-write-visual-test等多个 skill 目录。没有它每次对话都得人工复述一遍测试模式等工作流。Hooks文件写入时自动格式化代码位于 .claude/hooks/实际文件为post-write-format.sh。没有它AI 编辑后文件会出现 eslint 报错——虽然 lint-staged 会在提交时兜底修复但你在长修改中途未必想提交。MCPModel Context Protocol扩展 AI 能力的外部工具服务器配置文件按工具拆分——.cursor/mcp.jsonCursor、.mcp.jsonClaude Code、.vscode/mcp.jsonVS Code。三份文件内容一致地声明了两个 MCPPlaywright MCP交互式浏览器自动化导航、点击、填表、截图与 Payload 自身的 HTTP MCPhttp://localhost:3000/api/mcp?overrideAccesstrue。仓库中还进一步固化了 Playwright MCP 的启动参数与含义Flag用途--capsvision,verify,tracing,devtools启用 vision截图、verification、tracing 与 devtools 能力--isolated使用隔离浏览器 profile 而非系统 Chrome规避企业策略对 DevTools 远程调试的封锁--headless无头运行、无可见 UI自动化更快实际配置完整形态以 .mcp.json 为例为{ mcpServers: { playwright: { command: pnpm, env: {}, args: [dlx, playwright/mcplatest, --capsvision,verify,tracing,devtools, --isolated, --headless, --browser, chromium] }, payload: { type: http, url: http://localhost:3000/api/mcp?overrideAccesstrue } } }前置条件使用前必须已运行pnpm devAI 将导航到localhost:3000与应用交互。没有 MCPAI 只能写测试代码而无法直接浏览、验证真实 UI。六、写代码前必读test/ 目录结构与功能驱动测试CONTRIBUTING.md 明确指出新功能要“把测试放在心上”test/下的每个顶层目录负责测试一类特定功能fields、collections等若现有目录合适优先往已有测试目录里加而不是另起炉灶。6.1 典型测试目录布局一个典型目录结构如下. ├── config.ts ├── int.spec.ts ├── e2e.spec.ts └── payload-types.ts各文件职责在仓库中有多处实例如 test/fields 与 test/_communityconfig.ts——粒度尽量细的测试用 Payload 配置越轻量越好。例如test/fields/config.ts只注册该主题需要的集合与字段。int.spec.ts—— 由 Vitest 运行的集成测试文件任何测试文件都必须以*int.spec.ts结尾Vitest 据此识别集成测试工程。test/fields/int.spec.ts、test/_community/int.spec.ts均为实例。e2e.spec.ts—— 端到端测试文件用上面的 config 启动 Admin UI 后跑 Playwright通常只在 Admin UI 有较大改动时才需要。test/access-control/e2e.spec.ts、test/uploads/e2e.spec.ts、test/joins/e2e.spec.ts等都是实例。payload-types.ts—— 从config.ts生成的类型文件生成命令见下。这种拆分刻意降低写测试的摩擦既能让某个测试目录独立启动 Payload也方便 CI 只跑相关套件。6.2 启动被测实例与生成类型pnpm dev my-test-dir # 用指定测试目录的 config 启动 Payload pnpm dev fields # 例启动 test/fields 套件 pnpm dev:generate-types my-test-dir # 生成该目录的 payload-types.tspnpm dev my-test-dir会以该 config 启动 Payload并且每次重启都会刷新测试数据库。从根目录 package.json 看其底层是tsx ./test/dev.ts带--no-deprecation --max-old-space-size16384的 Node 选项也就是说 dev 入口本身是一个测试编排脚本test/dev.ts。若用 VS Code常见的 run config 会自动注入编辑器见 .vscode/launch.json。6.3 自动登录与默认凭据默认情况下 Payload 会用默认凭据自动登录关闭方式pnpm dev my-test-dir --no-auto-login或设置环境变量PAYLOAD_PUBLIC_DISABLE_AUTO_LOGINfalse默认凭据邮箱devpayloadcms.com、密码test。对应到代码侧test/_community等套件正是围绕这套凭据做 Admin UI 的自动登录与鉴权测试的。七、数据库准备PAYLOAD_DATABASE、Docker Compose 与连接串7.1 选择适配器先把 .env.example 复制为.env再设置PAYLOAD_DATABASE选择数据库适配器。CONTRIBUTING.md 列出的可用值涵盖四大类MongoDB 系mongodbMongoDB Community vector search/mongot、mongodb-atlasAtlas Local 一体容器、cosmosdb、documentdb、firestore均为“兼容选项下跑 MongoDB”PostgreSQL 系postgres含 pgvector 与 PostGIS、postgres-custom-schema、postgres-uuid、postgres-uuidv7、postgres-read-replica、supabaseSQLite 系sqlite、sqlite-uuid、sqlite-uuidv7、d1Cloudflare D1。7.2 Docker 编排命令pnpm docker:start # 清空并启动全部服务PostgreSQL、MongoDB、存储模拟器数据全新 pnpm docker:clean # 停止并移除全部服务 pnpm docker:test # 测试数据库连接docker:start每次都会删除旧数据、全新启动保证环境干净。所有服务定义在单个 test/docker-compose.yml 中通过 Docker Compose profilespostgres、mongodb、mongodb-atlas、storage、redis、all切换。查看该文件可发现它远不止三个数据库除了主 Postgres含 PostGISpgvector 镜像、读写副本 postgres-replica、MongoDB 副本集含 mongot 全文/向量搜索、MongoDB Atlas Local 外还编排了 LocalStackS3、AzuriteAzure Storage、fake-gcs-server、vercel-blob-emulator 与 Redis分别对应packages/storage-*与packages/kv-redis适配器的测试需求。macOS 用户可用brew install --cask docker安装 Docker Desktop。7.3 官方连接串数据库URLPostgreSQLpostgres://payload:payload127.0.0.1:5433/payloadMongoDBmongodb://payload:payloadlocalhost:27018/payload?authSourceadmindirectConnectiontruereplicaSetrs0MongoDB Atlas Localmongodb://localhost:27019/payload?directConnectiontruereplicaSetmongodb-atlas-local无鉴权SQLite 无需 Docker——它直接以项目内文件形式存储。7.4 使用自己的数据库若不想用 Docker 数据库而想用自己的 MongoDB/PostgreSQL供test/目录使用在.env中配置MONGODB_URLmongodb://127.0.0.1/payloadtests # 指向本地安装的 MongoDB POSTGRES_URLpostgres://127.0.0.1:5432/payloadtests # 指向本地安装的 PostgreSQL八、在 Devcontainer 中开发整个开发环境也可以在 devcontainer 内运行。前提是 Docker 或 OrbStackmacOS 上性能更佳加 VS Code 的 Dev Containers 扩展或devcontainers/cli二者其一。启动方式二选一VS Code打开仓库按提示点 “Reopen in Container”或命令面板执行Dev Containers: Reopen in ContainerCLI仓库根目录执行devcontainer up再devcontainer exec zsh进入 shell之后可用 JetBrains “Dev Containers”插件或 Cursor/VS Code 的 “Attach to Running Container” 把编辑器挂进容器。容器内继续不用 sqlite 就运行pnpm docker:start运行pnpm dev 测试套件名devcontainer 内默认PAYLOAD_DATABASEsqlite所以只有切到 mongodb/postgres 时才需要第 1 步。仓库的 .devcontainer/devcontainer.json 实现了这套方案基于 Ubuntu 镜像挂载独立node_modules卷隔离宿主 mac 二进制与容器 linux 二进制onCreateCommand与 .devcontainer/setup.sh 自动处理卷克隆/绑定挂载两种模式的属主问题并仅在.env缺失时从.devcontainer/.env.example播种最后只转发 3000 端口给 Next.js dev server。九、测试执行矩阵int / e2e / 多数据库9.1 跑什么pnpm test # 全量int components e2e pnpm test:e2e # 只跑 Playwright 端到端 pnpm test:int # 只跑集成测试默认仅 MongoDB pnpm test:int:postgres # 集成测试跑在 PostgreSQL需本机装好 postgres在 package.json 中test:int的底层是vitest --project int带DISABLE_LOGGING另有test:int:postgres、test:int:sqlite、test:unit、test:typeststyche与test:e2etest/runE2E.ts等变体可供不同场景选用。9.2 关于现代集成测试的补充约定值得一提的是虽然 CONTRIBUTING.md 仍以int.spec.ts命名约定为主线但仓库演进后对集成测试提出了更严格的封装要求可在 CLAUDE.md 中找到集成测试必须从test/__helpers/int/vitest.ts导入test而非直接来自 Vitest用test.suite({ config: ./config.ts })包裹被测套件并从参数读取payload/restClient/sdk/cli——fixture 会负责“每个文件初始化一次 Payload、每个测试前重置并播种数据、结束后销毁”开发者无需手工写数据库重置逻辑。对照阅读两条规范能避免你按旧模式提交的 PR 在 review 阶段被打回。十、视觉回归测试visual 标签、基线图片与“只能用 Docker 生成基线”部分 e2e 测试除了断言 DOM还会把 UI 截图与已提交的基线图片对比。这类测试是可选的opt-in只有打上visual标签的测试才走此流程且与普通 e2e 测试同住一个e2e.spec.ts文件不设独立目录。使用visual()辅助函数代替test()它会自动打上visual标签无需记忆例如 CONTRIBUTING.md 中给出的写法import { expectScreenshot } from ../__helpers/e2e/expectScreenshot.js import { visual } from ../__helpers/e2e/visual.js visual(renders the posts list view, async () { await page.goto(url.list) await expectScreenshot({ page, name: posts-list-view.png }) })上述两个辅助函数确实位于 test/__helpers/e2e/expectScreenshot.ts 与 test/__helpers/e2e/visual.ts。相关运行命令pnpm docker:start # 先起 MongoDB若尚未运行 pnpm test:visual # 运行所有含 visual 测试的套件 pnpm test:visual:update # 接受有意的视觉变更并重新生成基线 pnpm test:visual:preview suite # 查看 actual/expected/diff 的交互式对比报告基线的存放位置是 spec 文件旁的__snapshots__/spec-file/name.png。几条重要纪律基线必须且只能在 CI 所用的固定 Playwright Docker 镜像内生成/更新。操作系统间字体渲染差异足以让 macOS/Windows 上“看起来一样”的基线在 CI 上对比失败。禁止提交来自任何其他来源的基线 PNG——手工截图、截图工具、编辑器扩展、AI Agent 截图、浏览器 “保存图片”都不行只有上述命令写出的 PNG 才保证与 CI 渲染一致否则本地全绿、CI 必挂。新增visual()测试尚无基线时直接跑pnpm test:visual即可——Playwright 首次运行会补写缺失基线只有需要“接受既有基线的变更”时才用pnpm test:visual:update因为它会把本次运行触碰到的所有基线都重写一遍。在 PR 上CI 只在 diff 可能影响渲染样式、组件、截图、当前visual测试渲染的 fixture 配置时才运行visual测试若visual-regressionjob 失败CI 不会贴注释需要本地用上述命令自行复现、检查 diff。仓库配套的 test/scripts/run-visual-docker.sh 正是这一策略的执行体它自动探测playwright/test版本、把根目录node_modules装进 Docker volume避免宿主 macOS 二进制污染容器并在容器内跑被visual标签圈定的测试。十一、Pull Request 规范描述详尽 Conventional Commits scope11.1 描述与关联 Issue所有 PR 都要极其详尽地说明问题与拟议方案若关联任何 open/closed issue请在 PR 描述中留下 issue 编号。11.2 PR 标题使用 Conventional Commits合并时 PR 内所有 commit 会被squash 为一个且以PR 标题作为提交信息因此 PR 标题必须遵循 Conventional Commits。官方给出的类型示例feat: add new featurefix: fix bugdocs: add documentationtest: add/fix testsrefactor: refactor codechore: anything that does not fit into the above categories在适用时还要用括号标注影响到的包scope。改payloadchore 包无需 scope。示例feat(ui): add new featurefix(richtext-lexical): fix bug若提交涉及 templates 或 examples固定用chore类型 相应 scopechore(templates): adds feature to templatechore(examples): fixes bug in example11.3 允许维护者推送从 fork 开 PR 时请保持“Allow edits and access to secrets by maintainers”处于开启状态GitHub UI 默认开启。这样 Payload 团队可以直接在你的分支上做小修rebase、lint/format 清理、微调PR 无需再跑一个来回。若该权限被关闭且团队需要推送改动推进 PR官方可能直接关闭你的 PR 并在 Payload 仓库内开一个等价分支来迭代。十二、本地预览文档改动想本地预览自己修改过的 docs克隆 website repository运行pnpm install按该 website 仓库 README 中 “Documentation” 一节说明预览 docs。原因在于仓库内的 docs/ 是文档的唯一事实来源官方站点会直接把 docs 内容部署出去因此本仓库的文档改动即官网文档改动。十三、国际化i18n新增 UI 字符串的完整流程如果 PR 往 UI 中新增了字符串需要翻译到 Payload 支持的全部语言找到合适的 i18n 文件通常在packages/translations/src/languages该目录下实际有en.ts、ar.ts、az.ts、bg.ts、bnBd.ts、bnIn.ts等大量语言文件部分包如 richtext-lexical为每个 feature 单独维护 i18n 文件。先把字符串加到英文 localeen。再翻译到其他语言若.env中有OPENAI_KEY可用translateNewKeys脚本自动翻译——核心翻译执行cd packages/translations pnpm translateNewKeyslexical 翻译执行cd packages/richtext-lexical pnpm translateNewKeys。当然也可以用 ChatGPT 或 Google 翻译。外部贡献者可跳过此步留给官方处理。根目录脚本别名见 package.json 的translateNewKeys。UI 中渲染这些字符串必须通过useTranslationhook 的t工具const { t } useTranslation() // ... t(yourStringKey)这与仓库国际化实现完全对齐翻译文案以 key 形式集中存放组件内不硬编码多语言文案。十四、把整份指南串成一条可执行的开发路径结合以上所有环节从零开始向 Payload 核心仓库提交一个高质量 PR 的完整路径是先聊后写新功能先去 Discussion/Discord 对齐设计改动先提交设计提案安全漏洞走邮件而非 Issue。搭环境用 pnpm版本对齐 .tool-versions执行pnpm install将 .env.example 复制为.env并设PAYLOAD_DATABASE需要非 SQLite 库时先pnpm docker:start也可直接用 devcontainer.devcontainer/devcontainer.json一键拉起完整环境。找对测试目录把新功能落入 test/ 下对应功能目录补齐config.tsint.spec.ts必要时e2e.spec.ts并用pnpm dev:generate-types dir生成payload-types.ts。本地验证pnpm dev dir手动调试默认凭据自动登录pnpm test:int跑集成测试涉及 Admin UI 的用 Playwright e2e涉及样式/组件渲染的补一个visual()测试并在 Docker 镜像内生成基线。提 PR描述详尽、标注关联 issue、标题符合 Conventional Commits 并正确带 scopetemplates/examples走chore保持 “Allow edits from maintainers” 开启。这条路径上的每一步都能在仓库中找到对应的真实配置文件或可执行脚本而非停留在文档层面——这正是 CONTRIBUTING.md 与仓库自描述性的真正价值所在。【免费下载链接】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），仅供参考