跳至主要内容

使用 Nuxt Prisma 模块

Nuxt Prisma 模块简化了将 Prisma ORM 集成到您的 Nuxt 应用中的过程。

Prisma ORM 是一个数据库库,它允许您建模数据库架构,提供自动生成的迁移,并允许您以直观且类型安全的方式查询数据库。

此模块提供了多个功能来简化在 Nuxt 应用中设置和使用 Prisma ORM 的过程,从而更容易与您的数据库进行交互。

功能

  • 项目初始化:在您的 Nuxt 项目中自动设置一个带有 SQLite 数据库的 Prisma ORM 项目。
  • 可组合:提供一个自动导入的 usePrismaClient() 可组合函数,可在您的 Vue 文件中使用。
  • API 路由集成:自动导入 PrismaClient 的实例,以便在 API 路由中用于查询您的数据库。
  • Prisma Studio 访问:通过 Nuxt Devtools 启用对 Prisma Studio 的访问,以便查看和手动编辑数据。

入门

  1. 创建一个新的 Nuxt 项目

    npx nuxi@latest init test-nuxt-app
  2. 导航到项目目录并使用 Nuxt CLI 安装 @prisma/nuxt

    cd test-nuxt-app
    npx nuxi@latest module add @prisma/nuxt

    警告

    如果您正在使用 pnpm,请确保提升 Prisma 依赖项。请按照此处的步骤获取详细说明。

  3. 启动开发服务器

    npm run dev

    启动开发服务器将

    1. 自动安装Prisma CLI
    2. 使用 SQLite 初始化一个 Prisma 项目
    3. 在 Prisma 架构文件中创建 UserPost 示例模型
      prisma/schema.prisma
       // This is your Prisma schema file,
      // learn more about it in the docs: https://pris.ly/d/prisma-schema

      generator client {
      provider = "prisma-client-js"
      }

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

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

      model Post {
      id Int @id @default(autoincrement())
      title String
      content String?
      published Boolean @default(false)
      author User @relation(fields: [authorId], references: [id])
      authorId Int
      }
    4. 提示您使用Prisma Migrate运行迁移以创建数据库表
      注意

      如果不存在 migrations 文件夹,则模块在您第一次启动时会自动迁移数据库。之后,您需要在 CLI 中手动运行 npx prisma migrate dev 以应用任何架构更改。手动运行 npx prisma migrate dev 命令可以更容易、更安全地管理迁移,并可以解决任何与迁移相关的错误。

    5. 安装并生成一个Prisma Client,它使您能够查询您的数据库
    6. 提示您启动Prisma Studio
  4. 您现在可以在您的项目中使用 Prisma ORM。如果您接受了添加 Prisma Studio 的提示,则可以通过 Nuxt Devtools 访问 Prisma Studio。请参阅使用部分,了解如何在您的应用中使用 Prisma Client。

使用不同的数据库提供程序

@prisma/nuxt 模块可与Prisma ORM 支持的任何数据库提供程序一起使用。您可以配置入门示例以使用您选择的数据库。对于没有现有数据的数据库具有预先存在的数据的数据库,步骤会有所不同。

使用没有现有数据的数据库

要配置入门示例以使用没有任何现有数据的 PostgreSQL 数据库

  1. 停止 Nuxt 开发服务器和 Prisma Studio(如果它们仍在运行)
    npx kill-port 3000  # Stops Nuxt dev server (default port)
    npx kill-port 5555 # Stops Prisma Studio (default port)
  2. 导航到 schema.prisma 文件并更新 datasource 块以指定 postgresql 提供程序
    prisma/schema.prisma
    // This is your Prisma schema file,
    // learn more about it in the docs: https://pris.ly/d/prisma-schema

    generator client {
    provider = "prisma-client-js"
    }

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

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

    model Post {
    id Int @id @default(autoincrement())
    title String
    content String?
    published Boolean @default(false)
    author User @relation(fields: [authorId], references: [id])
    authorId Int
    }
  3. 使用您的 PostgreSQL 数据库 URL 更新 .env 文件中的 DATABASE_URL 环境变量
    .env
    ## This is a sample database URL, please use a valid URL
    DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
  4. 删除 SQLite 数据库文件和迁移文件夹
    rm prisma/dev.db # Delete SQLite database file
    rm -r prisma/migrations # Delete the pre-existing migrations folder
  5. 运行开发服务器
    npm run dev
    启动开发服务器将提示您将架构更改迁移到数据库,您应该同意。然后同意安装并从 Nuxt Devtools 访问 Prisma Studio 的提示。
  6. @prisma/nuxt 模块已准备好与您的 PostgreSQL 数据库一起使用。请参阅使用部分,了解如何在您的应用中使用 Prisma Client。

使用具有预先存在数据的数据库

要配置入门示例以使用已存在数据的 PostgreSQL 数据库

  1. 停止开发服务器和 Prisma Studio(如果它们仍在运行)
    // stops Nuxt dev server from running incase it's still running
    npx kill-port 3000
    // stops Prisma Studio instance incase it's still running
    npx kill-port 5555
  2. 删除 Prisma 文件夹
    rm -r prisma/
  3. 使用您的 PostgreSQL 数据库 URL 更新 .env 文件中的 DATABASE_URL 环境变量
    .env
    ## This is a sample database URL, please use a valid URL
    DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
  4. 要从现有数据库生成 Prisma 架构和迁移文件夹,您必须内省数据库。完成内省指南中的**步骤 1**到**步骤 4**,然后继续。
  5. 启动开发服务器将跳过将架构更改迁移到数据库的提示,因为迁移文件夹已存在。同意安装并从 Nuxt Devtools 访问 Prisma Studio 的提示。
  6. @prisma/nuxt 模块已准备好与您的 PostgreSQL 数据库一起使用。请参阅使用部分,了解如何在您的应用中使用 Prisma Client。

用法

选项 A:usePrismaClient 可组合函数

在您的 Nuxt 服务器组件中使用可组合函数

如果您正在使用Nuxt 服务器组件,则可以在您的 .server.vue 文件中使用 Prisma Client 的全局实例

<script setup>
const prisma = usePrismaClient()
const user = await prisma.user.findFirst()
</script>

<template>
<p>{{ user.name }}</p>
</template>

在您的 API 路由中使用自动导入的 Prisma Client 实例

您可以按如下方式在您的 Nuxt API 路由中使用自动导入的 Prisma Client 实例 prisma

export default defineEventHandler(async (event) => {
return {
user: await prisma.user.findFirst(),
};
});

选项 B:lib/prisma.ts

完成初始设置提示后,此模块将创建 lib/prisma.ts 文件,其中包含 Prisma Client 的全局实例。

lib/prisma.ts
import { PrismaClient } from '@prisma/client'

const prismaClientSingleton = () => {
return new PrismaClient()
}

declare const globalThis: {
prismaGlobal: ReturnType<typeof prismaClientSingleton>;
} & typeof global;

const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()

export default prisma

if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma

您可以通过在 lib/prisma.ts 文件中使用客户端扩展来自定义 Prisma Client 的功能。以下是在 lib/prisma.ts 文件中使用Pulse 客户端扩展的一个示例

lib/prisma.ts
import { PrismaClient } from '@prisma/client'
import { withPulse } from '@prisma/extension-pulse'

const prismaClientSingleton = () => {
return new PrismaClient().$extends(withPulse({
apiKey: process.env.PULSE_API_KEY
}))
}

declare const globalThis: {
prismaGlobal: ReturnType<typeof prismaClientSingleton>;
} & typeof global;

const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()

export default prisma

if (process.env.NODE_ENV !== 'production') globalThis.prismaGlobal = prisma

信息

如果您想利用使用Prisma Client 扩展的客户端,请使用lib文件夹中的prisma实例。

在您的 API 路由中使用全局 Prisma Client 实例

您可以在您的 Nuxt API 路由中按如下方式使用 Prisma Client 的全局实例

import prisma from "~/lib/prisma";

export default defineEventHandler(async (event) => {
return {
user: await prisma.user.findFirst(),
};
});

在您的 Nuxt 服务器组件中使用全局 Prisma Client 实例

如果您正在使用Nuxt 服务器组件,则可以在.server.vue文件中使用 Prisma Client 的全局实例。

<script setup>
import prisma from '~/lib/prisma';
const user = await prisma.user.findFirst()
</script>

<template>
<p>{{ user.name }}</p>
</template>

配置

您可以通过在nuxt.config.ts中使用prisma键来配置@prisma/nuxt模块。

nuxt.config.ts
export default defineNuxtConfig({
// ...
prisma: {
// Options
}
})

注意

在通过运行npm run dev成功设置模块后,prisma键在nuxt.config.ts中可用。

选项类型默认值描述
installCLI布尔值true是否安装Prisma CLI
installClient布尔值true是否在项目中安装Prisma Client库。
generateClient布尔值true是否生成PrismaClient实例。在每次运行时执行npx prisma generate以根据模式更改更新客户端。
formatSchema布尔值true是否格式化Prisma 模式文件。
installStudio布尔值true是否在 Nuxt Devtools 中安装并启动Prisma Studio
autoSetupPrisma布尔值false是否跳过设置期间的所有提示。此选项对于在脚本或 CI/CD 管道中自动化 Prisma 设置很有用。

限制

PrismaClient构造函数选项在usePrismaClient组合式中不可配置

usePrismaClient模块目前不允许配置PrismaClient构造函数选项

usePrismaClient组合式在边缘运行时不受支持

usePrismaClient组合式目前依赖于在边缘运行时无法使用的PrismaClient实例。如果您需要组合式的边缘支持,请在DiscordGitHub上告知我们。

故障排除

使用pnpm时 Prisma Studio 无法打开

如果您在使用pnpm时遇到以下错误并且 Prisma Studio 无法打开

Uncaught SyntaxError: The requested module '/_nuxt/node_modules/.pnpm/*@*/node_modules/@prisma/client/index-browser.js?v=' does not provide an export named 'PrismaClient' (at plugin.mjs?v=*)

要解决此问题,请在您的项目根目录中创建一个.npmrc文件,并添加以下配置以提升 Prisma 依赖项

.npmrc
hoist-pattern[]=*prisma*

这将确保pnpm正确解析 Prisma 依赖项。

解决TypeError: Failed to resolve module specifier ".prisma/client/index-browser"

如果您在构建和预览应用程序后在浏览器控制台中遇到以下错误消息

TypeError: Failed to resolve module specifier ".prisma/client/index-browser" 

要解决此问题,请将以下配置添加到您的nuxt.config.ts文件中

nuxt.config.ts
import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
modules: [
'@prisma/nuxt',
],
// additional config
vite: {
resolve: {
alias: {
'.prisma/client/index-browser': './node_modules/.prisma/client/index-browser.js',
},
},
},
})

此配置确保模块说明符正确映射到相应的文件。