用 Next.js 快速搭建带 Stripe 支付订阅与用户看板的 SaaS 应用

方案简介

Next.js SaaS Starter 是 Next.js 官方提供的 SaaS 应用启动模板。它以 Next.js 为核心框架，组合 Postgres 数据库、Drizzle ORM、Stripe 支付与 shadcn/ui 组件库，开箱即用地解决了 SaaS 产品起步阶段最常见的三件事：用户认证、付费订阅和登录后仪表盘。

模板包含带动画 Terminal 元素的营销落地页、对接 Stripe Checkout 的定价页、支持用户/团队增删改查的 Dashboard 页面，以及基于 Owner 和 Member 角色的基础 RBAC。认证采用邮箱/密码方式，JWT 存储在 Cookie 中，并通过全局中间件保护登录路由。

该模板定位是「intentionally minimal and to be used as a learning resource」，即刻意保持精简、用作学习资源。适合希望快速了解如何把 Next.js、Stripe、Postgres 等组合成完整 SaaS 的开发者，也可作为自建 SaaS 产品的起步骨架。

亮点与能力

• 带动画 Terminal 元素的营销落地页（/）
• 连接 Stripe Checkout 的定价页（/pricing）
• Dashboard 页面支持用户/团队的增删改查（CRUD）
• 基于 Owner 和 Member 角色的基础 RBAC 权限控制
• 通过 Stripe Customer Portal 管理订阅
• 邮箱/密码认证，JWT 存储到 Cookie
• 全局中间件保护登录路由
• 本地中间件保护 Server Actions 或校验 Zod schemas
• 针对任意用户事件的 Activity 日志系统

组成与分工

• Next.js：核心框架，承载页面、API 路由（如 /api/stripe/webhook）与 Server Actions
• Postgres：数据库，存储用户、团队、订阅等数据
• Drizzle：ORM，负责数据库迁移与数据访问
• Stripe：支付服务，提供 Checkout 结账、Customer Portal 订阅管理与 Webhook 事件通知
• shadcn/ui：UI 组件库，用于构建界面
• Vercel：生产部署平台，通过连接 GitHub 仓库完成部署并配置环境变量
• Stripe CLI：本地开发时登录 Stripe 账号并转发 webhook 事件

前置要求

• Node.js 环境与 pnpm 包管理器
• Postgres 数据库
• Stripe 账号，并安装 Stripe CLI

克隆仓库并安装依赖：

bash
git clone https://github.com/nextjs/saas-starter
cd saas-starter
pnpm install

实施步骤

1. 登录 Stripe

安装并登录 Stripe CLI：

bash
stripe login

2. 生成环境变量

使用内置 setup 脚本创建 .env 文件：

bash
pnpm db:setup

3. 迁移并填充数据库

bash
pnpm db:migrate
pnpm db:seed

这一步会创建默认用户和团队：User 为 test@test.com，Password 为 admin123。也可以通过 /sign-up 路由创建新用户。

4. 启动开发服务器

bash
pnpm dev

打开 http://localhost:3000 即可看到应用运行。

5. 本地监听 Stripe webhook

通过 Stripe CLI 在本地监听订阅变更事件：

bash
stripe listen --forward-to localhost:3000/api/stripe/webhook

使用与配置要点

测试支付

使用以下测试卡信息验证 Stripe 支付流程：

• Card Number: 4242 4242 4242 4242
• Expiration: 任意未来日期
• CVC: 任意 3 位数字

验证运行成功

启动 pnpm dev 后在浏览器打开 http://localhost:3000 看到应用页面即说明启动成功；访问定价页可体验 Stripe Checkout 流程。

生产部署要点

1. 在 Stripe Dashboard 为生产环境创建 webhook，endpoint 设为生产 API 路由（如 https://yourdomain.com/api/stripe/webhook），并选择要监听的事件（如 checkout.session.completed、customer.subscription.updated）。
2. 将代码推送到 GitHub 仓库，连接 Vercel 部署。
3. 在 Vercel 项目设置中配置生产环境变量，包括 BASE_URL（生产域名）、STRIPE_SECRET_KEY（生产密钥）、STRIPE_WEBHOOK_SECRET（生产 webhook 密钥）、POSTGRES_URL（生产数据库 URL）、AUTH_SECRET（可用 openssl rand -base64 32 生成的随机字符串）。

注意事项与常见问题

• 该模板刻意保持精简（intentionally minimal），定位为学习资源，功能不追求完备；社区有更多全功能的付费版本（如 achromatic.dev、shipfa.st、makerkit.dev、zerotoshipped.com、turbostarter.dev）。
• 本地开发订阅变更事件依赖 Stripe CLI 的 webhook 转发，需保持 stripe listen 运行。
• 生产环境务必使用独立的 Stripe webhook 与密钥（STRIPE_WEBHOOK_SECRET、STRIPE_SECRET_KEY），不要沿用测试配置。

优缺点

• ✓ 覆盖认证、支付、看板完整链路
• ✓ 本地可跑通 Stripe webhook
• ✕ 刻意精简，功能有限
• ✕ 社区付费版功能更全

出处

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