Firebase actionCodeSettings原理及邮件验证、登录链接实现咨询

一、actionCodeSettings 核心配置逻辑 #

uri 配置 #

• uri 是用户点击邮件链接后的基础跳转目标，无论用户在网页、安卓还是iOS设备上打开邮件，Firebase都会基于这个地址处理跳转逻辑。
• 必须是Firebase控制台「认证 > 登录方法 > 授权域名」中已添加的域名，否则会被拦截。
• 示例：网页端用https://your-app.com/verify-email，APP端可使用自定义scheme（如yourapp://verify），但需提前在对应平台配置好跳转规则。

Android/iOS 专属配置 #

这部分用于让邮件链接直接唤起原生APP，而非打开网页：

• Android：需配置packageName（APP包名）、installApp（用户未安装APP时是否引导至应用商店）、minimumVersion（最低支持版本），同时要在Firebase控制台添加对应包名和SHA1指纹。
• iOS：配置bundleId（APP的Bundle ID），同样需在Firebase控制台完成iOS应用的配置。
• 若用户设备未安装对应APP，Firebase会自动 fallback 到uri指定的网页链接。

二、sendEmailVerification 实现示例（邮箱验证） #

在Verification.jsx中实现邮箱验证的发送与验证逻辑：

import { getAuth, sendEmailVerification, applyActionCode } from "firebase/auth";
import { useEffect, useState } from "react";

const Verification = () => {
  const auth = getAuth();
  const [email, setEmail] = useState("");
  const [isProcessing, setIsProcessing] = useState(false);

  // 配置 actionCodeSettings
  const actionCodeSettings = {
    uri: "https://your-app.com/verify-email",
    // Android 配置（可选，有原生APP时添加）
    android: {
      packageName: "com.yourapp.android",
      installApp: true,
      minimumVersion: "12"
    },
    // iOS 配置（可选，有原生APP时添加）
    iOS: {
      bundleId: "com.yourapp.ios"
    },
    handleCodeInApp: true
  };

  // 发送验证邮件
  const sendVerification = async () => {
    if (!email) return;
    setIsProcessing(true);
    try {
      const user = auth.currentUser;
      if (user) {
        await sendEmailVerification(user, { actionCodeSettings });
        alert("验证邮件已发送，请查收");
      } else {
        alert("请先登录或注册账号");
      }
    } catch (error) {
      console.error("发送验证邮件失败：", error);
      alert(`失败：${error.message}`);
    } finally {
      setIsProcessing(false);
    }
  };

  // 页面加载时自动检测验证链接并完成验证
  useEffect(() => {
    const urlParams = new URLSearchParams(window.location.search);
    const oobCode = urlParams.get("oobCode");
    if (oobCode) {
      setIsProcessing(true);
      applyActionCode(auth, oobCode)
        .then(() => {
          alert("邮箱验证成功！");
          window.location.href = "/";
        })
        .catch((error) => {
          console.error("验证失败：", error);
          alert(`验证失败：${error.message}`);
        })
        .finally(() => {
          setIsProcessing(false);
        });
    }
  }, [auth]);

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="输入邮箱"
      />
      <button onClick={sendVerification} disabled={isProcessing}>
        {isProcessing ? "发送中..." : "发送验证邮件"}
      </button>
    </div>
  );
};

export default Verification;

三、sendSignInLinkToEmail 实现示例（链接登录） #

该流程让用户输入邮箱后，通过点击邮件链接直接完成登录，无需密码：

import { getAuth, sendSignInLinkToEmail, isSignInWithEmailLink, signInWithEmailLink } from "firebase/auth";
import { useState, useEffect } from "react";

const Verification = () => {
  const auth = getAuth();
  const [email, setEmail] = useState("");
  const [isProcessing, setIsProcessing] = useState(false);

  // 配置 actionCodeSettings
  const actionCodeSettings = {
    uri: "https://your-app.com/sign-in-with-link",
    android: {
      packageName: "com.yourapp.android",
      installApp: true
    },
    iOS: {
      bundleId: "com.yourapp.ios"
    },
    handleCodeInApp: true,
    url: "https://your-app.com/sign-in-with-link"
  };

  // 发送登录链接邮件
  const sendSignInLink = async () => {
    if (!email) return;
    setIsProcessing(true);
    try {
      await sendSignInLinkToEmail(auth, email, actionCodeSettings);
      localStorage.setItem("loginEmail", email);
      alert("登录链接已发送，请查收");
    } catch (error) {
      console.error("发送登录链接失败：", error);
      alert(`失败：${error.message}`);
    } finally {
      setIsProcessing(false);
    }
  };

  // 页面加载时自动检测登录链接并完成登录
  useEffect(() => {
    if (isSignInWithEmailLink(auth, window.location.href)) {
      setIsProcessing(true);
      const storedEmail = localStorage.getItem("loginEmail");
      if (!storedEmail) {
        alert("请先输入邮箱获取登录链接");
        setIsProcessing(false);
        return;
      }
      signInWithEmailLink(auth, storedEmail, window.location.href)
        .then(() => {
          localStorage.removeItem("loginEmail");
          alert("登录成功！");
          window.location.href = "/dashboard";
        })
        .catch((error) => {
          console.error("登录失败：", error);
          alert(`登录失败：${error.message}`);
        })
        .finally(() => {
          setIsProcessing(false);
        });
    }
  }, [auth]);

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="输入邮箱获取登录链接"
      />
      <button onClick={sendSignInLink} disabled={isProcessing}>
        {isProcessing ? "发送中..." : "获取登录链接"}
      </button>
    </div>
  );
};

export default Verification;

四、第三方平台（Gmail/Facebook/Twitch）关联说明 #

第三方OAuth登录和actionCodeSettings、邮件验证是独立流程：

1. 先在Firebase控制台开启对应第三方登录方法，完成平台配置（如Facebook的App ID/Secret）。
2. 用户通过第三方登录后，Firebase会获取其邮箱信息。若需验证该邮箱，直接调用sendEmailVerification并传入配置好的actionCodeSettings即可，无需额外关联操作。
3. 第三方登录本身不依赖邮件链接，邮件验证仅用于确认邮箱有效性，增强账号安全性。

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