核心用法
stack-scaffold 是面向全栈开发者的项目初始化工具，通过结构化对话引导用户快速创建生产级 Next.js 应用。执行时强制遵循六步规划协议：需求确认→环境勘察→计划制定→风险识别→顺序执行→结果汇总，确保不覆盖现有项目或敏感凭证文件。
技术栈组合
- 前端：Next.js 15 App Router + TypeScript + Tailwind CSS
- 后端服务：Supabase（PostgreSQL + 实时订阅）+ Firebase Authentication
- 部署：Vercel + Cloudflare DNS，预置区域与缓存头配置
- 状态管理：Zustand 用户 store + next-themes 主题切换
- 测试：Vitest 单元测试 + Playwright E2E
生成产物
- 完整的
src/目录结构，含(auth)与(dashboard)路由组 - 双模式 Supabase 客户端（Browser/Server）+ SSR Cookie 刷新中间件
- Firebase Client SDK 与 Admin SDK 隔离配置
- 预置
.env.example、RLS 安全策略的profiles表迁移 vercel.json区域锁定、vitest.config.ts别名解析
显著优点
1. 安全设计先行：显式声明永不读取/修改 .env 或凭证文件，强制目标目录为空，规避凭据泄露与数据覆盖风险
2. SSR 认证最佳实践：通过 @supabase/ssr 实现服务端会话刷新，中间件自动同步 Cookie，避免客户端水合冲突
3. 双 Auth 架构灵活：Supabase 托管数据库 + Firebase Auth 身份验证，兼顾实时订阅能力与社交登录生态
4. 开发体验优化：Turbopack 本地启动、Prettier/ESLint 预设、类型生成脚本 types:supabase 一键同步数据库类型
潜在局限
- 技术锁定：深度绑定 Next.js App Router，迁移至 Remix/SvelteKit 需重构目录与 SSR 逻辑
- 环境变量复杂：同时管理 Supabase 3 项 + Firebase 9 项共 12 个环境变量，手动配置门槛较高
- Cloudflare 配置缺失：仅提供 DNS 建议，未自动化 R2 存储或 Workers 路由规则
- Firebase Admin 冷启动：服务端凭证初始化无连接池优化，高并发场景可能触发重复
initializeApp
适合人群
- 需快速启动 MVP 的独立开发者或小型团队
- 熟悉 React/TypeScript、希望避免重复配置样板代码的全栈工程师
- 采用 "Vercel + Supabase + Firebase" 标准架构的技术选型决策者
常规风险
| 风险点 | 说明 |
|--------|------|
| 环境变量泄露 | `FIREBASE_PRIVATE_KEY` 含换行符，若直接粘贴 JSON 未处理 `\\n` 转义会导致初始化失败 |
| RLS 策略遗漏 | 仅预置 `profiles` 表，后续新增表需手动补充 RLS，否则默认公开访问 |
| 中间件性能 | `middleware.ts` 对所有路由执行 `getUser()`，高流量站点应考虑匹配范围优化 |
| 依赖版本漂移 | `npx create-next-app@latest` 可能引入破坏性更新，建议锁定至具体版本号 |