如何在 Clerk Auth 和 Next.js 中使用 Prisma ORM

25 分钟

简介

Clerk 是一个即插即用的身份验证提供商，它处理注册、登录、用户管理和 webhook，让你无需费心。

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

先决条件

1. 设置你的项目

创建应用

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

它会提示你自定义设置。选择默认值即可

信息

你想使用 TypeScript 吗？ Yes
你想使用 ESLint 吗？ Yes
你想使用 Tailwind CSS 吗？ Yes
你想把代码放在 src/ 目录下吗？ Yes
你想使用 App Router 吗？ (推荐) Yes
你想在 next dev 中使用 Turbopack 吗？ Yes
你想自定义导入别名（默认为 @/*）吗？ No

导航到项目目录

cd clerk-nextjs-prisma

2. 设置 Clerk

2.1. 创建新的 Clerk 应用

登录到 Clerk 并导航到主页。在那里，点击 Create Application 按钮创建一个新应用。输入标题，选择登录选项，然后点击 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 中间件保护路由

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 项目”

这将创建

一个包含 schema.prisma 文件的 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 路由

导入必要的依赖项