Stack Scaffold

核心用法

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` 可能引入破坏性更新，建议锁定至具体版本号 |

核心用法

stack-scaffold 是一款面向现代全栈开发的项目脚手架工具，通过交互式对话引导用户快速生成完整的Next.js项目结构。使用时，开发者只需告知项目名称和目标目录，Skill便会自动执行六步规划协议：需求确认→环境勘测→执行计划→风险识别→顺序执行→结果汇总。生成的项目采用TypeScript + Tailwind CSS + ESLint标准化配置，内置App Router架构，可直接进入开发阶段。

生成内容涵盖完整的目录体系：前端页面路由（含认证页、仪表板）、API端点、可复用UI组件库、Supabase客户端/服务端双模式集成、Firebase Auth双SDK配置、Zustand状态管理、主题切换等现代前端工程必备模块。特别配置了Vercel部署适配和Cloudflare CDN支持，实现开发到部署的全链路覆盖。

显著优点

技术栈前瞻性强：深度整合2024-2025年主流全栈方案，Next.js App Router替代传统Pages Router，Supabase SSR模式解决服务端鉴权难题，Zustand替代Redux简化状态管理，技术选型紧跟社区演进方向。

工程化程度完善：开箱即含Vitest单元测试、Playwright E2E测试、Prettier代码格式化、类型生成脚本等DevOps工具链，.env.example文件规范敏感信息管理，Git提交信息遵循Conventional Commits规范。

安全设计内建：Row Level Security策略预配置、Firebase Admin SDK服务端隔离、middleware层鉴权刷新机制，降低新手开发者常见的安全疏漏风险。cookie处理采用try-catch容错设计，兼顾Server Component场景兼容性。

潜在局限

技术锁定效应明显：强制绑定特定技术组合（Supabase+Firebase+Vercel），若团队已有其他数据库或托管方案，需大量手动改造。双Auth方案（Supabase Auth+Firebase Auth）并存可能增加架构复杂度，实际项目中通常二选一即可。

环境配置门槛：要求用户预先注册并配置Supabase项目、Firebase项目、Vercel账号，生成后需手动填入十余项环境变量，对全栈新手存在上手障碍。regions固定配置为"gru1"（圣保罗），亚洲用户需手动调整。

维护可持续性：作者为T3级别个人开发者，无企业背书，长期更新承诺存疑。Next.js生态迭代极快（Turbopack尚在实验阶段），模板代码可能滞后于官方最佳实践。

适合人群

• 独立开发者/小团队：需要快速验证MVP，不愿重复配置技术栈
• 全栈学习进阶者：通过标准化代码理解现代前端工程架构
• 技术调研场景：对比App Router vs Pages Router、Supabase vs Firebase等方案的实际体验
• 外包项目交付：建立统一的项目基线，减少团队内代码风格差异

使用风险

依赖供应链风险：生成项目依赖30+个npm包，虽均来自官方registry，但仍需定期执行npm audit。特别值得关注的是Firebase Admin SDK的私钥文件（FIREBASE_PRIVATE_KEY）需正确处理换行符转义，配置不当将导致认证失败。

环境变量泄露风险：Skill明确禁止读取现有.env文件，但用户手动配置时易误将真实密钥提交至Git。建议配合git-secrets或GitHub Secret Scanning建立防护。

性能与兼容性风险：middleware对全路由匹配（除静态资源外），高并发场景可能成为瓶颈。Turbopack虽提升开发体验，但生产构建仍回退Webpack，需关注二者行为差异。

平台锁定成本：Vercel配置（vercel.json）和Cloudflare DNS暗示深度绑定边缘计算生态，迁移至AWS/Azure需重构部署配置。

测试覆盖率空白：生成的test:e2e脚本和Vitest配置为框架占位，实际测试用例需开发者自行补充，存在"有工具无实践"的形式化风险。