Strapi v4用户注册邮箱验证问题：开启邮件确认后注册表单失效

以下是针对Strapi v4开启邮件确认后注册表单无法工作的排查和解决步骤：

1. 检查用户权限插件的基础配置 #

确保config/plugins.js（TS项目为config/plugins.ts）中正确启用了邮件确认功能：

module.exports = ({ env }) => ({
  // 其他插件配置
  'users-permissions': {
    config: {
      emailConfirmation: true,
    },
  },
});

同时确认用户模型（src/api/user/models/user.settings.json）中email字段为必填且唯一，这是邮件验证的基础：

{
  "attributes": {
    "email": {
      "type": "email",
      "required": true,
      "unique": true
    },
    // 其他用户字段配置
  }
}

2. 验证邮件服务配置（核心问题点） #

邮件发送失败是导致注册流程中断的最常见原因，必须正确配置邮件提供者：
在config/plugins.js中添加邮件服务配置（以SMTP为例）：

module.exports = ({ env }) => ({
  // 其他插件配置
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: env('SMTP_HOST', 'smtp.your-domain.com'),
        port: env('SMTP_PORT', 587),
        auth: {
          user: env('SMTP_USERNAME'),
          pass: env('SMTP_PASSWORD'),
        },
        secure: env('SMTP_SECURE', false), // 根据邮件服务商要求设置
      },
      settings: {
        defaultFrom: 'no-reply@your-domain.com',
        defaultReplyTo: 'support@your-domain.com',
      },
    },
  },
});

确保.env文件中已正确设置SMTP相关环境变量：

SMTP_HOST=smtp.your-domain.com
SMTP_PORT=587
SMTP_USERNAME=your-email@your-domain.com
SMTP_PASSWORD=your-smtp-password
SMTP_SECURE=false

可以通过Strapi后台管理面板的「设置-邮件」发送测试邮件，确认邮件服务正常工作。

3. 排查注册端点的响应与前端处理 #

开启邮件确认后，/api/auth/local/register端点会返回200状态码及如下响应：

{
  "user": {...},
  "jwt": "...",
  "confirmationSent": true
}

检查前端代码是否正确处理了该响应，避免因未识别confirmationSent字段导致逻辑错误。若后端报错，执行strapi logs查看具体错误信息（如SMTP认证失败、邮箱格式错误等）。

4. 自定义注册逻辑的兼容处理 #

如果自定义了用户注册控制器，确保没有覆盖默认的邮件确认逻辑。示例兼容代码如下：

// src/api/user/controllers/user.js
module.exports = {
  async register(ctx) {
    // 自定义前置逻辑
    const { user, jwt } = await strapi.plugins['users-permissions'].services.user.add(ctx.request.body);
    // 调用内置服务发送确认邮件
    await strapi.plugins['users-permissions'].services.user.sendConfirmationEmail(user);
    // 返回标准响应
    ctx.send({ user, jwt, confirmationSent: true });
  },
};

5. 直接测试注册端点 #

使用curl或Postman直接调用注册端点，排除前端代码干扰：

curl -X POST http://localhost:1337/api/auth/local/register \
  -H "Content-Type: application/json" \
  -d '{"username":"test_user","email":"test@example.com","password":"ValidPass123!"}'

根据返回结果和日志定位具体问题。

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