如何在 Next.js 中将 Prisma ORM 与 Clerk Auth 结合使用

25 分钟

引言

Clerk 是一个即插即用的身份验证提供商，它处理注册、登录、用户管理和 webhook，让您无需亲自处理这些繁琐的工作。

在本指南中，您将把 Clerk 集成到一个全新的 Next.js 应用中，将用户持久化到 Prisma Postgres 数据库，并提供一个简单的文章 API。您可以在 GitHub 上找到本指南的完整示例。

先决条件

1. 设置您的项目

创建应用

npx create-next-app@latest clerk-nextjs-prisma

它将提示您自定义设置。选择默认选项

信息

您想使用 TypeScript 吗？ 是
您想使用 ESLint 吗？ 是
您想使用 Tailwind CSS 吗？ 是
您想将代码放在 src/ 目录中吗？ 是
您想使用 App Router 吗？（推荐） 是
您想为 next dev 使用 Turbopack 吗？ 是
您想自定义导入别名吗？（默认是 @/*） 否

进入项目目录

cd clerk-nextjs-prisma

2. 设置 Clerk

2.1. 创建一个新的 Clerk 应用

前往 Clerk 的 New App 页面，创建一个新的应用。输入标题，选择您的登录选项，然后点击 Create Application。

信息

在本指南中，将使用 Google、Github 和电子邮件登录选项。

安装 Clerk Next.js SDK

npm install @clerk/nextjs

复制您的 Clerk 密钥，并将其粘贴到项目根目录下的 .env 文件中

.env

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<your-publishable-key>
CLERK_SECRET_KEY=<your-secret-key>

2.2. 使用 Clerk middleware 保护路由

clerkMiddleware 辅助函数启用身份验证，并在此处配置您的受保护路由。

在项目 /src 目录下创建一个 middleware.ts 文件

src/middleware.ts

import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    '/(api|trpc)(.*)',
  ],
};

2.3. 将 Clerk UI 添加到您的布局

接下来，您需要将您的应用包裹在 ClerkProvider 组件中，以使身份验证全局可用。

在您的 layout.tsx 文件中，添加 ClerkProvider 组件

src/app/layout.tsx

import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import { ClerkProvider } from "@clerk/nextjs";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
          {children}
        </body>
      </html>
    </ClerkProvider>
  );
}

创建一个 Navbar 组件，用于显示登录和注册按钮，以及用户登录后的用户按钮

src/app/layout.tsx

import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import {
  ClerkProvider,
  UserButton,
  SignInButton,
  SignUpButton,
  SignedOut,
  SignedIn,
} from "@clerk/nextjs";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider>
      <html lang="en">
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
          <Navbar />
          {children}
        </body>
      </html>
    </ClerkProvider>
  );
}

const Navbar = () => {
  return (
    <header className="flex justify-end items-center p-4 gap-4 h-16">
      <SignedOut>
        <SignInButton />
        <SignUpButton />
      </SignedOut>
      <SignedIn>
        <UserButton />
      </SignedIn>
    </header>
  );
};

3. 安装和配置 Prisma

3.1. 安装依赖

要开始使用 Prisma，您需要安装一些依赖项

Prisma Postgres（推荐）
其他数据库

npm install prisma --save-dev
npm install tsx --save-dev
npm install @prisma/extension-accelerate

npm install prisma --save-dev
npm install tsx --save-dev

安装完成后，在您的项目中初始化 Prisma

npx prisma init --db --output ../src/app/generated/prisma

信息

在设置 Prisma Postgres 数据库时，您需要回答几个问题。选择离您位置最近的区域，并为数据库选择一个容易记住的名称，例如“我的 Clerk NextJS 项目”

这将创建

一个 prisma/ 目录，其中包含一个 schema.prisma 文件
.env 文件中的 DATABASE_URL

3.2. 定义您的 Prisma Schema

在 prisma/schema.prisma 文件中，添加以下模型

prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
  output   = "../src/app/generated/prisma"
}

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

model User {
  id      Int     @id @default(autoincrement())
  clerkId String  @unique
  email   String  @unique
  name    String?
  posts   Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  Int
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
}

这将创建两个模型：User 和 Post，它们之间存在一对多关系。

现在，运行以下命令来创建数据库表并生成 Prisma Client

npx prisma migrate dev --name init

警告

建议您将 /src/app/generated/prisma 添加到您的 .gitignore 文件中。

3.3. 创建一个可复用的 Prisma Client

在 src/ 目录下，创建 /lib 目录并在其中创建一个 prisma.ts 文件

Prisma Postgres（推荐）
其他数据库

src/lib/prisma.ts

import { PrismaClient } from "@/app/generated/prisma";
import { withAccelerate } from "@prisma/extension-accelerate";

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};

const prisma =
  globalForPrisma.prisma || new PrismaClient().$extends(withAccelerate());

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

export default prisma;

src/lib/prisma.ts

import { PrismaClient } from "@/app/generated/prisma";

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};

const prisma = globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

export default prisma;

4. 将 Clerk 连接到数据库

4.1. 创建一个 Clerk webhook 端点

您将使用 Svix 来确保请求是安全的。Svix 会签署每个 webhook 请求，以便您可以验证其合法性，并确保在传输过程中未被篡改。

安装 svix 包

npm install svix

在 src/app/api/webhooks/clerk/route.ts 创建一个新的 API 路由

导入必要的依赖项