如何在Next.js自定义Clerk注册流程中添加用户角色（Django+Next.js架构）

方案1：通过Clerk公共元数据传递角色（推荐，契合现有Webhook流程） #

核心思路是在前端注册时，把角色存入Clerk用户的公共元数据，后端通过user.created Webhook直接读取该字段存入数据库。

针对内置SignUp组件 #

在司机/乘客各自的注册页面，给SignUp组件传入initialValues指定公共元数据：

// 司机注册页
<SignUp
  initialValues={{
    publicMetadata: { role: 'driver' }
  }}
  // 其他配置项
/>

// 乘客注册页
<SignUp
  initialValues={{
    publicMetadata: { role: 'passenger' }
  }}
  // 其他配置项
/>

用户注册完成后，Clerk会自动将角色写入用户的公共元数据。后端处理Webhook时，从事件payload的public_metadata字段中取出role，存入Django用户表对应字段即可。

针对自定义注册表单（useClerk + client.SignUp.create()） #

调用创建用户接口时，直接在参数中加入publicMetadata：

const { client } = useClerk();

const handleSignUp = async () => {
  const signUp = await client.signUp.create({
    emailAddress: userEmail,
    password: userPassword,
    publicMetadata: { role: 'driver' } // 根据当前页面设置对应角色
  });
  // 后续邮箱验证等逻辑...
};

Webhook的payload会包含该公共元数据，后端直接解析使用。

方案2：注册完成后主动调用Django接口写入角色 #

如果不想依赖Clerk元数据，可在用户注册成功后，直接调用后端接口传递角色信息。

内置SignUp组件的实现 #

利用组件的onComplete回调，注册成功后立即调用后端接口：

<SignUp
  onComplete={(user) => {
    fetch('/api/set-user-role', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        clerk_user_id: user.id,
        role: 'driver' // 当前页面对应角色
      })
    });
  }}
/>

自定义表单的实现 #

在创建用户成功后，获取用户ID并调用后端接口：

const handleSignUp = async () => {
  const signUp = await client.signUp.create({
    emailAddress: userEmail,
    password: userPassword
  });
  if (signUp.status === 'complete') {
    const userId = signUp.createdUserId;
    fetch('/api/set-user-role', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        clerk_user_id: userId,
        role: 'passenger'
      })
    });
  }
};

Django后端需提供对应POST接口，根据clerk_user_id找到数据库中的用户，更新role字段。

方案3：利用Clerk角色系统（进阶权限控制） #

若需要更完善的权限体系，可先在Clerk后台创建driver和passenger角色，前端注册时直接为用户分配对应角色：

内置SignUp组件 #

<SignUp
  initialValues={{
    role: 'driver'
  }}
/>

自定义表单 #

const signUp = await client.signUp.create({
  emailAddress: userEmail,
  password: userPassword,
  role: 'driver'
});

后端Webhook的user.created事件payload中会包含roles字段，直接读取存入数据库即可。

关键注意事项 #

• 若之前误用privateMetadata，后端Webhook无法读取该字段，必须改用publicMetadata或直接分配角色。
• 确保Clerk Webhook配置中勾选了元数据、角色等所需字段，避免payload缺失信息。
• 自定义表单时，需等用户完成邮箱验证（注册流程彻底结束）后再调用后端接口，避免无效数据写入。

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