Google Identity Platform/Firebase Auth阻塞函数失效，无法限制未验证邮箱登录

要实现「用户创建账户后需验证邮箱才能登录」的流程，正确的做法是结合Firebase Admin SDK 创建用户、发送验证邮件，同时配合beforeSignIn 阻塞函数拦截未验证用户的登录请求，具体步骤如下：

1. 客户端仅收集信息，通过云函数完成用户创建与验证邮件发送 #

放弃客户端直接调用createUserWithEmailAndPassword，改用云函数处理核心逻辑——避免客户端自动登录，同时在服务端确保用户创建与验证邮件发送的时序正确性：

客户端代码 #

async function registerWithEmail(email, password) {
  try {
    await firebase.functions().httpsCallable('createUserAndSendVerification')({
      email,
      password
    });
    alert('账户已创建，请查收邮箱验证链接');
  } catch (err) {
    console.error('注册失败:', err);
    alert(err.message);
  }
}

云函数（创建用户+发送验证邮件） #

import admin from 'firebase-admin';
import functions from 'firebase-functions';
admin.initializeApp();

export const createUserAndSendVerification = functions.https.onCall(async (data, context) => {
  const { email, password } = data;
  
  // 创建用户（服务端创建不会触发客户端自动登录）
  const userRecord = await admin.auth().createUser({
    email,
    password,
    emailVerified: false // 默认标记为未验证
  });

  // 生成验证链接
  const actionCodeSettings = {
    url: `${process.env.FRONTEND_URL}/login`, // 验证完成后跳转登录页
    handleCodeInApp: false
  };
  const verificationLink = await admin.auth().generateEmailVerificationLink(email, actionCodeSettings);
  
  // 调用自定义邮件发送逻辑
  await sendCustomVerificationEmail(email, verificationLink);

  return { message: '验证邮件已发送' };
});

const sendCustomVerificationEmail = async (email, link) => {
  // 替换为你的实际邮件发送实现（如SendGrid、Mailgun等）
  console.log(`发送验证邮件至 ${email}: ${link}`);
};

2. 用beforeSignIn阻塞函数拦截未验证用户的登录请求 #

保留角色分配逻辑，调整错误抛出类型，确保客户端能明确识别拦截原因：

import gcipCloudFunctions from 'gcip-cloud-functions';
import admin from 'firebase-admin';

const app = admin.initializeApp();

export const beforeSignInHandler = async (user, context, adminEmails) => {
  if (!user.emailVerified) {
    // 可选：重发验证邮件，避免用户丢失初始邮件
    try {
      const actionCodeSettings = {
        url: `${process.env.FRONTEND_URL}/login`,
        handleCodeInApp: false
      };
      const link = await app.auth().generateEmailVerificationLink(user.email, actionCodeSettings);
      await sendCustomVerificationEmail(user.email, link);
    } catch (err) {
      console.error('重发验证邮件失败:', err);
    }

    // 抛出明确权限错误，客户端可据此提示用户
    throw new gcipCloudFunctions.https.HttpsError(
      'permission-denied', 
      '请先验证你的邮箱地址'
    );
  }

  // 原有角色分配逻辑保持不变
  const role = adminEmails.includes(user.email) ? 'admin' : 'user';
  return { customClaims: { role } };
};

const sendCustomVerificationEmail = async (email, link) => {
  console.log(`发送验证邮件至 ${email}: ${link}`);
};

原方案失败原因解析 #

1. 客户端直接调用createUserWithEmailAndPassword：该方法默认会完成「用户创建+自动登录」，无法阻止这一行为，直接违反「创建后不允许登录」的需求。
2. beforeCreate中调用generateEmailVerificationLink：用户数据尚未持久化到数据库，因此无法生成验证链接，官方文档此处存在误导。
3. 首次注册时beforeSignIn中用户不存在：注册流程中beforeSignIn触发时，用户数据还未完成持久化，导致generateEmailVerificationLink报错，属于Identity Platform的时序特性问题。

流程验证 #

1. 用户在客户端输入邮箱和密码，调用云函数发起注册
2. 云函数创建用户并发送验证邮件，客户端收到成功提示
3. 用户点击邮件链接完成邮箱验证
4. 用户返回登录页输入账号密码，beforeSignIn验证邮箱已通过，允许登录并分配角色
5. 若用户未验证就尝试登录，beforeSignIn拦截请求并提示，同时重发验证邮件

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