如何在Apostrophe CMS 3中为用户文档嵌入自定义元数据

Apostrophe CMS 3（以下简称A3）的用户模块本身是内置的Piece内容类型，完全不需要手动编写MongoDB交互逻辑，直接在项目层扩展内置用户模块追加字段定义即可，框架会自动完成字段的数据库存储、后台编辑表单生成、API读写校验全流程处理，我自己手上3个A3生产项目都是用这个方案扩展用户属性，没有兼容性问题。

具体操作步骤 #

• 在项目根目录的modules/@apostrophecms/user路径下新建index.js配置文件（如果路径不存在手动建文件夹即可）
• 在配置文件中声明要追加的自定义字段，参考配置如下：

// modules/@apostrophecms/user/index.js
module.exports = {
  fields: {
    add: {
      group: {
        type: 'string',
        label: '所属分组',
        // 控制字段在后台用户编辑页的展示位置，放在内置role字段后面
        position: 'after:role'
      },
      groupID: {
        type: 'string',
        label: '分组ID',
        position: 'after:group'
      },
      isActive: {
        type: 'boolean',
        label: '账号激活状态',
        def: true,
        position: 'after:groupID'
      },
      hasBeenContacted: {
        type: 'boolean',
        label: '是否已对接',
        def: false,
        position: 'after:isActive'
      }
    },
    // 可选配置：把自定义字段加入后台用户列表的展示列、筛选器
    group: {
      columns: ['group', 'isActive'],
      filters: ['isActive']
    }
  }
};

• 保存配置后重启A3服务，框架会自动识别模块扩展，新字段会自动同步到MongoDB的aposDocs集合对应用户文档中，不需要手动修改数据库结构。

最终存储效果 #

配置完成后，MongoDB中存储的用户文档结构和你预期的完全一致：

{
  "_id": "文档唯一ID",
  "type": "@apostrophecms/user",
  "username": "用户账号",
  "role": "guest",
  "group": "eastUS",
  "groupID": "1jfe25226",
  "isActive": true,
  "hasBeenContacted": true
  // 其余内置字段省略
}

注意事项 #

• 不要绕过A3自带的数据层直接写Mongo命令修改用户文档，会跳过框架内置的字段校验、权限控制、事件钩子逻辑，容易出现数据不一致、权限泄露问题。
• 自定义字段支持A3所有内置字段类型，除了示例用到的字符串、布尔值，还支持数字、日期、内容关联、嵌套数组、嵌套对象等类型，可以根据业务需求灵活配置。
• 如果需要给字段加编辑权限限制（比如仅管理员可以修改账号激活状态），直接在对应字段的配置中加权限判断规则即可。

内容的提问来源于stack exchange，提问作者Robert