尧图网页设计 
Payload 起步模板实战with-vercel-mongodb 的云端部署与本地开发全指南【免费下载链接】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本指南围绕开源仓库中的 with-vercel-mongodb 起步模板完整讲解如何把一套“最小可用”的 Payload 全栈应用一键部署到 Vercel数据库使用 MongoDB Atlas、文件存储使用 Vercel Blob并在此基础上进行本地开发与 Docker 化运行。读完本文你将掌握该模板的目录结构、环境变量体系、核心配置MongoDB 适配器与 Vercel Blob 存储插件、两个内置集合Users 与 Media的含义以及从克隆、配环境变量到pnpm dev跑起来的完整链路。模板是什么with-vercel-mongodb位于仓库 templates/with-vercel-mongodb是 Payload 官方提供的若干模板之一。正如其package.json中声明的定位它是一个 “A blank template to get started with Payload”——以最少配置、最低依赖的方式让你快速开启任意项目同时预置了面向 Vercel 生态的数据库MongoDB与对象存储Vercel Blob接线。它依赖 Payload 3.x当前仓库内锁定的版本为payload3.82.1、next16.3.3、react19.2.6包管理器为pnpmpackageManager: pnpm10.33.0运行环境要求node 24.15.0。模板的核心要点开箱即含一套完整的 Payload Next.js 目录骨架src/app、src/collections、src/payload.config.ts等默认使用 MongoDB 作为主数据库通过payloadcms/db-mongodb的mongooseAdapter接入默认把上传文件存储到 Vercel Blob通过payloadcms/storage-vercel-blob实现提供Dockerfile与docker-compose.yml本地可用容器跑 MongoDB 与整个应用附带基于 Playwright 与 Vitest 的端到端/集成测试骨架见tests/目录。一键部署到 VercelDeploy to Vercel模板 README 提供的标准上云路径是点击其顶部的 “Deploy” 按钮对应 README 中附带的 Vercel 部署入口。流程如下点击部署按钮Vercel 会先提示你把该模板保存到自己的 GitHub 仓库这样你即拥有代码的完整所有权可任意修改在弹出的界面中关联以下由 Vercel 集成的服务点击 “Add” 并 “Connect”Mongo Atlas——基于 MongoDB 的云数据库用于存放业务数据Vercel Blob Storage——对象存储用于存放图片、视频等媒体文件两个服务连接成功后Vercel 会自动为项目注入对应的连接变量无需手工填写数据库地址构建命令使用模板预置的pnpm run ci构建流程见 package.json 的scripts应用构建并部署完成后访问生成的站点 URL即可在/admin路径打开管理后台。需要配置的 Secret在 Vercel 项目配置阶段你还会被提示填写一个 secret变量用途PAYLOAD_SECRETPayload 用它为 JWT 等令牌签名README 强调这应是一个足够长、不可猜测的强口令也可以借助密码管理器生成该变量的实际消费点在 src/payload.config.ts——secret: process.env.PAYLOAD_SECRET || 直接被传入buildConfig。部署完成后README 指引从应用 URL 进入/admin管理面板创建管理员账号随后按 dashboard 中的提示完成初始内容写入即可开始使用。本地开发快速开始Quick Start - local setup如果你已经把模板克隆git clone到本地需要走如下步骤跑起开发服务器。1. 克隆与复制环境变量进入项目目录后把环境变量样例复制为实际使用的.envcd my-project cp .env.example .env.env.example 中定义了两个必填项MONGODB_URLmongodb://127.0.0.1/your-database-name PAYLOAD_SECRETYOUR_SECRET_HERE如果你希望本地环境与线上使用同一套 Vercel 资源需要把 Vercel 项目自动生成的环境变量填入.envMONGODB_URL——指向你在 Vercel 上连接好的 Mongo Atlas 数据库BLOB_READ_WRITE_TOKEN——Vercel Blob 的读写令牌用于让本地请求能够读写云端对象存储。2. 安装依赖并启动开发服务器pnpm install pnpm dev然后打开http://localhost:3000即可在浏览器中看到应用首页。模板首页src/app/(frontend)/page.tsx/page.tsx)会通过getPayload({ config })与payload.auth({ headers })检查当前登录态未登录显示 “Welcome to your new project.”已登录则显示 “Welcome back, {user.email}”并提供进入管理后台的链接。后续对./src的任何改动都会热更新到页面。首次启动后按屏幕提示登录并创建你的第一个管理员用户。待准备打包与正式运行时再参考下文“生产构建”与“部署”部分。3. 生产构建与类型生成模板在 package.json 中预置了常用脚本build: payload build, dev: next dev, devsafe: rm -rf .next next dev, generate:importmap: payload generate:importmap, generate:types: payload generate:types, start: next start,注意两点其一这里next dev、next start运行的是模板的 Next.js 应用外壳但被payloadcms/next/withPayload包装过见 next.config.ts从而路由、管理后台、GraphQL 等 Payload 能力全部挂载在 Next 应用内其二generate:types会把集合结构生成为 TS 类型文件——模板中该输出路径配置在typescript.outputFile见下方配置解读。Docker 本地开发可选模板同时提供了两种 Docker 使用方式适用于不想在本机单独安装 MongoDB、又想保证团队环境一致的场景。方式一仅用 docker-compose 起数据库如果你希望使用 Docker 运行本地 MongoDB而应用本身照常以pnpm dev启动修改.env中MONGODB_URL为mongodb://127.0.0.1/dbname修改 docker-compose.yml 中对应的MONGODB_URL使二者一致README 提示该值需与上一步的dbname匹配运行docker-compose up启动数据库可加-d让其在后台运行。关于名字模板注释指出若改用 Docker 内的 Mongo 服务连接串的主机名应使用mongo如mongodb://mongo/my-db-name因为docker-compose.yml中服务名为mongo、并对外映射27017:27017。方式二整栈容器化更彻底的做法是把应用与数据库都放进容器先完成上文 “1. 克隆与复制环境变量” 步骤docker-compose.yml 会自动加载项目根目录的.env执行docker-compose up回到上文 “2. 安装依赖并启动” 的登录流程创建你的第一个管理员用户。模板的 Compose 编排如下要点摘录payload服务基于 Node 镜像将项目目录挂载进容器映射3000:3000启动命令依次执行corepack enable、准备最新版 pnpm、pnpm install pnpm dev并depends_onmongomongo服务使用mongo:latest显式指定--storageEnginewiredTiger数据落到命名卷data文件末尾还保留了被注释掉的postgres服务示例供想切换数据库方案的开发者参考。工作原理Payload 配置逐段拆解模板之所以能“开箱即跑”核心在 src/payload.config.ts整份配置只有约 37 行却是理解整个模板的钥匙import { mongooseAdapter } from payloadcms/db-mongodb import { lexicalEditor } from payloadcms/richtext-lexical import path from path import { buildConfig } from payload import { fileURLToPath } from url import { Users } from ./collections/Users import { Media } from ./collections/Media import { vercelBlobStorage } from payloadcms/storage-vercel-blob const filename fileURLToPath(import.meta.url) const dirname path.dirname(filename) export default buildConfig({ admin: { user: Users.slug, importMap: { baseDir: path.resolve(dirname), }, }, collections: [Users, Media], editor: lexicalEditor(), secret: process.env.PAYLOAD_SECRET || , typescript: { outputFile: path.resolve(dirname, payload-types.ts), }, db: mongooseAdapter({ url: process.env.MONGODB_URL || , }), storage: [ vercelBlobStorage({ collections: { media: true, }, token: process.env.BLOB_READ_WRITE_TOKEN || , }), ], })逐项说明admin.user指定用于登录管理后台的集合这里指向Users.slugadmin.importMap.baseDir用于解析管理端组件映射对应src/app/(payload)/admin/importMap.js。collections注册Users与Media两个集合详情见下文。editor选择富文本编辑器为lexicalEditor()来自payloadcms/richtext-lexical。secret读取PAYLOAD_SECRET环境变量。typescript.outputFile把自动生成的类型写到同目录payload-types.ts即模板根下的 src/payload-types.ts可配合pnpm generate:types使用。db使用mongooseAdapter({ url })从MONGODB_URL读取连接串。若该变量为空Payload 在启动时将无法连库因此部署/开发前必须正确配置。storage注册vercelBlobStorage插件并把media集合指向 Vercel Blobtoken 取自BLOB_READ_WRITE_TOKEN。在对应包 packages/storage-vercel-blob/src/index.ts 的源码注释中可以看到其行为约定该插件基于payloadcms/plugin-cloud-storage实现当token未设置时插件会自动禁用并回退到本地存储当前只支持access: public的访问级别Vercel 后续才计划支持私有 blob可通过cacheControlMaxAge控制缓存时长默认一年、通过addRandomSuffix决定是否在上传文件名后加随机后缀等。也就是说模板的数据与文件分别走两条线结构化数据 → MongoDBAtlas 或本地容器上传的图片/视频等文件 → Vercel Blob。管理后台与前端则在同一个 Next.js 应用里共享配置。内置集合Users 与 Media模板刻意保持“最小”只注册了两个集合。Users认证集合src/collections/Users.tsexport const Users: CollectionConfig { slug: users, admin: { useAsTitle: email, }, auth: true, fields: [ // Email added by default // Add more fields as needed ], versions: false, }auth: true表示该集合启用认证Payload 会自动加上 email 字段、密码哈希与登录逻辑只有这里的用户能访问/admin管理面板admin.useAsTitle: email让后台列表中用 email 作为文档标题展示字段默认留空等待你按业务扩展如姓名、角色等关于认证集合的深入用法可参考仓库内 examples/auth 示例以及 docs/authentication/overview.mdx 认证文档。Media上传集合src/collections/Media.tsexport const Media: CollectionConfig { slug: media, access: { read: () true, }, fields: [ { name: alt, type: text, required: true, }, ], upload: true, }upload: true让该集合成为上传集合同时被上面storage中的vercelBlobStorage命中因此文件会落到 Vercel Blob自定义了一个必填的alt文本字段用于图片可访问性描述access.read: () true表示媒体文件公开可读——这是模板刻意为之的默认值方便前端直接展示注意该模板中的 Media 未像更完整的示例那样预置多尺寸缩略图如需尺寸生成、焦点控制focal point等能力可参考更完整的示例模板例如 templates/ecommerce与 docs/upload/overview.mdx 上传文档。集合结构的管理与扩展方式可继续阅读 docs/configuration/collections.mdx 集合配置文档。目录骨架Next.js 与 Payload 的路由是如何组织的模板在src/app下做了清晰的目录划分src/app/ ├── (frontend)/ # 公开站点页面你自己的业务 UI │ ├── layout.tsx │ ├── page.tsx # 首页根据登录态显示欢迎语 │ └── styles.css ├── (payload)/ # Payload 自带的管理面自动生成、勿手改 │ ├── admin/[[...segments]]/ # /admin 路由 │ ├── admin/importMap.js # 管理端组件导入映射 │ ├── api/[...slug]/route.ts # /api/... REST 端点 │ ├── api/graphql/route.ts # /api/graphql │ ├── api/graphql-playground/ # GraphQL Playground │ ├── custom.css │ └── layout.tsx # Payload RootLayout 装配 └── my-route/route.ts # 你可以按需添加的任意自定义路由其中(payload)组里的入口文件都带 “generated automatically by payload” 注释例如 src/app/(payload)/layout.tsx/layout.tsx) 从payloadcms/next/layouts引入RootLayout、generatePayloadViewport与handleServerFunctions并装配importMap——这些是 Payload 管理后台在 Next.js App Router 下的标准接线正常情况下不需要改动。(frontend)才是你写业务页面的地方二者共享同一个 Payload 配置实例。测试骨架验证你的模板改动模板虽然“最小”但仍携带了一套可运行的测试基建templates/with-vercel-mongodb/testse2e/基于 Playwright 的端到端测试分别覆盖管理后台admin.e2e.spec.ts与前端页面frontend.e2e.spec.ts配套helpers/login.ts、helpers/seedUser.ts完成登录与造数int/基于 Vitest 的集成测试api.int.spec.ts通过pnpm test即可依次执行集成测试与端到端测试运行配置见 playwright.config.ts 与 vitest.config.mts。这为你后续扩展集合、新增接口时提供了一套可参考的回归保障范式。后续路径与常见问题速查扩展集合与字段注册新集合只需在src/collections新增配置文件、写进collections数组字段系统文档见 docs/fields/overview.mdx。认证相关改密码、多因素、策略等见 docs/authentication/overview.mdx完整可运行示例见 examples/auth。富文本默认启用 Lexical 编辑器扩展能力见 docs/rich-text/overview.mdx。REST 与 GraphQL模板已挂载/api/...REST 与 GraphQL/Playground 路由接口约定见 docs/rest-api/overview.mdx 与 docs/graphql/overview.mdx。常见错误自查若本地请求媒体文件返回 404/失败先检查.env是否配置了BLOB_READ_WRITE_TOKEN未配置时按插件源码逻辑会回退到本地存储注意与线上行为一致若管理后台登录异常检查PAYLOAD_SECRET是否为空或前后不一致。模板间的横向对比若你并不需要 Vercel 生态或想换数据库可参考同目录下其他模板例如 templates/with-postgres、templates/blank 与 templates/with-vercel-postgres。综上with-vercel-mongodb是一个“配置面小、可运行面全”的模板它以 Payload 3 MongoDB Vercel Blob 三件套打通了一条从git clone、.env配置、pnpm dev本地开发到 Vercel 一键部署的完整链路。你可以基于它在一小时级的时间内把管理后台与数据库接通然后把全部精力投入到自己的业务集合与前端页面中。【免费下载链接】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），仅供参考 Payload 起步模板实战：with-vercel-mongodb 的云端部署与本地开发全指南
Payload 起步模板实战with-vercel-mongodb 的云端部署与本地开发全指南【免费下载链接】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本指南围绕开源仓库中的 with-vercel-mongodb 起步模板完整讲解如何把一套“最小可用”的 Payload 全栈应用一键部署到 Vercel数据库使用 MongoDB Atlas、文件存储使用 Vercel Blob并在此基础上进行本地开发与 Docker 化运行。读完本文你将掌握该模板的目录结构、环境变量体系、核心配置MongoDB 适配器与 Vercel Blob 存储插件、两个内置集合Users 与 Media的含义以及从克隆、配环境变量到pnpm dev跑起来的完整链路。模板是什么with-vercel-mongodb位于仓库 templates/with-vercel-mongodb是 Payload 官方提供的若干模板之一。正如其package.json中声明的定位它是一个 “A blank template to get started with Payload”——以最少配置、最低依赖的方式让你快速开启任意项目同时预置了面向 Vercel 生态的数据库MongoDB与对象存储Vercel Blob接线。它依赖 Payload 3.x当前仓库内锁定的版本为payload3.82.1、next16.3.3、react19.2.6包管理器为pnpmpackageManager: pnpm10.33.0运行环境要求node 24.15.0。模板的核心要点开箱即含一套完整的 Payload Next.js 目录骨架src/app、src/collections、src/payload.config.ts等默认使用 MongoDB 作为主数据库通过payloadcms/db-mongodb的mongooseAdapter接入默认把上传文件存储到 Vercel Blob通过payloadcms/storage-vercel-blob实现提供Dockerfile与docker-compose.yml本地可用容器跑 MongoDB 与整个应用附带基于 Playwright 与 Vitest 的端到端/集成测试骨架见tests/目录。一键部署到 VercelDeploy to Vercel模板 README 提供的标准上云路径是点击其顶部的 “Deploy” 按钮对应 README 中附带的 Vercel 部署入口。流程如下点击部署按钮Vercel 会先提示你把该模板保存到自己的 GitHub 仓库这样你即拥有代码的完整所有权可任意修改在弹出的界面中关联以下由 Vercel 集成的服务点击 “Add” 并 “Connect”Mongo Atlas——基于 MongoDB 的云数据库用于存放业务数据Vercel Blob Storage——对象存储用于存放图片、视频等媒体文件两个服务连接成功后Vercel 会自动为项目注入对应的连接变量无需手工填写数据库地址构建命令使用模板预置的pnpm run ci构建流程见 package.json 的scripts应用构建并部署完成后访问生成的站点 URL即可在/admin路径打开管理后台。需要配置的 Secret在 Vercel 项目配置阶段你还会被提示填写一个 secret变量用途PAYLOAD_SECRETPayload 用它为 JWT 等令牌签名README 强调这应是一个足够长、不可猜测的强口令也可以借助密码管理器生成该变量的实际消费点在 src/payload.config.ts——secret: process.env.PAYLOAD_SECRET || 直接被传入buildConfig。部署完成后README 指引从应用 URL 进入/admin管理面板创建管理员账号随后按 dashboard 中的提示完成初始内容写入即可开始使用。本地开发快速开始Quick Start - local setup如果你已经把模板克隆git clone到本地需要走如下步骤跑起开发服务器。1. 克隆与复制环境变量进入项目目录后把环境变量样例复制为实际使用的.envcd my-project cp .env.example .env.env.example 中定义了两个必填项MONGODB_URLmongodb://127.0.0.1/your-database-name PAYLOAD_SECRETYOUR_SECRET_HERE如果你希望本地环境与线上使用同一套 Vercel 资源需要把 Vercel 项目自动生成的环境变量填入.envMONGODB_URL——指向你在 Vercel 上连接好的 Mongo Atlas 数据库BLOB_READ_WRITE_TOKEN——Vercel Blob 的读写令牌用于让本地请求能够读写云端对象存储。2. 安装依赖并启动开发服务器pnpm install pnpm dev然后打开http://localhost:3000即可在浏览器中看到应用首页。模板首页src/app/(frontend)/page.tsx/page.tsx)会通过getPayload({ config })与payload.auth({ headers })检查当前登录态未登录显示 “Welcome to your new project.”已登录则显示 “Welcome back, {user.email}”并提供进入管理后台的链接。后续对./src的任何改动都会热更新到页面。首次启动后按屏幕提示登录并创建你的第一个管理员用户。待准备打包与正式运行时再参考下文“生产构建”与“部署”部分。3. 生产构建与类型生成模板在 package.json 中预置了常用脚本build: payload build, dev: next dev, devsafe: rm -rf .next next dev, generate:importmap: payload generate:importmap, generate:types: payload generate:types, start: next start,注意两点其一这里next dev、next start运行的是模板的 Next.js 应用外壳但被payloadcms/next/withPayload包装过见 next.config.ts从而路由、管理后台、GraphQL 等 Payload 能力全部挂载在 Next 应用内其二generate:types会把集合结构生成为 TS 类型文件——模板中该输出路径配置在typescript.outputFile见下方配置解读。Docker 本地开发可选模板同时提供了两种 Docker 使用方式适用于不想在本机单独安装 MongoDB、又想保证团队环境一致的场景。方式一仅用 docker-compose 起数据库如果你希望使用 Docker 运行本地 MongoDB而应用本身照常以pnpm dev启动修改.env中MONGODB_URL为mongodb://127.0.0.1/dbname修改 docker-compose.yml 中对应的MONGODB_URL使二者一致README 提示该值需与上一步的dbname匹配运行docker-compose up启动数据库可加-d让其在后台运行。关于名字模板注释指出若改用 Docker 内的 Mongo 服务连接串的主机名应使用mongo如mongodb://mongo/my-db-name因为docker-compose.yml中服务名为mongo、并对外映射27017:27017。方式二整栈容器化更彻底的做法是把应用与数据库都放进容器先完成上文 “1. 克隆与复制环境变量” 步骤docker-compose.yml 会自动加载项目根目录的.env执行docker-compose up回到上文 “2. 安装依赖并启动” 的登录流程创建你的第一个管理员用户。模板的 Compose 编排如下要点摘录payload服务基于 Node 镜像将项目目录挂载进容器映射3000:3000启动命令依次执行corepack enable、准备最新版 pnpm、pnpm install pnpm dev并depends_onmongomongo服务使用mongo:latest显式指定--storageEnginewiredTiger数据落到命名卷data文件末尾还保留了被注释掉的postgres服务示例供想切换数据库方案的开发者参考。工作原理Payload 配置逐段拆解模板之所以能“开箱即跑”核心在 src/payload.config.ts整份配置只有约 37 行却是理解整个模板的钥匙import { mongooseAdapter } from payloadcms/db-mongodb import { lexicalEditor } from payloadcms/richtext-lexical import path from path import { buildConfig } from payload import { fileURLToPath } from url import { Users } from ./collections/Users import { Media } from ./collections/Media import { vercelBlobStorage } from payloadcms/storage-vercel-blob const filename fileURLToPath(import.meta.url) const dirname path.dirname(filename) export default buildConfig({ admin: { user: Users.slug, importMap: { baseDir: path.resolve(dirname), }, }, collections: [Users, Media], editor: lexicalEditor(), secret: process.env.PAYLOAD_SECRET || , typescript: { outputFile: path.resolve(dirname, payload-types.ts), }, db: mongooseAdapter({ url: process.env.MONGODB_URL || , }), storage: [ vercelBlobStorage({ collections: { media: true, }, token: process.env.BLOB_READ_WRITE_TOKEN || , }), ], })逐项说明admin.user指定用于登录管理后台的集合这里指向Users.slugadmin.importMap.baseDir用于解析管理端组件映射对应src/app/(payload)/admin/importMap.js。collections注册Users与Media两个集合详情见下文。editor选择富文本编辑器为lexicalEditor()来自payloadcms/richtext-lexical。secret读取PAYLOAD_SECRET环境变量。typescript.outputFile把自动生成的类型写到同目录payload-types.ts即模板根下的 src/payload-types.ts可配合pnpm generate:types使用。db使用mongooseAdapter({ url })从MONGODB_URL读取连接串。若该变量为空Payload 在启动时将无法连库因此部署/开发前必须正确配置。storage注册vercelBlobStorage插件并把media集合指向 Vercel Blobtoken 取自BLOB_READ_WRITE_TOKEN。在对应包 packages/storage-vercel-blob/src/index.ts 的源码注释中可以看到其行为约定该插件基于payloadcms/plugin-cloud-storage实现当token未设置时插件会自动禁用并回退到本地存储当前只支持access: public的访问级别Vercel 后续才计划支持私有 blob可通过cacheControlMaxAge控制缓存时长默认一年、通过addRandomSuffix决定是否在上传文件名后加随机后缀等。也就是说模板的数据与文件分别走两条线结构化数据 → MongoDBAtlas 或本地容器上传的图片/视频等文件 → Vercel Blob。管理后台与前端则在同一个 Next.js 应用里共享配置。内置集合Users 与 Media模板刻意保持“最小”只注册了两个集合。Users认证集合src/collections/Users.tsexport const Users: CollectionConfig { slug: users, admin: { useAsTitle: email, }, auth: true, fields: [ // Email added by default // Add more fields as needed ], versions: false, }auth: true表示该集合启用认证Payload 会自动加上 email 字段、密码哈希与登录逻辑只有这里的用户能访问/admin管理面板admin.useAsTitle: email让后台列表中用 email 作为文档标题展示字段默认留空等待你按业务扩展如姓名、角色等关于认证集合的深入用法可参考仓库内 examples/auth 示例以及 docs/authentication/overview.mdx 认证文档。Media上传集合src/collections/Media.tsexport const Media: CollectionConfig { slug: media, access: { read: () true, }, fields: [ { name: alt, type: text, required: true, }, ], upload: true, }upload: true让该集合成为上传集合同时被上面storage中的vercelBlobStorage命中因此文件会落到 Vercel Blob自定义了一个必填的alt文本字段用于图片可访问性描述access.read: () true表示媒体文件公开可读——这是模板刻意为之的默认值方便前端直接展示注意该模板中的 Media 未像更完整的示例那样预置多尺寸缩略图如需尺寸生成、焦点控制focal point等能力可参考更完整的示例模板例如 templates/ecommerce与 docs/upload/overview.mdx 上传文档。集合结构的管理与扩展方式可继续阅读 docs/configuration/collections.mdx 集合配置文档。目录骨架Next.js 与 Payload 的路由是如何组织的模板在src/app下做了清晰的目录划分src/app/ ├── (frontend)/ # 公开站点页面你自己的业务 UI │ ├── layout.tsx │ ├── page.tsx # 首页根据登录态显示欢迎语 │ └── styles.css ├── (payload)/ # Payload 自带的管理面自动生成、勿手改 │ ├── admin/[[...segments]]/ # /admin 路由 │ ├── admin/importMap.js # 管理端组件导入映射 │ ├── api/[...slug]/route.ts # /api/... REST 端点 │ ├── api/graphql/route.ts # /api/graphql │ ├── api/graphql-playground/ # GraphQL Playground │ ├── custom.css │ └── layout.tsx # Payload RootLayout 装配 └── my-route/route.ts # 你可以按需添加的任意自定义路由其中(payload)组里的入口文件都带 “generated automatically by payload” 注释例如 src/app/(payload)/layout.tsx/layout.tsx) 从payloadcms/next/layouts引入RootLayout、generatePayloadViewport与handleServerFunctions并装配importMap——这些是 Payload 管理后台在 Next.js App Router 下的标准接线正常情况下不需要改动。(frontend)才是你写业务页面的地方二者共享同一个 Payload 配置实例。测试骨架验证你的模板改动模板虽然“最小”但仍携带了一套可运行的测试基建templates/with-vercel-mongodb/testse2e/基于 Playwright 的端到端测试分别覆盖管理后台admin.e2e.spec.ts与前端页面frontend.e2e.spec.ts配套helpers/login.ts、helpers/seedUser.ts完成登录与造数int/基于 Vitest 的集成测试api.int.spec.ts通过pnpm test即可依次执行集成测试与端到端测试运行配置见 playwright.config.ts 与 vitest.config.mts。这为你后续扩展集合、新增接口时提供了一套可参考的回归保障范式。后续路径与常见问题速查扩展集合与字段注册新集合只需在src/collections新增配置文件、写进collections数组字段系统文档见 docs/fields/overview.mdx。认证相关改密码、多因素、策略等见 docs/authentication/overview.mdx完整可运行示例见 examples/auth。富文本默认启用 Lexical 编辑器扩展能力见 docs/rich-text/overview.mdx。REST 与 GraphQL模板已挂载/api/...REST 与 GraphQL/Playground 路由接口约定见 docs/rest-api/overview.mdx 与 docs/graphql/overview.mdx。常见错误自查若本地请求媒体文件返回 404/失败先检查.env是否配置了BLOB_READ_WRITE_TOKEN未配置时按插件源码逻辑会回退到本地存储注意与线上行为一致若管理后台登录异常检查PAYLOAD_SECRET是否为空或前后不一致。模板间的横向对比若你并不需要 Vercel 生态或想换数据库可参考同目录下其他模板例如 templates/with-postgres、templates/blank 与 templates/with-vercel-postgres。综上with-vercel-mongodb是一个“配置面小、可运行面全”的模板它以 Payload 3 MongoDB Vercel Blob 三件套打通了一条从git clone、.env配置、pnpm dev本地开发到 Vercel 一键部署的完整链路。你可以基于它在一小时级的时间内把管理后台与数据库接通然后把全部精力投入到自己的业务集合与前端页面中。【免费下载链接】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），仅供参考