Payload Blank Template 快速上手从本地开发到 Docker 部署的零配置启动指南【免费下载链接】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本指南面向希望从零起步、快速搭建一个基于 Payload CMS 与 Next.js 全栈应用的开发者。本文以仓库内 templates/blank 模板为核心完整讲解其目录结构、内置的 Users / Media / Folders / Tags 四大集合Collections、.env 环境变量配置以及pnpm dev、Docker 本地数据库两种启动路径。读完本文你将掌握如何用最小可用配置启动 Payload 管理后台与前台页面并能为自己的业务自由扩展集合与路由。Blank Template 是什么Payload Blank Template 是 payload 官方维护的空模板——它与仓库内其他模板如 ecommerce、website的区别在于只携带启动任何业务所必需的极简配置。模板的 README.md 开宗明义地说明This template comes configured with the bare minimum to get started on anything you need.换言之它是一个无业务假设的脚手架没有预置博客、电商或营销页逻辑但已具备数据建模Collection、认证、媒体上传、富文本编辑、GraphQL/REST 接口与后台界面等 Payload 的核心底座非常适合用来验证想法、作为学习起步点或当作新项目的骨架。从模板的 package.json 可以看到其技术栈组成依赖作用payloadPayload 核心框架payloadcms/next在 Next.js 中挂载 Payload 应用含管理后台与 APIpayloadcms/db-mongodbMongoDB 数据库适配器payloadcms/richtext-lexical默认富文本编辑器基于 Lexicalpayloadcms/plugin-mcpMCP 插件模型上下文协议next/react/react-domNext.js 渲染层sharp图片处理引擎用于上传裁剪与格式转换graphqlGraphQL 端点支持值得说明的是Blank 模板默认使用MongoDB作为数据库配置于 payload.config.ts这与仓库中同样基于 Next.js 但面向 PostgreSQL 的 with-postgres 等模板形成对照可按部署目标选择。快速开始三步跑通本地开发模板官方 README 给出的本地启动流程非常短核心命令如下执行目录为模板所在项目根目录# 1. 准备环境变量 cp .env.example .env # 2. 安装依赖并启动开发服务器 pnpm install pnpm dev # 3. 浏览器打开 open http://localhost:3000结合 package.json 的 scripts 定义pnpm dev实际执行的是next dev通过cross-env设置NODE_OPTIONS--no-deprecation以抑制 Node 的弃用警告。模板目录中确实预置了 .env.example 文件可通过ls -a在 templates/blank 目录中确认内容结构上至少需要提供两类关键变量DATABASE_URL或MONGODB_URLMongoDB 连接串Payload 通过mongooseAdapter读取见 payload.config.tsPAYLOAD_SECRET用于加密与签名的服务端密钥模板在 payload.config.ts 中以process.env.PAYLOAD_SECRET || 方式读取——生产环境务必设置为足够长的随机串留空将导致会话与令牌校验不可用。首次启动后访问http://localhost:3000页面会显示欢迎页并引导你进入/admin创建第一个管理员账号前台欢迎页的具体实现位于 src/app/(frontend)/page.tsx/page.tsx)其逻辑会通过payload.auth({ headers })读取当前会话未登录时显示 Welcome to your new project.已登录则显示 Welcome back, {email}并输出前往管理后台的入口链接。环境变量的来源说明原 README 特别强调若通过Payload Cloud的Deploy按钮部署平台会为你创建 MongoDB 数据库与 S3 对象存储此时需将云项目的MONGODB_URL填入本地.env才能同时使用云端数据库与 S3 存储而在纯本地 MongoDB 场景下可将其改为mongodb://127.0.0.1/dbname详见下文 Docker 章节。使用 Docker 启动数据库可选路径如果你不想在宿主机单独安装 MongoDB模板自带的 docker-compose.yml 可以直接拉起整套环境。原 README 给出了两条使用路径。路径一仅用 Docker 跑数据库代码在宿主机运行完成上文cp .env.example .env将.env中的数据库连接串指向本地容器例如mongodb://127.0.0.1/dbname同步修改 docker-compose.yml 中mongo服务注释里提示的 hostname 约定容器内数据库主机名是mongo因此 DATABASE_URL 应写作mongodb://mongo/my-db-name宿主机访问则用127.0.0.1运行docker-compose up启动数据库容器追加-d可后台运行。路径二整体容器化运行应用 数据库.docker-compose.yml 定义了三个服务payload基于node:20-alpine镜像挂载项目源码与独立node_modules卷容器启动时依次执行corepack enable、准备 pnpm、pnpm install与pnpm dev并把宿主3000端口映射到容器mongomongo:latest使用 wiredTiger 存储引擎数据持久化到命名卷data同时暴露宿主27017端口postgres被注释如需切换 PostgreSQL取消注释并把 payload.config.ts 的mongooseAdapter替换为payloadcms/db-postgres提供的 postgres 适配器即可。原 README 建议优先走路径一也就是本机跑代码、Docker 只提供数据库这样既保证./src中代码改动即时热更新也能统一团队开发环境若必须整体容器化docker-compose up后同样访问http://localhost:3000完成管理员创建。模板如何运作目录结构与 Payload 配置剖析README 中 How it works 一节明确指出该模板的 Payload 配置是面向大多数网站通用需求裁剪的。整个骨架围绕 src/payload.config.ts 这一单一配置文件展开。目录结构解读模板源码布局如下与仓库根目录test/下的集成测试配置不同这是独立应用templates/blank/ ├── .env.example # 环境变量样例 ├── docker-compose.yml # Docker 数据库编排 ├── next.config.ts # Next.js 配置含 payloadcms/next 封装 ├── src/ │ ├── collections/ # Users / Media / Folders / Tags 集合定义 │ ├── app/ │ │ ├── (frontend)/ # 前台页面layout / page / styles │ │ ├── (payload)/ # Payload 后台 layout admin 入口 REST/GraphQL 路由 │ │ └── my-route/ # 演示用的自定义路由 │ └── payload.config.ts # 核心配置其中 src/app/(payload)/layout.tsx/layout.tsx) 是由 Payload 自动生成的根布局它从payloadcms/next/layouts引入RootLayout与handleServerFunctions并注入admin/importMap.js组件映射表因此该文件顶部明确标注DO NOT MODIFY——需要扩展后台时请通过配置中的admin.importMap与组件路径完成。payload.config.ts 中的核心配置项如下export default buildConfig({ admin: { user: Users.slug, // 后台登录使用 users 集合 importMap: { baseDir: path.resolve(dirname) }, }, collections: [Users, Media, Folders, Tags], editor: lexicalEditor(), // 富文本编辑器 secret: process.env.PAYLOAD_SECRET || , typescript: { outputFile: path.resolve(dirname, payload-types.ts), // 类型生成位置 }, db: mongooseAdapter({ url: process.env.DATABASE_URL || }), sharp, localization: { locales: [en], fallback: true, defaultLocale: en, }, plugins: [mcpPlugin({})], })注意这里环境变量名是DATABASE_URLREADME 的 Cloud 流程中提到的MONGODB_URL是其等价来源类型输出文件 payload-types.ts 由payload generate:types命令生成脚本见 package.json。Users启用认证的管理员集合src/collections/Users.ts 是标准的 Payload 认证集合写法export const Users: CollectionConfig { slug: users, admin: { useAsTitle: email }, auth: true, // 开启认证能力 fields: [ /* email 默认自带按需追加字段 */ ], versions: false, }要点解读auth: true让该集合成为可登录后台的认证集合同时拥有邮件与密码字段密码以哈希形式存储、永不通过 API 返回useAsTitle: email让后台列表用 email 字段展示记录versions: false关闭该集合的版本历史若需草稿/版本能力可开启参见仓库 docs/versions/overview.mdxadmin.user指定其为后台登录用户集合。Media开箱即用的上传集合README 中特别强调 Media 是uploads enabled 集合具备预置尺寸、焦点focal point与手动裁剪能力。其实现见 src/collections/Media.tsexport const Media: CollectionConfig { slug: media, access: { read: () true }, // 允许公开读取供前台 img 直链 fields: [ { name: alt, type: text, required: true }, createFolderField({ relationTo: folders }), // 文件夹归属 createTagField({ relationTo: tags }), // 标签关联 ], upload: true, }关键点upload: true启用文件上传能力配合 sharp 完成图片自动处理尺寸生成、WebP/AVIF 等格式输出、焦点裁剪access.read: () true意味着任何人可读取媒体文件——这正是前台页面能直接展示图片的前提alt字段为必填文本保证无障碍与 SEO 描述完整。Folders 与 Tags组织结构化媒体相较于仓库根目录更早期的 Blank 配置本模板额外引入了Folders与Tags两个集合见 payload.config.ts用于给媒体文件做归类管理src/collections/Folders.tsslug: folders开启folders: true的文件夹集合必填name文本字段后台以name作标题src/collections/Tags.tsslug: tags开启tags: true的标签集合结构同样是必填name字段。这两个集合与 Media 之间通过createFolderField({ relationTo: folders })/createTagField({ relationTo: tags })均来自payload包导出建立一对多关系实现上传即归入文件夹并打标签的后台体验——对应 Payload 官方的文件夹Folders与标签Tags特性可参考仓库文档 docs/folders/overview.mdx。管理与 API 路由的自动生成模板中的(payload)目录是 Payload 在 Next.js 内的挂载区包含管理后台入口(payload)/admin/[[...segments]]/page.tsx与配套的not-found.tsx承载/admin全部界面REST API(payload)/api/[...slug]/route.ts将所有/api/{collection|global}请求转交给 Payload 处理GraphQL(payload)/api/graphql/route.ts提供/api/graphql查询端点graphql-playground提供可视化调试界面依赖 package.json 中的graphql依赖自定义路由演示src/app/my-route/route.ts源码位于src/app/my-route可用ls templates/blank/src/app/确认目录展示了在 Payload 应用内自由编写 Next.js Route Handler 的方式。同时 next.config.ts 通过withPayload(...)包装 Next 配置并设置了images.localPatterns允许 Next 的Image组件加载/api/media/file/**本地图片webpack 扩展别名让.js/.mjs/.cjs导入能解析到对应.ts/.tsx源码便于在 Payload 生态中直引 TS 文件turbopack.root指定 Turbopack 的根目录。测试与常见问题模板还自带了开箱可用的测试基建脚本见 package.jsonpnpm run test:int基于 Vitest 的接口集成测试配置于 vitest.config.mtspnpm run test:e2e基于 Playwright 的端到端测试配置文件为 playwright.config.ts测试辅助代码位于 tests包含管理员登录、前台渲染等场景的用例。其他实用脚本同样在 package.json 中暴露payload generate:types重新生成 payload-types.tspayload generate:importmap重建组件导入映射payload build构建生产版本next start以生产模式启动。常见排障提示页面加载后提示数据库连接失败检查.env中DATABASE_URL/MONGODB_URL是否与 docker-compose 的主机名约定一致容器间用mongo宿主机用127.0.0.1想新增业务集合在 src/collections 下新建CollectionConfig并在 payload.config.ts 的collections数组注册即可REST 与 GraphQL 端点会自动出现需要本地 SQL 数据库参考 .docker-compose.yml 中被注释的postgres服务并切换 payload.config.ts 的数据库适配器。下一步从 Blank 起步延伸一旦熟悉了 Blank 模板的最小骨架可沿以下方向在仓库中继续深入集合与字段配置官方配置文档见 docs/configuration/collections.mdx、字段全集见 docs/fields/overview.mdx认证深入Users 的 auth 机制细节见 docs/authentication/overview.mdx功能更完整的认证示例可对照仓库 examples/auth上传与图片处理Media 的 sizes、焦点裁剪等选项见 docs/upload/overview.mdx管理后台定制dashboard、自定义视图等见 docs/custom-components按业务选择更完整的起点需要营销/博客能力可用 website需要商城则用 ecommerce需要 PostgreSQL 则对照 with-postgres 或 with-vercel-postgres。无论从哪一个模板起步Blank 都提供了一个没有任何历史包袱的干净底座理解它的目录与配置方式就等于理解了所有 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），仅供参考