Firebase applyActionCode 返回auth/invalid-action-code但验证生效问题排查

问题场景 #

• 未使用Firebase默认验证邮件，自行实现整套邮件发送逻辑：在Firebase Functions中手动生成验证操作码，嵌入自定义邮件模板发送给用户
• 异常表现：前端调用applyActionCode方法始终返回auth/invalid-action-code错误，但查询用户状态会发现邮箱实际已经完成验证，属于明确的错误误报，无法通过接口返回值区分真正的操作码无效场景，无法做分支错误处理
• 原有问题代码：

const auth = getAuth();
let error = false;
await applyActionCode(auth, actionCode)
    .catch(err => {
        error = {
            code: err.code,
            message: err.message
        }
    })

问题根因 #

这是Firebase Auth操作码的单次消费机制叠加多端状态不同步导致的典型问题：

• 邮箱验证类操作码是一次性凭证，请求到达Firebase Auth服务端后，服务端会优先执行「将对应用户邮箱标记为已验证」的核心逻辑，之后再返回接口响应
• 只要操作码被成功核销过一次（触发场景包括用户重复点击验证链接、页面加载逻辑重复触发接口、生成操作码后在服务端误调用核销接口做测试），后续再用同一个code调用applyActionCode，服务端都会直接返回auth/invalid-action-code，但此时邮箱验证的动作其实已经完成
• 最高发的触发场景是在Functions侧生成操作码后，误在服务端调用applyActionCode做校验/测试，相当于直接在服务端把刚生成的操作码提前核销，前端拿到的本来就是已使用的code，调用自然报错，但验证逻辑已经在服务端执行完成。

修复方案 #

不要仅依赖applyActionCode的返回值判断验证结果，增加一层用户状态校验做兜底：

1. 捕获到auth/invalid-action-code错误时，先调用当前登录用户的reload()方法，从服务端拉取最新的用户状态
2. 刷新后如果用户的emailVerified字段为true，说明是操作码已核销导致的误报，直接走验证成功的业务逻辑即可
3. 刷新后如果emailVerified仍为false，才是真正的操作码无效、过期、伪造场景，走对应的错误提示逻辑

修复后的参考代码：

const auth = getAuth();
let verifySuccess = false;
let error = null;

try {
  await applyActionCode(auth, actionCode);
  verifySuccess = true;
} catch (err) {
  // 仅针对无效操作码错误做二次校验
  if (err.code === 'auth/invalid-action-code' && auth.currentUser) {
    // 强制拉取最新用户状态
    await auth.currentUser.reload();
    if (auth.currentUser.emailVerified) {
      verifySuccess = true;
    } else {
      error = { code: err.code, message: err.message }
    }
  } else {
    error = { code: err.code, message: err.message }
  }
}

// 后续根据verifySuccess、error状态走对应业务分支即可

避坑提示 #

• 禁止在Firebase Functions生成验证操作码的逻辑中，调用applyActionCode做任何测试或预校验，会直接核销操作码导致前端拿到无效code
• 验证链接页面增加防重复点击逻辑，避免用户端短时间内重复触发接口调用
• Firebase验证操作码默认有效期为1小时，自定义邮件模板中建议提示用户在有效期内完成验证

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