方案简介

本方案是 Makerkit 开源的 Next.js Supabase SaaS Starter Kit（Lite 版），用于快速搭建 SaaS 应用的基础骨架。它将 Next.js 16.3（服务端渲染与静态站点生成的 React 框架）与 Supabase（实时数据库与认证）组合起来，通过 Turborepo 以 monorepo 形式组织代码，使用 Tailwind CSS v4 与 Shadcn UI（Base UI）构建界面，并内置 i18n、受保护路由、用户资料设置和 Playwright 基础测试。该套件是完整版的精简版本，适合评估代码架构与模式、构建基础 SaaS 原型、学习其技术栈方式，或直接作为自己项目的基础。整套方案可在本地通过 Docker 运行 Supabase，开箱即可在 http://localhost:3000 访问应用。

亮点与能力

• 🏗️ Next.js 16.3 + Turborepo monorepo 架构
• 🎨 Shadcn UI (Base UI) 组件 + Tailwind CSS v4
• 🔐 Supabase 认证与基础数据库
• 🌐 i18n 国际化翻译（客户端 + 服务端）
• ✨ TypeScript + Oxlint + Oxfmt 完整配置
• 👤 用户认证流程
• ⚙️ 用户资料与设置
• 📱 响应式营销页面
• 🔒 受保护路由
• 🎯 Playwright 基础测试配置

前置要求

• Node.js 18.x 或更高版本（最好是最新 LTS 版本）
• Docker
• PNPM

请确保机器上有 Docker daemon 在运行，这是 Supabase CLI 正常工作所必需的。

实施步骤

1. 克隆仓库

bash
git clone https://github.com/makerkit/next-supabase-saas-kit-lite.git

2. 安装依赖

bash
pnpm install

3. 启动 Supabase

请确保 Docker daemon 已运行，然后执行：

bash
pnpm run supabase:web:start

Supabase 服务器启动后，可通过输出中的端口访问 Supabase Dashboard，通常在 http://localhost:54323。终端会打印所有 Supabase 服务信息。

4. 启动 Next.js 应用

bash
pnpm run dev

应用将在 http://localhost:3000 可用。

5. 代码健康检查

格式化代码：

bash
pnpm run format:fix

执行 lint：

bash
pnpm run lint

校验 TypeScript：

bash
pnpm run typecheck

使用与配置要点

通过 .env.local 文件设置环境变量来配置应用，可用变量包括：

• NEXT_PUBLIC_SITE_URL：SaaS 应用 URL，默认 http://localhost:3000
• NEXT_PUBLIC_PRODUCT_NAME：产品名称，默认 Makerkit
• NEXT_PUBLIC_SITE_TITLE：站点标题
• NEXT_PUBLIC_SITE_DESCRIPTION：站点描述
• NEXT_PUBLIC_DEFAULT_THEME_MODE：默认主题模式，默认 light
• NEXT_PUBLIC_THEME_COLOR / NEXT_PUBLIC_THEME_COLOR_DARK：主题颜色
• NEXT_PUBLIC_SUPABASE_URL：Supabase 项目 URL，默认 http://127.0.0.1:54321
• NEXT_PUBLIC_SUPABASE_ANON_KEY：Supabase anon key
• SUPABASE_SERVICE_ROLE_KEY：Supabase service role key

数据库迁移相关命令：

bash

Create new migration

pnpm --filter web supabase migration new

Link to Supabase project

pnpm --filter web supabase link

Push migrations

pnpm --filter web supabase db push

Turborepo 会缓存 lint/format/typecheck 结果，可反复运行而无需担心性能影响。

注意事项与常见问题

• 本套件文档仍在更新中，后续会补充更多细节。
• Lite 版是完整版的精简版本，完整版才包含计费订阅系统、团队账户、邮件模板、分析（GA、Posthog、Umami 等）、监控（Sentry、Baselime 等）、生产级数据库 schema、完整测试套件、实时通知、博客/文档系统、超级管理员面板等生产功能。
• 停止 Supabase：pnpm run supabase:web:stop；重置 Supabase：pnpm run supabase:web:reset。
• 更多 Supabase 命令参见 Supabase CLI 文档。

优缺点

• ✓ 生产级架构决策与严格 TypeScrip
• ✓ 本地 Docker 一键启动 Supab
• ✕ 文档仍在更新中
• ✕ Lite 版无计费订阅等功能

出处

本方案挖掘自开源项目 makerkit/nextjs-saas-starter-kit-lite，方案内容与实施命令均来自其 README 原文。