Payload CMS 自定义集合 Collection 怎么建与配置

2026/9/53 min read

Payload CMS 自定义集合 Collection 怎么建与配置

在 Payload CMS 中，"自定义集合"（Collections）是管理结构化数据的核心单元。要建立一个可投入使用的 Collection，你需要在 payload.config.ts 中注册集合定义，指定字段结构、访问权限及路由路径，最后在入口文件挂载 Payload 实例。我通常将这一过程分为定义 Schema、配置选项和挂载服务三步走。

什么是 Payload CMS Collection

Collection 类似于传统关系型数据库中的表。每一个 Collection 代表一类实体，比如“文章”、“用户”或“产品”。与页面（Globals）不同，Collection 支持多条记录、版本控制和复杂的过滤查询。我在设计时，会优先考虑字段的可扩展性，比如为所有集合默认添加 title、slug 和 createdAt/updatedAt 字段，这样后续搜索和排序会顺手很多。

如何定义 Collection Schema

定义集合的第一步是在配置文件中注册它。下面是一个标准的自定义集合示例，包含了文本、关系和数组类型字段：

import { buildConfig } from 'payload/config';
import { mongooseAdapter } from '@payloadcms/db-mongodb';

export default buildConfig({
  collections: [
    {
      slug: 'products',
      labels: {
        singular: '产品',
        plural: '产品列表',
      },
      fields: [
        {
          name: 'title',
          label: '产品名称',
          type: 'text',
          required: true,
        },
        {
          name: 'slug',
          label: 'URL 标识',
          type: 'text',
          unique: true,
          index: true,
        },
        {
          name: 'category',
          label: '所属分类',
          type: 'relationship',
          relationTo: 'categories',
          required: true,
        },
        {
          name: 'specifications',
          label: '规格参数',
          type: 'array',
          fields: [
            {
              name: 'key',
              label: '参数名',
              type: 'text',
            },
            {
              name: 'value',
              label: '参数值',
              type: 'text',
            },
          ],
        },
      ],
    },
  ],
  // ... 其他配置
});

注意，slug 是集合的唯一标识，必须与 URL 路径对应。我倾向于将 slug 字段单独设置为 unique: true 并加索引，这样在前端生成路由时能直接复用该字段，避免额外的数据库查询。

Collection 的常用配置选项

除了字段，集合级别的配置决定了数据的生命周期和行为。我最常用的几个选项包括：

access：控制谁可以读写该集合。例如，我只允许管理员删除产品：
```
access: {
  delete: ({ req: { user } }) => Boolean(user?.role === 'admin'),
},
```
timestamps：是否自动生成 createdAt 和 updatedAt。我一般开启，但若需要审计日志，我会手动添加 deletedAt 字段并启用软删除。
defaultSort：设置默认排序，比如按创建时间倒序，这样在后台列表页能第一时间看到最新内容。

挂载 Payload 实例

定义完集合后，需要在应用入口挂载 Payload。对于 Next.js 项目，通常是在 payload.config.ts 导出配置后，在 next.config.js 或专门的启动脚本中调用 payload.init()。如果你使用的是 Express，则在 server.ts 中初始化：

import payload from 'payload/init';

async function start() {
  await payload.init({
    secret: process.env.PAYLOAD_SECRET || '',
    mongoURL: process.env.MONGODB_URI || '',
    express: app,
  });
  app.listen(3000);
}
start();

这一步完成后，Payload 会自动根据集合的 slug 创建对应的 REST/GraphQL 路由。我遇到过的问题是忘记重启服务导致新集合未生效，因此在开发阶段养成随时重启的习惯很重要。

常见错误与调试技巧

Slug 冲突：如果两个集合用了相同的 slug，Payload 启动时会报错。我总是用 linter 脚本检查整个配置文件中是否重复。
字段类型不匹配：关系字段引用的 relationTo 对应的集合必须已经定义且启动成功，否则会出现连接错误。
中文标签乱码：确保配置文件编码为 UTF-8，并在编辑器中保存时使用 UTF-8 无 BOM 格式。

想要深入了解 Payload 的插件机制或中间件，可以查阅官方文档中的高级配置章节，或者看看我们之前关于自定义 React 组件的字段的实践总结。

Payload CMS 自定义集合 Collection 怎么建与配置