Firebase 邮箱链接登录（Email Link Auth）在本地开发时失败，常因控制台中未配置正确的自定义操作 URL 所致；即使 actionCodeSettings 中设置了 localhost，实际邮件中的链接仍由 Firebase 控制台模板决定，需手动修改认证模板中的「Customise Action URL」。
firebase 邮箱链接登录（email link auth）在本地开发时失败，常因控制台中未配置正确的自定义操作 url 所致；即使 actioncodesettings 中设置了 localhost，实际邮件中的链接仍由 firebase 控制台模板决定，需手动修改认证模板中的「customise action url」。
Firebase 的邮箱链接认证机制分为两层 URL 配置：
-
客户端代码中的
actionCodeSettings.url：仅作为重定向目标（即用户点击邮件链接后、完成验证跳转的页面），用于接收和处理 Firebase 生成的一次性代码； -
控制台中模板配置的「Customise Action URL」：这才是真正嵌入到发送邮件中的链接域名，Firebase 后端据此生成动态链接（如
https://your-project.page.link/...），并强制校验该域名是否在「Authorized domains」列表中。
关键误区在于：许多开发者误以为设置 dynamicLinkDomain: 'localhost' 或 url: 'http://localhost:5173/' 就足以让邮件链接指向本地，但 Firebase 不支持将 localhost 作为动态链接主域名（dynamicLinkDomain） —— 这是平台限制（官方文档明确说明），且 dynamicLinkDomain 字段仅在启用 Firebase Dynamic Links 且需自定义子域时才有效，本地开发应完全忽略此字段。
✅ 正确做法如下：
-
移除
dynamicLinkDomain字段（避免误导与报错）； - 确保
actionCodeSettings.url指向你本地应用的有效路径（如'http://localhost:5173/finishSignIn'），该路径需能接收oobCode、mode等查询参数； -
最重要一步：登录 Firebase Console → 进入你的项目 → Authentication → Templates → Email link → Edit template → Customise Action URL → 将其改为你的本地地址，例如：
http://localhost:5173/finishSignIn
✅ 该 URL 必须以
http://或https://开头，且对应域名（localhost）已添加至 Authentication → Settings → Authorized domains（默认已包含）； - 保存模板并重新触发
sendSignInLinkToEmail()。
示例修正后的代码：
const actionCodeSettings = {
url: 'http://localhost:5173/finishSignIn', // ✅ 本地回调页，需能处理 oobCode
handleCodeInApp: true, // ✅ 必须为 true，否则会跳转到 Firebase 默认页
// ❌ 删除 dynamicLinkDomain: 'localhost' —— 无效且引发 invalid-dynamic-link-domain 错误
};
sendSignInLinkToEmail(auth, email, actionCodeSettings)
.then(() => {
window.localStorage.setItem('emailForSignIn', email);
})
.catch((error) => {
console.error('Email link send failed:', error.code, error.message);
// 常见错误码：auth/invalid-dynamic-link-domain → 表明控制台模板 URL 未配置或域名未授权
});
⚠️ 注意事项：
- 修改模板后，新发送的邮件才会生效，已发出的链接无法更新；
- 若使用 HTTPS 本地服务（如 Vite + HTTPS），请确保浏览器信任证书，且
url使用https://localhost:...； - 生产环境务必切换为真实域名（如
https://app.yoursite.com），并在控制台同步更新； -
handleCodeInApp: true是必须项，它告诉 Firebase 在应用内处理链接（而非跳转到浏览器外），这对单页应用（SPA）至关重要。
总结：Firebase 邮箱链接的“源头域名”由控制台模板唯一决定，actionCodeSettings 仅影响后续重定向逻辑。本地开发只需专注配置控制台模板 URL + 授权 localhost，即可安全、可靠地完成全流程测试。
