Firebase Email + Phone Auth on Cloudflare Pages (MVP)

这是一个最小可行测试项目：

• 前端：原生 HTML + TypeScript
• 认证：Firebase Web SDK（邮箱密码 + 手机短信）
• 部署：Cloudflare Pages 静态站

1. Firebase 控制台准备

在 Firebase Console 中完成以下配置：

1. Authentication -> Sign-in method -> 启用 Phone 和 Email/Password。
2. Authentication -> Settings -> Authorized domains 添加：
   • localhost
   • 你的 Pages 域名（例如 your-project.pages.dev）
3. 建议先配置测试手机号（Authentication -> Sign-in method -> Phone -> Phone numbers for testing）。

2. 本地开发

pnpm install
pnpm build
pnpm preview

打开：http://127.0.0.1:8788

如需监听 TypeScript 变更：

pnpm dev

注意：pnpm dev 只监听 TS 构建；如修改 index.html 或 src/styles.css，请重新执行一次 pnpm build。

3. Cloudflare Pages 部署

方式 A：Pages 绑定 Git 仓库

1. 在 Cloudflare Pages 创建项目并连接仓库。
2. Build command 填：pnpm build
3. Build output directory 填：dist
4. 部署后，拿到 *.pages.dev 域名并回填到 Firebase Authorized domains。

方式 B：手动部署

pnpm build
pnpm wrangler pages deploy dist --project-name <你的-pages-项目名>

4. 使用流程

页面采用“邮箱登录 / 手机登录”两个标签页，不会同时展示两个表单。

4.1 邮箱登录（可选）

1. 输入邮箱与密码。
2. 点击“邮箱登录（不存在则创建）”。
3. 若邮箱账号存在则直接登录；不存在则自动创建并登录。

4.2 手机登录（可选）

1. 输入 E.164 手机号（例如 +8613800138000）。
2. 点击“发送验证码”。
   • 系统会自动进行人机验证（Invisible reCAPTCHA），通常无需手动点击。
3. 输入短信验证码后点击“确认登录”。
4. 页面结果区会显示登录成功后的 uid 和 phoneNumber。

5. 关于账户关联

本项目支持两种关联路径（都在前端实现）：

• 邮箱账号 -> 关联手机号：先邮箱登录，再走手机验证码流程，内部使用 linkWithPhoneNumber。
• 手机号账号 -> 关联邮箱：先手机号登录，再点邮箱登录按钮，内部使用 linkWithCredential。

在执行关联前，页面会显示当前账号的 provider 列表（例如：手机号、邮箱密码），便于确认当前绑定状态。

Firebase 默认规则：

• 首次某方式登录：创建新用户。
• 后续同方式登录：登录到原有 uid。
• 跨方式关联后：邮箱和手机号都会指向同一个 uid。

6. Cloudflare 是否需要数据库

在“只做登录认证”场景下，不需要在 Cloudflare 额外接数据库：

• 用户身份、手机号、邮箱、会话令牌由 Firebase Auth 管理。
• 静态前端部署在 Pages 即可。

建议在以下场景再引入数据库（如 D1 / Supabase / Firestore）：

• 需要保存业务资料（会员信息、订单、配置、审计日志）。
• 需要基于 uid 做业务数据读写。

7. 常见问题

1. reCAPTCHA key invalid：检查 Firebase 授权域名是否包含当前访问域名。

2. auth/invalid-phone-number：手机号格式必须是 E.164（以 + 开头）。

3. auth/too-many-requests：发送过于频繁，等待后重试。

4. 部分地区号码不可用：先用 Firebase 测试手机号排查流程问题。

5. auth/operation-not-allowed：通常是未启用对应登录方式。

   • 到 Firebase Console -> Authentication -> Sign-in method。
   • 确认 Phone 已启用。
   • 若当前代码使用邮箱+密码登录，请启用 Email/Password。
   • Email link (passwordless) 只有在你实现了邮件链接登录流程时才需要启用。
   • 如果刚启用，等待 1-2 分钟后刷新页面再试。

6. Email/Password 与 Email link (passwordless) 应该怎么选？

   • 你现在这版代码使用的是“邮箱+密码”模式，因此必须开启 Email/Password。
   • 这里的“密码”是该邮箱账号在 Firebase Auth 里的登录密码（用户可注册/设置），不是 Cloudflare 或 Google 控制台密码。
   • 如果你倾向无密码，我可以下一步把前端改成 sendSignInLinkToEmail 的免密邮件链接登录流程，再只保留 Email link (passwordless)。

---

已启用结算账号并完成 reCAPTCHA Enterprise 配置。