快速开始

5分钟内让您的 AI SaaS Template 项目启动并运行！本指南将引导您完成从安装到运行第一个 AI SaaS 应用程序的完整设置过程。

🚀 概览

完成本指南后，您将拥有：

✅ 在本地运行的完全功能的 AI SaaS 应用程序
✅ 基于 Clerk 的身份认证系统
✅ tRPC + Drizzle ORM + PostgreSQL 数据库
✅ Stripe 支付系统集成
✅ AI 服务接口（OpenAI/Anthropic/Google/XAI）
✅ 多语言支持（中英文）

📋 前置要求

开始之前，请确保您的系统已安装以下软件：

必需软件

Node.js 18+ - 下载 Node.js
pnpm - 包管理器 (npm install -g pnpm)
PostgreSQL - 数据库托管商 (Neon, Supabase) 或本地数据库服务器
Git - 版本控制系统 (下载 Git)

第三方服务账户（获得完整功能）

Clerk 账户 - 用于身份认证 (注册)
Stripe 账户 - 用于支付处理 (注册)
AI API 密钥 - OpenAI/Anthropic/Google AI/XAI 中至少一个
Upstash Redis - 用于缓存和限流 (注册)
邮件服务 - Resend 或 SMTP 服务器

⚡ 5分钟设置

步骤 1：克隆仓库

# 克隆仓库
git clone https://github.com/geallenboy/ai-saas-template
cd ai-saas-template

# 或使用 GitHub CLI
gh repo clone geallenboy/ai-saas-template
cd ai-saas-template

步骤 2：安装依赖

# 安装所有依赖
pnpm install

# 这将安装：
# - Next.js 15 和 React 19
# - TypeScript 和所有类型定义
# - Tailwind CSS v4 和 Radix UI 组件
# - tRPC 和 TanStack Query
# - Drizzle ORM 和 PostgreSQL 支持
# - Vitest 和 Playwright 测试框架
# - 以及所有其他项目依赖

步骤 3：环境配置

# 复制环境变量模板
cp env.example .env

# 在编辑器中打开 .env 文件
code .env  # VS Code
# 或
vim .env  # 终端编辑器

配置基本的环境变量：

# 应用配置
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

# 数据库（必需）
DATABASE_URL="postgresql://username:password@localhost:5432/ai_saas_template"

# Clerk 认证（必需）
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_your_key_here"
CLERK_SECRET_KEY="sk_test_your_secret_here"

# Stripe 支付（必需）
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_stripe_key"
STRIPE_SECRET_KEY="sk_test_your_stripe_secret"
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret"

步骤 4：数据库设置

推荐使用 Neon 或 Supabase 等云数据库服务：

使用 Neon:

登录 Neon，创建新项目
在项目面板点击 "Connect"，复制数据库 URL
将 URL 添加到 .env 文件

# 数据库配置
DATABASE_URL="postgresql://username:[email protected]/ai_saas_template?sslmode=require"

# 推送数据库架构
pnpm db:push

# 这将：
# - 创建所有必要的表（users, payments, system_configs 等）
# - 设置表关系和索引
# - 初始化数据库结构

步骤 5：启动开发服务器

# 启动开发服务器
pnpm dev

# 应用程序将在以下地址可用：
# http://localhost:3000

🎉 恭喜！ 您的 AI SaaS Template 应用程序现在正在运行！

🔧 完整配置

为了获得完整功能，请配置这些额外的服务：

AI 服务配置

选择一个或多个 AI 服务提供商：

# AI 服务 API 密钥（至少需要一个）
OPENAI_API_KEY="sk-your-openai-key"              # OpenAI GPT 模型
ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"     # Claude 模型
GOOGLE_GENERATIVE_AI_API_KEY="your-google-key"    # Gemini 模型
XAI_API_KEY="xai-your-xai-key"                    # Grok 模型

# 启用 AI 功能
ENABLE_AI_FEATURES="true"
NEXT_PUBLIC_ENABLE_AI_FEATURES="true"

支付集成（Stripe）

在 stripe.com 创建 Stripe 账户
从 Stripe 仪表板获取您的 API 密钥
配置环境变量（已在基本配置中包含）
在您的 Stripe 仪表板中创建产品和价格
为支付事件设置 webhook 端点

缓存服务（Upstash Redis）

用于提高性能和限流：

在 upstash.com 创建账户
创建 Redis 数据库
添加到 .env 文件：

# Upstash Redis 配置
UPSTASH_REDIS_REST_URL="https://your-database.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-redis-token"

邮件服务配置

用于发送通知邮件：

使用 Resend（推荐）:

# Resend 配置
RESEND_API_KEY="re_your_resend_api_key"

或使用 SMTP:

# SMTP 配置
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USERNAME="[email protected]"
SMTP_PASSWORD="your-app-password"

社交登录（Clerk 中配置）

Clerk 支持多种登录方式，在 Clerk Dashboard 中配置：

GitHub OAuth
Google OAuth
Discord, Twitter 等其他平台
邮箱/密码登录
手机号登录

🎯 探索您的应用程序

1. 身份认证系统

访问 http://localhost:3000/auth/sign-in 进行测试：

✅ 邮箱/密码登录 - 使用 Clerk 认证系统
✅ 社交登录 - 在 Clerk Dashboard 中配置 GitHub/Google 等
✅ 密码重置 - Clerk 自动处理密码重置流程
✅ 用户注册 - 访问 /auth/sign-up 创建账户

2. 仪表板功能

在 http://localhost:3000/dashboard 访问仪表板：

✅ 用户仪表板 - 个人用户界面和设置
✅ AI 对话 - 体验 AI 功能和智能对话
✅ 管理员仪表板 - 访问 /admin 进行管理
✅ 用户管理 - 管理员可管理所有用户

3. 支付系统

在 http://localhost:3000/pricing 测试支付流程：

✅ 订阅计划 - 查看可用的定价计划
✅ 支付处理 - 使用 Stripe 测试卡进行测试
✅ 账单管理 - 管理订阅和发票
✅ 客户门户 - 自助服务账单门户

4. 文件管理

在 http://localhost:3000/dashboard/files 尝试文件操作：

✅ 文件上传 - 拖放文件上传
✅ 图像处理 - 自动缩略图生成
✅ 文件组织 - 组织和管理文件
✅ 访问控制 - 文件权限和共享

5. 国际化

测试语言切换：

✅ 语言切换 - 在中文和英文之间切换
✅ 本地化内容 - 所有 UI 文本都已翻译
✅ 本地化路由 - URL 根据语言变化
✅ 日期/货币格式 - 正确的本地化格式

🛠️ 开发命令

以下是开发的基本命令：

开发服务器

# 启动带热重载的开发服务器
pnpm dev

# 使用特定端口启动
pnpm dev -- --port 3001

# 使用 turbo 模式启动（更快的构建）
pnpm dev --turbo

数据库操作

# 将架构更改推送到数据库
pnpm db:push

# 生成数据库迁移
pnpm db:generate

# 运行数据库迁移
pnpm db:migrate

# 打开数据库工作室（GUI）
pnpm db:studio

代码质量

# 运行 TypeScript 类型检查
pnpm type-check

# 运行 Biome 代码检查
pnpm lint:check

# 自动修复代码格式问题
pnpm lint

# 运行代码格式化
pnpm format

测试

# 运行所有测试
pnpm test

# 仅运行单元测试
pnpm test:unit

# 运行集成测试
pnpm test:integration

# 运行 E2E 测试 (Playwright)
pnpm test:e2e

# 运行带覆盖率的测试
pnpm test:coverage

# 开启测试 UI 界面
pnpm test:ui

构建和生产

# 为生产构建
pnpm build

# 启动生产服务器
pnpm start

# 构建并启动（组合）
pnpm preview

🔍 验证清单

验证您的设置是否正常工作：

✅ 基本功能

应用程序在 http://localhost:3000 加载
浏览器开发者工具中没有控制台错误
数据库连接正常工作
环境变量正确加载

✅ 身份认证

用户注册正常工作
邮箱/密码登录正常工作
社交登录正常工作（如果已配置）
受保护的路由重定向到登录页面
用户会话正确持久化

✅ 数据库

数据库表已创建
用户数据正确存储
数据库工作室无错误打开
迁移成功运行

✅ 文件系统

文件上传正常工作
图像处理正确
文件存储在配置位置
文件权限正常工作

✅ 支付系统（如果已配置）

Stripe 集成正常工作
测试支付正确处理
Webhook 端点接收事件
订阅管理正常工作

🚨 常见问题与解决方案

环境变量未加载

问题： 环境变量未定义

# 确保 .env 文件在根目录
ls -la .env

# 检查文件权限
chmod 644 .env

# 重启开发服务器
pnpm dev

端口已被占用

问题： 端口 3000 已被占用

# 查找并终止使用端口 3000 的进程
lsof -ti:3000 | xargs kill -9

# 或使用不同端口
pnpm dev -- --port 3001

Node.js 版本问题

问题： 不支持的 Node.js 版本

# 检查您的 Node.js 版本
node --version

# 更新到 Node.js 18+
nvm install 18
nvm use 18

📚 下一步

现在您的应用程序正在运行，接下来要做的是：

1. 探索功能

阅读项目架构章节了解系统设计
查看项目特色章节获取详细的功能说明

2. 自定义您的应用程序

按照自定义配置章节使其成为您自己的
更新品牌、颜色和内容以匹配您的需求

3. 添加您的内容

用您自己的内容替换占位符内容
配置您的定价计划和功能
设置您的域名和品牌

4. 部署到生产环境

按照代码部署章节进行生产设置
配置生产环境变量
设置监控和分析

🎉 您准备好了！

恭喜！您现在拥有一个在本地运行的完全功能的 SaaS 应用程序。构建下一个伟大产品的基础已经奠定。

需要帮助？ 扫码添加作者微信，邀请你进入专属答疑微信群，获取配套的视频教程和实战项目代码。

5分钟内让您的 AI SaaS Template 项目启动并运行！本指南将引导您完成从安装到运行第一个 AI SaaS 应用程序的完整设置过程。

🚀 概览

完成本指南后，您将拥有：

✅ 在本地运行的完全功能的 AI SaaS 应用程序
✅ 基于 Clerk 的身份认证系统
✅ tRPC + Drizzle ORM + PostgreSQL 数据库
✅ Stripe 支付系统集成
✅ AI 服务接口（OpenAI/Anthropic/Google/XAI）
✅ 多语言支持（中英文）

📋 前置要求

开始之前，请确保您的系统已安装以下软件：

必需软件

Node.js 18+ - 下载 Node.js
pnpm - 包管理器 (npm install -g pnpm)
PostgreSQL - 数据库托管商 (Neon, Supabase) 或本地数据库服务器
Git - 版本控制系统 (下载 Git)

第三方服务账户（获得完整功能）

Clerk 账户 - 用于身份认证 (注册)
Stripe 账户 - 用于支付处理 (注册)
AI API 密钥 - OpenAI/Anthropic/Google AI/XAI 中至少一个
Upstash Redis - 用于缓存和限流 (注册)
邮件服务 - Resend 或 SMTP 服务器

⚡ 5分钟设置

步骤 1：克隆仓库

# 克隆仓库
git clone https://github.com/geallenboy/ai-saas-template
cd ai-saas-template

# 或使用 GitHub CLI
gh repo clone geallenboy/ai-saas-template
cd ai-saas-template

步骤 2：安装依赖

# 安装所有依赖
pnpm install

# 这将安装：
# - Next.js 15 和 React 19
# - TypeScript 和所有类型定义
# - Tailwind CSS v4 和 Radix UI 组件
# - tRPC 和 TanStack Query
# - Drizzle ORM 和 PostgreSQL 支持
# - Vitest 和 Playwright 测试框架
# - 以及所有其他项目依赖

步骤 3：环境配置

# 复制环境变量模板
cp env.example .env

# 在编辑器中打开 .env 文件
code .env  # VS Code
# 或
vim .env  # 终端编辑器

配置基本的环境变量：

# 应用配置
NEXT_PUBLIC_SITE_URL="http://localhost:3000"

# 数据库（必需）
DATABASE_URL="postgresql://username:password@localhost:5432/ai_saas_template"

# Clerk 认证（必需）
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_your_key_here"
CLERK_SECRET_KEY="sk_test_your_secret_here"

# Stripe 支付（必需）
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_stripe_key"
STRIPE_SECRET_KEY="sk_test_your_stripe_secret"
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret"

步骤 4：数据库设置

推荐使用 Neon 或 Supabase 等云数据库服务：

使用 Neon:

登录 Neon，创建新项目
在项目面板点击 "Connect"，复制数据库 URL
将 URL 添加到 .env 文件

# 数据库配置
DATABASE_URL="postgresql://username:[email protected]/ai_saas_template?sslmode=require"

# 推送数据库架构
pnpm db:push

# 这将：
# - 创建所有必要的表（users, payments, system_configs 等）
# - 设置表关系和索引
# - 初始化数据库结构

步骤 5：启动开发服务器

# 启动开发服务器
pnpm dev

# 应用程序将在以下地址可用：
# http://localhost:3000

🎉 恭喜！ 您的 AI SaaS Template 应用程序现在正在运行！

🔧 完整配置

为了获得完整功能，请配置这些额外的服务：

AI 服务配置

选择一个或多个 AI 服务提供商：

# AI 服务 API 密钥（至少需要一个）
OPENAI_API_KEY="sk-your-openai-key"              # OpenAI GPT 模型
ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"     # Claude 模型
GOOGLE_GENERATIVE_AI_API_KEY="your-google-key"    # Gemini 模型
XAI_API_KEY="xai-your-xai-key"                    # Grok 模型

# 启用 AI 功能
ENABLE_AI_FEATURES="true"
NEXT_PUBLIC_ENABLE_AI_FEATURES="true"

支付集成（Stripe）

在 stripe.com 创建 Stripe 账户
从 Stripe 仪表板获取您的 API 密钥
配置环境变量（已在基本配置中包含）
在您的 Stripe 仪表板中创建产品和价格
为支付事件设置 webhook 端点

缓存服务（Upstash Redis）

用于提高性能和限流：

在 upstash.com 创建账户
创建 Redis 数据库
添加到 .env 文件：

# Upstash Redis 配置
UPSTASH_REDIS_REST_URL="https://your-database.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-redis-token"

邮件服务配置

用于发送通知邮件：

使用 Resend（推荐）:

# Resend 配置
RESEND_API_KEY="re_your_resend_api_key"

或使用 SMTP:

# SMTP 配置
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USERNAME="[email protected]"
SMTP_PASSWORD="your-app-password"

社交登录（Clerk 中配置）

Clerk 支持多种登录方式，在 Clerk Dashboard 中配置：

GitHub OAuth
Google OAuth
Discord, Twitter 等其他平台
邮箱/密码登录
手机号登录

🎯 探索您的应用程序

1. 身份认证系统

访问 http://localhost:3000/auth/sign-in 进行测试：

✅ 邮箱/密码登录 - 使用 Clerk 认证系统
✅ 社交登录 - 在 Clerk Dashboard 中配置 GitHub/Google 等
✅ 密码重置 - Clerk 自动处理密码重置流程
✅ 用户注册 - 访问 /auth/sign-up 创建账户

2. 仪表板功能

在 http://localhost:3000/dashboard 访问仪表板：

✅ 用户仪表板 - 个人用户界面和设置
✅ AI 对话 - 体验 AI 功能和智能对话
✅ 管理员仪表板 - 访问 /admin 进行管理
✅ 用户管理 - 管理员可管理所有用户

3. 支付系统

在 http://localhost:3000/pricing 测试支付流程：

✅ 订阅计划 - 查看可用的定价计划
✅ 支付处理 - 使用 Stripe 测试卡进行测试
✅ 账单管理 - 管理订阅和发票
✅ 客户门户 - 自助服务账单门户

4. 文件管理

在 http://localhost:3000/dashboard/files 尝试文件操作：

✅ 文件上传 - 拖放文件上传
✅ 图像处理 - 自动缩略图生成
✅ 文件组织 - 组织和管理文件
✅ 访问控制 - 文件权限和共享

5. 国际化

测试语言切换：

✅ 语言切换 - 在中文和英文之间切换
✅ 本地化内容 - 所有 UI 文本都已翻译
✅ 本地化路由 - URL 根据语言变化
✅ 日期/货币格式 - 正确的本地化格式

🛠️ 开发命令

以下是开发的基本命令：

开发服务器

# 启动带热重载的开发服务器
pnpm dev

# 使用特定端口启动
pnpm dev -- --port 3001

# 使用 turbo 模式启动（更快的构建）
pnpm dev --turbo

数据库操作

# 将架构更改推送到数据库
pnpm db:push

# 生成数据库迁移
pnpm db:generate

# 运行数据库迁移
pnpm db:migrate

# 打开数据库工作室（GUI）
pnpm db:studio

代码质量

# 运行 TypeScript 类型检查
pnpm type-check

# 运行 Biome 代码检查
pnpm lint:check

# 自动修复代码格式问题
pnpm lint

# 运行代码格式化
pnpm format

测试

# 运行所有测试
pnpm test

# 仅运行单元测试
pnpm test:unit

# 运行集成测试
pnpm test:integration

# 运行 E2E 测试 (Playwright)
pnpm test:e2e

# 运行带覆盖率的测试
pnpm test:coverage

# 开启测试 UI 界面
pnpm test:ui

构建和生产

# 为生产构建
pnpm build

# 启动生产服务器
pnpm start

# 构建并启动（组合）
pnpm preview

🔍 验证清单

验证您的设置是否正常工作：

✅ 基本功能

应用程序在 http://localhost:3000 加载
浏览器开发者工具中没有控制台错误
数据库连接正常工作
环境变量正确加载

✅ 身份认证

用户注册正常工作
邮箱/密码登录正常工作
社交登录正常工作（如果已配置）
受保护的路由重定向到登录页面
用户会话正确持久化

✅ 数据库

数据库表已创建
用户数据正确存储
数据库工作室无错误打开
迁移成功运行

✅ 文件系统

文件上传正常工作
图像处理正确
文件存储在配置位置
文件权限正常工作

✅ 支付系统（如果已配置）

Stripe 集成正常工作
测试支付正确处理
Webhook 端点接收事件
订阅管理正常工作

🚨 常见问题与解决方案

环境变量未加载

问题： 环境变量未定义

# 确保 .env 文件在根目录
ls -la .env

# 检查文件权限
chmod 644 .env

# 重启开发服务器
pnpm dev

端口已被占用

问题： 端口 3000 已被占用

# 查找并终止使用端口 3000 的进程
lsof -ti:3000 | xargs kill -9

# 或使用不同端口
pnpm dev -- --port 3001

Node.js 版本问题

问题： 不支持的 Node.js 版本

# 检查您的 Node.js 版本
node --version

# 更新到 Node.js 18+
nvm install 18
nvm use 18

📚 下一步

现在您的应用程序正在运行，接下来要做的是：

1. 探索功能

阅读项目架构章节了解系统设计
查看项目特色章节获取详细的功能说明

2. 自定义您的应用程序

按照自定义配置章节使其成为您自己的
更新品牌、颜色和内容以匹配您的需求

3. 添加您的内容

用您自己的内容替换占位符内容
配置您的定价计划和功能
设置您的域名和品牌

4. 部署到生产环境

按照代码部署章节进行生产设置
配置生产环境变量
设置监控和分析

🎉 您准备好了！

恭喜！您现在拥有一个在本地运行的完全功能的 SaaS 应用程序。构建下一个伟大产品的基础已经奠定。

需要帮助？ 扫码添加作者微信，邀请你进入专属答疑微信群，获取配套的视频教程和实战项目代码。

快速开始

On this page

快速开始

On this page