## 引言

本文以真实项目 CustomQR.pro（二维码生成 SaaS）为例，分享从本地开发到 Vercel 上线的完整流程，涵盖 **Next.js 16 + React 19** 项目搭建、**Prisma + PostgreSQL** 数据模型设计、**NextAuth** 认证、**Stripe** 订阅支付，以及 **Vercel** 部署与 Webhook 配置。所有代码均来自生产环境，可直接参考复用。

---

## 一、技术栈选型

| 层次 | 技术 | 说明 |
|------|------|------|
| 前端框架 | Next.js 16 + React 19 | App Router、RSC、流式渲染 |
| 样式 | Tailwind CSS | 快速构建响应式 UI |
| 数据库 ORM | Prisma 6 | 类型安全、迁移管理、多数据库支持 |
| 数据库 | PostgreSQL | 托管于 Vercel Postgres 或 Neon |
| 认证 | NextAuth v5 | OAuth、Session、JWT |
| 支付 | Stripe | 订阅、Checkout、Webhook |
| 部署 | Vercel | 自动 CI/CD、边缘函数、Serverless |

---

## 二、项目初始化与 Prisma 配置

### 2.1 初始化项目

```bash
npx create-next-app@latest my-saas --typescript --tailwind --app --src-dir=false
cd my-saas
npm install prisma @prisma/client
npx prisma init
```

### 2.2 Prisma Schema 设计

SaaS 常见核心表：用户、OAuth 账户、会话、订阅、业务数据。以下为精简后的 `prisma/schema.prisma` 示例：

```prisma
// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 用户表
model User {
  id            Int       @id @default(autoincrement())
  name          String?
  email         String?   @unique
  emailVerified DateTime?
  image         String?
  plan          Plan      @default(FREE)
  
  accounts      Account[]
  sessions      Session[]
  subscriptions UserSubscription[]
  
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  
  @@map("users")
}

enum Plan {
  FREE
  PRO
  ENTERPRISE
}

// OAuth 账户（NextAuth 需要）
model Account {
  id                Int     @id @default(autoincrement())
  userId            Int
  type              String
  provider          String
  providerAccountId String
  refresh_token     String? @db.Text
  access_token      String? @db.Text
  
  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
  @@unique([provider, providerAccountId])
  @@map("accounts")
}

// 会话（NextAuth 需要）
model Session {
  id           Int      @id @default(autoincrement())
  sessionToken String   @unique
  userId       Int
  expires      DateTime
  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  @@map("sessions")
}

// 订阅表（Stripe 集成）
model UserSubscription {
  id                     Int      @id @default(autoincrement())
  userId                 Int
  user                   User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  plan                   Plan     @default(FREE)
  status                 String   @default("ACTIVE")
  stripeCustomerId       String?  @unique
  stripeSubscriptionId   String?  @unique
  startDate              DateTime @default(now())
  expiresAt              DateTime?
  
  createdAt              DateTime @default(now())
  updatedAt              DateTime @updatedAt
  
  @@map("user_subscriptions")
  @@index([userId])
}
```

### 2.3 迁移与生成客户端

```bash
npx prisma migrate dev --name init
npx prisma generate
```

生产环境使用 `prisma migrate deploy` 执行迁移。

---

## 三、NextAuth 认证集成

### 3.1 安装依赖

```bash
npm install next-auth @auth/prisma-adapter
```

### 3.2 配置 Auth.js（NextAuth v5）

```typescript
// auth.ts
import NextAuth from "next-auth"
import Google from "next-auth/providers/google"
import { PrismaAdapter } from "@auth/prisma-adapter"
import { prisma } from "@/lib/prisma"

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async session({ session, user }) {
      if (session.user) {
        session.user.id = user.id
      }
      return session
    },
  },
  session: { strategy: "database", maxAge: 30 * 24 * 60 * 60 },
})
```

### 3.3 路由与中间件

```typescript
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth"
export const { GET, POST } = handlers
```

需要保护的路由在中间件中校验 session，或在服务端组件中调用 `auth()` 获取当前用户。

---

## 四、Stripe 订阅与 Webhook

### 4.1 创建 Checkout Session

用户点击「升级」时，调用 API 创建 Stripe Checkout 会话：

```typescript
// app/api/checkout/route.ts
import { auth } from "@/auth"
import Stripe from "stripe"
import { prisma } from "@/lib/prisma"

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2024-12-18.acacia" })

export async function POST(request: Request) {
  const session = await auth()
  if (!session?.user?.id) {
    return Response.json({ error: "请先登录" }, { status: 401 })
  }

  const { plan, billing } = await request.json()
  const userId = parseInt(session.user.id, 10)

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: "subscription",
    payment_method_types: ["card"],
    line_items: [{ price: PRICE_IDS[plan][billing], quantity: 1 }],
    metadata: { userId: userId.toString(), plan, billing },
    success_url: `${process.env.NEXTAUTH_URL}/dashboard?success=true`,
    cancel_url: `${process.env.NEXTAUTH_URL}/pricing?canceled=true`,
    subscription_data: {
      metadata: { userId: userId.toString(), plan, billing },
    },
  })

  return Response.json({ success: true, url: checkoutSession.url })
}
```

### 4.2 Webhook 同步订阅状态

Stripe 在支付完成、订阅变更等事件时向你的 Webhook 端点推送通知：

```typescript
// app/api/stripe/webhook/route.ts
import { headers } from "next/headers"
import Stripe from "stripe"
import { prisma } from "@/lib/prisma"

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2024-12-18.acacia" })
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(request: Request) {
  const body = await request.text()
  const signature = (await headers()).get("stripe-signature")
  if (!signature) return Response.json({ error: "Missing signature" }, { status: 400 })

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret)
  } catch (err) {
    return Response.json({ error: "Invalid signature" }, { status: 400 })
  }

  switch (event.type) {
    case "checkout.session.completed": {
      const session = event.data.object as Stripe.Checkout.Session
      const userId = parseInt(session.metadata?.userId ?? "0", 10)
      const subscriptionId = session.subscription as string
      const subscription = await stripe.subscriptions.retrieve(subscriptionId)

      await prisma.userSubscription.create({
        data: {
          userId,
          plan: session.metadata?.plan ?? "PRO",
          status: "ACTIVE",
          stripeCustomerId: session.customer as string,
          stripeSubscriptionId: subscription.id,
          expiresAt: new Date(subscription.current_period_end * 1000),
        },
      })
      break
    }
    case "customer.subscription.updated":
    case "customer.subscription.deleted": {
      const sub = event.data.object as Stripe.Subscription
      await prisma.userSubscription.updateMany({
        where: { stripeSubscriptionId: sub.id },
        data: {
          status: sub.status,
          expiresAt: sub.current_period_end ? new Date(sub.current_period_end * 1000) : null,
        },
      })
      break
    }
  }

  return Response.json({ received: true })
}
```

**重要**：Webhook 路由不要启用 NextAuth 的 body 解析，Stripe 需要原始 body 验证签名。在 Next.js 中可通过 `request.text()` 获取。

---

## 五、Vercel 部署流程

### 5.1 连接仓库

1. 将项目推送到 GitHub/GitLab
2. 登录 [Vercel](https://vercel.com)，导入项目，选择对应框架（Next.js 自动识别）

### 5.2 环境变量

在 Vercel 项目设置中配置：

| 变量名 | 说明 |
|--------|------|
| `DATABASE_URL` | PostgreSQL 连接串（Vercel Postgres / Neon / Supabase） |
| `NEXTAUTH_URL` | 生产域名，如 `https://yourdomain.com` |
| `NEXTAUTH_SECRET` | 随机密钥，用于加密 session |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Google OAuth |
| `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET` | Stripe 密钥与 Webhook 签名密钥 |

### 5.3 数据库

推荐使用 Vercel Postgres 或 [Neon](https://neon.tech)：

- 创建数据库后复制连接串到 `DATABASE_URL`
- 在 Vercel 部署前或首次部署后执行：`npx prisma migrate deploy`

### 5.4 Stripe Webhook

1. 在 Stripe Dashboard → Developers → Webhooks 添加端点
2. URL 填写：`https://yourdomain.com/api/stripe/webhook`
3. 选择事件：`checkout.session.completed`、`customer.subscription.updated`、`customer.subscription.deleted`
4. 将生成的 Webhook 签名密钥填入 `STRIPE_WEBHOOK_SECRET`

---

## 六、常见问题与最佳实践

### 6.1 Prisma 在 Serverless 中的连接

Vercel 为 Serverless，每次请求可能新建连接。建议使用连接池（如 `?pgbouncer=true`）或 Prisma 官方推荐的 `@prisma/extension-accelerate`（若有加速需求）。

### 6.2 Webhook 与 Body 解析冲突

若使用 Next.js 的 `bodyParser` 配置，需在 Webhook 路由中禁用：

```typescript
// 在 route.ts 中，确保使用 request.text() 获取原始 body
export const config = { api: { bodyParser: false } }
```

Next.js 13+ App Router 下默认不解析，直接 `request.text()` 即可。

### 6.3 开发环境测试 Webhook

使用 [Stripe CLI](https://stripe.com/docs/stripe-cli) 转发本地：

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

会输出临时 `STRIPE_WEBHOOK_SECRET`，用于本地 `.env.local`。

### 6.4 迁移与 Seed

- 生产：`npx prisma migrate deploy`
- 开发：`npx prisma migrate dev`
- 种子数据：`npx prisma db seed`（需在 `package.json` 中配置 `prisma.seed`）

---

## 七、小结

本文以 CustomQR.pro 的实践为基础，串联了 **Next.js + Prisma + NextAuth + Stripe + Vercel** 的 SaaS 上线路径：

1. **Prisma**：定义清晰的用户、会话、订阅模型，便于扩展
2. **NextAuth**：快速接入 OAuth，与 Prisma 适配器无缝配合
3. **Stripe**：通过 Checkout + Webhook 完成订阅与状态同步
4. **Vercel**：零配置部署，自动构建、边缘网络、环境变量管理

按上述步骤，即可将 Next.js 全栈项目从本地开发顺利推向生产环境。如有问题，欢迎在评论区交流。

---

**作者**：CustomQR.pro 团队  
**项目**：[CustomQR.pro](https://customqr.pro) - 在线二维码生成与定制工具  

本文以真实项目 CustomQR.pro（二维码生成 SaaS）为例，分享从本地开发到 Vercel 上线的完整流程，涵盖 Next.js 16 + React 19 项目搭建、Prisma + PostgreSQL 数据模型设计、NextAuth 认证、Stripe 订阅支付，以及 Vercel 部署与 Webhook 配置。所有代码均来自生产环境，可直接参考复用。

从 0 到上线：Next.js + Prisma + Vercel 的 SaaS 实战

云计算

前端

后端

本文详细讲解Next.js+Prisma+Stripe构建SaaS项目的全流程，包括技术栈选型、数据库设计、NextAuth认证集成、Stripe支付系统实现及Vercel部署。提供生产级代码示例，涵盖Prisma数据模型、NextAuth配置、Stripe订阅与Webhook处理等核心功能实现，帮助开发者快速搭建企业级SaaS应用。

PostgreSQL

中间件

数据库

路由

GitHub

OAuth

SaaS

2026新春采购季

tencentdb-catalog

postgres

serverless-catalog

message-queue-catalog

domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文详细讲解Next.js+Prisma+Stripe构建SaaS项目的全流程，包括技术栈选型、数据库设计、NextAuth认证集成、Stripe支付系统实现及Vercel部署。提供生产级代码示例，涵盖Prisma数据模型、NextAuth配置、Stripe订阅与Webhook处理等核心功能实现，帮助开发者快速搭建企业...

从 0 到上线：Next.js + Prisma + Vercel 的 SaaS 实战-腾讯云开发者社区-腾讯云

从 0 到上线：Next.js + Prisma + Vercel 的 SaaS 实战

从 0 到上线：Next.js + Prisma + Vercel 的 SaaS 实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐