核心用法
本 Skill 提供 Firebase Authentication 在 Next.js App Router 项目中的全栈配置指南，采用 Firebase 认证 + Supabase 数据存储的混合架构。主要组件包括：
1. 客户端认证层：useAuth Hook 封装 Google、Apple、邮箱三种登录方式，管理认证状态与错误处理
2. Context 提供者：AuthProvider 组件实现全局认证状态共享
3. 服务端验证：verifyFirebaseToken 函数用于中间件和 API 路由的令牌校验
4. 用户同步机制：/api/auth/sync 端点将 Firebase 用户数据同步至 Supabase profiles 表
5. 权限控制：Custom Claims 实现 admin/editor/viewer 角色分级
显著优点
- 强制安全协议：执行前必须完成六步规划流程，主动识别锁用户、断同步等风险
- 混合架构清晰：Firebase 处理认证（成熟、多提供商），Supabase 处理数据（Postgres + RLS），职责分离明确
- 端到端类型安全：完整的 TypeScript 类型覆盖，从客户端 Hook 到服务端验证
- 生产级细节：包含令牌刷新、错误边界、授权域配置、CORS 检查等易被忽视的环节
潜在缺点与局限
- 环境依赖复杂：需同时配置 Firebase Console、Supabase Dashboard、Next.js 环境变量三重入口
- 同步延迟风险：Firebase→Supabase 的异步同步在极端情况下可能出现数据不一致窗口
- Custom Claims 延迟：角色更新后需强制刷新令牌才能生效（通常 < 1 小时），不适合实时权限变更场景
- 供应商锁定：深度绑定 Firebase 生态，迁移成本较高
适合人群
- 使用 Next.js App Router 的全栈开发者
- 需要快速集成 Google/Apple 社交登录的 SaaS 项目
- 已有 Supabase 基础设施，希望复用其数据层与 RLS 能力的团队
- 对安全有基础认知、能理解 JWT 验证流程的中高级开发者
常规风险
| 风险场景 | 缓解措施 |
|---------|---------|
| 中间件修改导致全站锁死 | 分步执行、单文件验证、保留回滚路径 |
| SUPABASE_SERVICE_ROLE_KEY 泄露 | 仅用于服务端，禁止暴露至客户端 |
| Firebase 配置错误导致登录失败 | 强制提醒用户完成 Console 手动配置 |
| 未 rate limiting 的同步端点被刷 | 需配合 Cloudflare Guard 等技能使用 |
与其他方案对比
| 维度 | 本方案 | NextAuth.js + Prisma |
|-----|--------|----------------------|
| 社交登录配置 | 控制台点选即生效 | 需手动配置 OAuth Provider |
| 服务端无状态验证 | ✅ 直接验签 | 需查库验 session |
| 实时数据库 | 需额外集成 | Supabase Realtime 原生支持 |
| 学习曲线 | 需理解 Firebase 生态 | 更贴近 Next.js 原生模式 |