核心用法
本技能专为 Next.js App Router 项目提供完整的 Firebase Authentication 工程化配置，采用"Firebase 鉴权 + Supabase 数据"的混合架构。用户通过 Google、Apple 或邮箱密码登录后，Firebase 签发 JWT ID Token，经 Next.js 中间件或 Server Component 通过 Firebase Admin SDK 验证，同时触发 API 路由将用户数据同步至 Supabase profiles 表，实现身份验证与业务数据的解耦。
配置流程遵循强制性的六步规划协议：需求分析 → 现有架构勘测 → 执行计划制定 → 风险识别与缓解 → 分步实施 → 结果汇总。技能会检测 src/lib/firebase/、src/hooks/use-auth.ts、src/middleware.ts 等关键路径，避免重复初始化或破坏性变更。
核心交付物包括：客户端 useAuth Hook（封装 Firebase 客户端 SDK）、AuthProvider Context 组件、服务端 Token 验证工具、Firebase-Supabase 用户同步 API 路由、登录页面模板，以及基于 Custom Claims 的角色权限系统（admin/editor/viewer）。
显著优点
- 架构清晰：鉴权与数据分离，Firebase 处理身份，Supabase 处理业务数据，通过 RLS 策略实现行级安全控制
- 多提供商支持：内置 Google、Apple、邮箱密码登录，可扩展至 GitHub、Twitter 等 OAuth 提供商
- 全栈类型安全：TypeScript 完整覆盖客户端 Hook、服务端验证、API 路由，减少运行时错误
- SSR 友好：服务端组件可直接验证 Firebase Token，支持 App Router 的 streaming 和 partial rendering
- 强制安全协议：规划阶段要求识别"中间件变更导致用户锁定"、"同步路由破坏用户映射"等风险并制定缓解措施
潜在缺点与局限性
- 供应商锁定：深度绑定 Firebase Authentication 生态，迁移成本较高
- 冷启动延迟：Firebase Admin SDK 初始化在部分 serverless 环境存在数百毫秒冷启动
- 实时同步复杂度：Firebase-Supabase 用户同步依赖自定义 API 路由，非原生集成，需自行处理失败重试
- Custom Claims 延迟：角色声明设置后需等待 JWT 刷新（最长 1 小时）或强制刷新令牌
- 环境变量管理繁琐：需同时配置 Firebase 客户端、Admin SDK、Supabase 三组凭证，易遗漏
适合人群
- 使用 Next.js App Router 的全栈开发者
- 需要快速搭建多社交登录的 SaaS 或消费级应用团队
- 希望利用 Supabase 实时数据库能力但偏好 Firebase Auth 成熟生态的架构师
- 具备 Firebase 控制台操作经验、理解 JWT 验证原理的中高级前端/全栈工程师
常规风险
| 风险类型 | 描述 | 缓解措施 |
|---------|------|---------|
| 配置泄露 | Firebase API Key 或 Admin 凭证提交至 Git | 强制使用 `.env.local`，技能包含环境变量检查清单 |
| 中间件误配 | Auth middleware 规则过严导致合法用户被拦截 | 规划协议要求评估现有路由影响，建议灰度发布 |
| 同步失败 | Firebase 用户创建但 Supabase 同步中断导致数据不一致 | API 路由包含错误处理，建议添加后台补偿任务 |
| Token 验证绕过 | 客户端直接访问 Supabase 绕过 Firebase 验证 | RLS 策略必须以 Firebase UID 为基准，技能提供标准模板 |
| 速率攻击 | 登录端点遭受暴力破解或滥用 | 需配合 Cloudflare Guard 等技能实施速率限制 |