StartFast

文档

StartFast Pro

StartFast Pro 是一个高级的、生产就绪的 Next.js 15 样板工程，包含认证、支付、团队、国际化、分析、博客和整洁的 UI 系统 — 全部预配置完成。

本文档将帮助你快速上手并为你的 SaaS 产品定制 StartFast Pro。

你将获得

  • •Next.js 15 App Router，搭配 React 19 和服务端组件
  • •Better Auth 认证（邮箱、Google、GitHub OAuth）
  • •PostgreSQL 数据库搭配 Drizzle ORM
  • •Stripe 支付，支持订阅和 Webhooks
  • •通过 Resend 发送邮件
  • •next-intl 国际化支持（7 种语言）
  • •团队与 RBAC，含组织、角色和权限
  • •PostHog 分析集成
  • •博客系统，支持 Markdown、SEO 和阅读时间
  • •管理后台，管理用户、订单、分析和内容
  • •Playwright 端到端测试
  • •TypeScript 端到端类型安全

快速开始

1克隆仓库
git clone https://github.com/Harries/startfast-pro.git my-saas
2安装依赖
cd my-saas && npm install
3配置环境
cp .env.example .env.local
4设置数据库
npm run db:push
5启动开发
npm run dev

打开 http://localhost:3000

环境变量

将 .env.example 复制为 .env.local 并配置：

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_NAME=StartFast Pro

# Database (Postgres)
DATABASE_URL=postgresql://username:password@localhost:5432/startfast_pro

# Authentication (Better-Auth)
BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters
BETTER_AUTH_URL=http://localhost:3000

# Email (Resend)
RESEND_API_KEY=re_xxxxx
EMAIL_FROM=onboarding@yourdomain.com

# Stripe
STRIPE_SECRET_KEY=sk_test_xxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxx

# Optional: Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Optional: GitHub OAuth
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Analytics (PostHog)
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

# Default Locale
NEXT_PUBLIC_DEFAULT_LOCALE=en

数据库设置

StartFast Pro 使用 PostgreSQL 搭配 Drizzle ORM。我们推荐使用 Neon 作为无服务器 PostgreSQL。

  1. 1.创建 PostgreSQL 数据库（本地或 Neon）
  2. 2.在 .env.local 中设置 DATABASE_URL
  3. 3.运行 npm run db:push 将 schema 推送到数据库
  4. 4.使用 npm run db:studio 通过 Drizzle Studio 查看/编辑数据
  5. 5.使用 npm run db:generate 生成迁移文件

Schema: 数据库 schema 在 src/db/schema.ts 中使用 Drizzle 的 TypeScript 优先方式定义。DB 客户端从 src/db/index.ts 导出。

认证

StartFast Pro 使用 Better Auth 搭配 Drizzle 适配器进行认证。支持邮箱/密码和社交 OAuth。

  1. 1.设置 BETTER_AUTH_SECRET（至少 32 个字符）
  2. 2.将 BETTER_AUTH_URL 设置为你的应用 URL
  3. 3.（可选）配置 Google OAuth：GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET
  4. 4.（可选）配置 GitHub OAuth：GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET

Tip: 认证配置在 src/lib/auth.ts（服务端）和 src/lib/auth-client.ts（客户端）中。会话默认 7 天后过期。

Stripe 支付

StartFast Pro 支持 Stripe 订阅和 Webhook 处理。

  1. 1.从 Stripe Dashboard → API Keys 获取你的 API 密钥
  2. 2.设置 STRIPE_SECRET_KEY、NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  3. 3.在 https://your-domain.com/api/webhook/stripe 创建 Webhook 端点
  4. 4.将 Webhook 签名密钥复制到 STRIPE_WEBHOOK_SECRET

Tip: 本地测试请使用 stripe listen --forward-to localhost:3000/api/webhook/stripe

邮件配置

StartFast Pro 使用 Resend 发送事务邮件。

  1. 1.创建 Resend 账户
  2. 2.获取 API 密钥并设置 RESEND_API_KEY
  3. 3.将 EMAIL_FROM 设置为你已验证的发件人地址
RESEND_API_KEY=re_xxxxx
EMAIL_FROM=onboarding@yourdomain.com

国际化

StartFast Pro 通过 next-intl 提供多语言支持，内置 7 种语言。

  • • 英语 (en)
  • • 中文 (zh)
  • • 日语 (ja)
  • • 韩语 (ko)
  • • 德语 (de)
  • • 法语 (fr)
  • • 西班牙语 (es)

翻译文件位于 src/i18n/messages/。使用以下方式设置默认语言：

NEXT_PUBLIC_DEFAULT_LOCALE=en

分析

StartFast Pro 集成了 PostHog 产品分析。预置了注册、订阅、团队操作等事件追踪器。

  1. 1.创建 PostHog 账户
  2. 2.设置 NEXT_PUBLIC_POSTHOG_KEY 和 NEXT_PUBLIC_POSTHOG_HOST

Tip: 分析辅助函数在 src/lib/analytics.ts 中。使用 analytics.signUp()、analytics.subscriptionStarted() 等。

团队与角色

StartFast Pro 包含完整的组织和基于角色的访问控制（RBAC）系统。

角色

  • • 所有者 — 完全访问权限。可以转让所有权。
  • • 管理员 — 管理成员、设置和大部分资源。
  • • 成员 — 创建和编辑内容。有限的设置访问权限。
  • • 查看者 — 只读访问权限。

Tip: 权限定义在 src/lib/permissions.ts 中。使用 hasPermission(role, permission) 检查访问权限。

部署

几分钟内部署到 Vercel：

  1. 1.将代码推送到 GitHub
  2. 2.在 Vercel 上导入仓库
  3. 3.添加所有环境变量
  4. 4.部署！

Important: 部署后，请将 Stripe Webhook URL 更新为你的生产域名。

支持

需要帮助？联系我们：