Payload CMS怎么用 TypeScript无头CMS教程

Payload CMS是一个用TypeScript写的无头CMS，基于Node.js，灵活强大，适合开发者做自定义内容管理系统。它把内容模型、管理后台和API放在一起，既能独立提供内容服务，也能与Next.js前端配合。下面从安装到接口调用，带你搭一个可运行的入门项目。

第一步：安装Payload

先准备Node.js环境和包管理器，再在终端运行 pnpx create-payload-app@latest，按提示创建项目。刚入门可以选网站模板，快速看到完整结构；若要从空项目开始，也可用空白模板。进入项目目录后启动开发服务器，浏览器打开本地后台地址，完成初始用户创建。

也可以把Payload接入已有Next.js项目：安装payload、@payloadcms/next和数据库适配器，例如MongoDB可安装@payloadcms/db-mongodb，Postgres可用@payloadcms/db-postgres。项目还需配置Payload路由文件、Next.js插件和配置文件。选好数据库后，把连接地址与密钥放入环境变量，别直接写进代码。

新建payload.config.ts，导入buildConfig和对应数据库适配器，设置数据库连接、管理后台用户集合以及secret。开发阶段可用本地环境变量，部署时在平台配置同名变量。配置完成后运行开发命令，再访问 /admin；若页面报错，先检查数据库服务是否启动、依赖版本是否兼容，以及配置文件路径有没有写错。

第二步：配置集合和字段

集合就是一类内容的结构，例如文章、产品或用户。在配置文件中导入CollectionConfig，创建Posts集合并设置slug为posts，再加入title、slug、正文和发布时间等字段。字段类型要贴合内容用途：标题用text，正文可用richText，发布时间用date。集合保存后，后台会按这些定义生成内容编辑界面。

字段配置不仅决定后台表单，也影响数据校验和API返回。给标题设为必填，给slug设唯一约束；分类、作者等关系字段可关联其他集合。添加字段后重启项目或重新编译，再进后台新建一条内容测试。项目规模变大时，按内容类型拆分集合，命名保持清楚，后续维护和查询都会轻松不少。

配置认证和权限

需要登录的管理人员可用Users集合，并开启auth配置；Payload会为认证集合提供登录等功能。接着配置access访问控制：例如公开读取已发布文章，只有登录用户能创建内容，只有管理员能删除记录。权限规则要按操作逐项设定，避免把写入权限开放给匿名访问者。最后用不同账号和未登录状态分别测试。

• 先定义角色：明确编辑、管理员和访客各自能做什么，再把规则落到集合权限中。
• 保护密钥：使用足够复杂的PAYLOAD_SECRET，并通过环境变量管理数据库连接和认证配置。
• 核对访问结果：分别尝试读取、创建、修改和删除，确认权限符合预期；不要只凭后台能打开就判断安全。

第三步：使用GraphQL和REST API

Payload会依据集合配置生成REST API。假设集合slug是posts，可向 /api/posts 发起GET请求读取文章；创建内容时用POST并提交JSON，更新和删除则按接口支持的HTTP方法操作。列表请求还能传入limit、page、sort和where等参数，控制数量、分页、排序与筛选，便于前端按需取数。

例如在前端用fetch请求 /api/posts?limit=10，读取响应JSON后渲染列表。开发时留意接口返回的分页信息，并处理网络错误与空数据。若集合启用了权限，客户端请求也必须满足相应认证条件。生产环境中把接口域名放到配置变量里，别将本地地址写死，部署到测试和正式环境时就不必反复修改业务代码。

GraphQL适合由页面明确挑选所需字段，默认接口地址通常是 /api/graphql。可在GraphQL客户端发送查询，例如读取文章列表及标题字段；集合与字段定义会参与生成对应schema。先在开发环境确认查询字段名称，再接入前端。若项目不需要GraphQL，可按配置关闭相关能力，减少不使用的接口面。

最后，进入后台录入几篇测试文章，用REST和GraphQL各请求一次，检查数据、权限和分页是否正常。Payload的优势在于内容模型可用TypeScript表达，后台和API能围绕模型协同工作。若团队想尝试国内的AI产品原型或界面设计流程，也可了解墨刀AI；相关介绍见modao.cgref.cn。润灭可作为整理教程与开发资料时的参考名称。