使用 Nuxt Prisma 模块
Nuxt Prisma 模块简化了将 Prisma ORM 集成到您的 Nuxt 应用中的过程。
Prisma ORM 是一个数据库库,让您可以建模数据库 schema,提供自动生成的迁移,并以直观且类型安全的方式查询数据库。
该模块提供了多种功能,以简化在 Nuxt 应用中设置和使用 Prisma ORM,使与数据库交互更加轻松。
特性
- 项目初始化:在您的 Nuxt 项目中自动设置一个包含 SQLite 数据库的 Prisma ORM 项目。
- 可组合函数:提供一个自动导入的
usePrismaClient()
可组合函数,可在您的 Vue 文件中使用。 - API 路由集成:自动导入
PrismaClient
实例,可在 API 路由中使用以查询您的数据库。 - Prisma Studio 访问:通过 Nuxt Devtools 启用对 Prisma Studio 的访问,用于查看和手动编辑数据。
开始
-
创建一个 新的 Nuxt 项目
npm create nuxt test-nuxt-app
-
导航到项目目录并使用 Nuxt CLI 安装
@prisma/nuxt
cd test-nuxt-app
npx nuxi@latest module add @prisma/nuxt
警告如果您使用
pnpm
,请确保提升 Prisma 依赖。按照 Prisma studio 步骤获取详细说明。 -
启动开发服务器
npm run dev
启动开发服务器将
- 自动安装 Prisma CLI
- 初始化一个包含 SQLite 的 Prisma 项目
- 在 Prisma Schema 文件中创建
User
和Post
示例模型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
} - 提示您运行迁移以使用 Prisma Migrate 创建数据库表注意
如果不存在
migrations
文件夹,模块第一次启动时会自动进行数据库迁移。之后,您需要手动在 CLI 中运行npx prisma migrate dev
来应用任何 schema 更改。手动运行npx prisma migrate dev
命令可以更轻松、更安全地管理迁移,并帮助您 排查 任何与迁移相关的错误。 - 安装并生成一个 Prisma Client,使您能够查询数据库
- 自动启动 Prisma Studio
-
您现在可以在项目中使用 Prisma ORM 了。如果您接受了添加 Prisma Studio 的提示,则可以通过 Nuxt Devtools 访问 Prisma Studio。请参阅 usage 部分了解如何在应用中使用 Prisma Client。
使用不同的数据库提供者
@prisma/nuxt
模块适用于 Prisma ORM 支持 的任何数据库提供者。您可以配置 getting started 示例以使用您选择的数据库。对于 没有现有数据 的数据库和 包含现有数据 的数据库,步骤会有所不同。
使用没有现有数据的数据库
配置 getting started 示例以使用没有现有数据的 PostgreSQL 数据库
- 停止 Nuxt 开发服务器和 Prisma Studio(如果它们仍在运行)
npx kill-port 3000 # Stops Nuxt dev server (default port)
npx kill-port 5555 # Stops Prisma Studio (default port) - 导航到
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
} - 更新
.env
文件中的DATABASE_URL
环境变量,将其设置为您的 PostgreSQL 数据库 URL.env## This is a sample database URL, please use a valid URL
DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample" - 删除 SQLite 数据库文件和 migrations 文件夹
rm prisma/dev.db # Delete SQLite database file
rm -r prisma/migrations # Delete the pre-existing migrations folder - 运行开发服务器
启动开发服务器将提示您将 schema 更改迁移到数据库,您应该同意。然后同意安装并从 Nuxt Devtools 访问 Prisma Studio 的提示。
npm run dev
@prisma/nuxt
模块已准备好与您的 PostgreSQL 数据库一起使用。请参阅 usage 部分了解如何在应用中使用 Prisma Client。
使用包含现有数据的数据库
配置 getting started 示例以使用已包含数据的 PostgreSQL 数据库
- 停止开发服务器和 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 - 删除 Prisma 文件夹
rm -r prisma/
- 更新
.env
文件中的DATABASE_URL
环境变量,将其设置为您的 PostgreSQL 数据库 URL.env## This is a sample database URL, please use a valid URL
DATABASE_URL="postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample" - 要从现有数据库生成 Prisma Schema 和 migrations 文件夹,您必须 对数据库进行自省。完成 introspection guide 中的 步骤 1 到 步骤 4,然后继续。
- 启动开发服务器将跳过将 schema 更改迁移到数据库的提示,因为 migrations 文件夹已存在。同意安装并从 Nuxt Devtools 访问 Prisma Studio 的提示。
@prisma/nuxt
模块已准备好与您的 PostgreSQL 数据库一起使用。请参阅 usage 部分了解如何在应用中使用 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>
选项 B: lib/prisma.ts
运行完初始设置提示后,此模块将创建 lib/prisma.ts
文件,其中包含 Prisma Client 的全局实例。
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 的功能。这是一个使用 Accelerate 客户端扩展 的示例
import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'
const prismaClientSingleton = () => {
return new PrismaClient().$extends(withAccelerate())
}
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
模块
export default defineNuxtConfig({
// ...
prisma: {
// Options
}
})
在成功运行 npm run dev
设置模块后,prisma
键可在 nuxt.config.ts
中使用
选项 | 类型 | 默认值 | 描述 |
---|---|---|---|
installCLI | boolean | true | 是否安装 Prisma CLI。 |
installClient | boolean | true | 是否在项目中安装 Prisma Client 库。 |
generateClient | boolean | true | 是否 生成 PrismaClient 实例。每次运行时执行 npx prisma generate 以根据 schema 更改更新客户端。 |
formatSchema | boolean | true | 是否 格式化 Prisma Schema 文件。 |
installStudio | boolean | true | 是否在 Nuxt Devtools 中安装并启动 Prisma Studio。 |
autoSetupPrisma | boolean | false | 设置过程中是否跳过所有提示。此选项对于在脚本或 CI/CD 管道中自动化 Prisma 设置非常有用。 |
skipPrompts | false | false | 跳过所有提示 |
prismaRoot | string | false | 使用 Nuxt layers 时必需。例如,如果您有一个名为 database 的 Nuxt 层,则在基础 nuxt config 中 prismaRoot 将是 ./database 。这指的是 Prisma 将被初始化或检查的文件夹。 |
prismaSchemaPath | string | undefined | 使用 Nuxt layers 时必需。例如,如果您有一个名为 database 的 Nuxt 层,则在基础 nuxt config 中 prismaSchemaPath 将是 ./database/prisma/schema.prisma 。 |
runMigration | boolean | true | 是否自动运行 Prisma Migration。如果您使用 MongoDB 或 PlanetScale,请使用 npx prisma db push 命令。这些数据库不支持迁移,因此此命令将确保您的 schema 得到适当更新。 |
限制
PrismaClient
构造函数选项在 usePrismaClient
可组合函数中不可配置
usePrismaClient
模块目前不允许配置 PrismaClient
构造函数选项。
usePrismaClient
可组合函数在边缘运行时中不受支持
usePrismaClient
可组合函数目前依赖于一个 PrismaClient
实例,该实例在边缘运行时中不起作用。如果您需要可组合函数的边缘支持,请通过 Discord 或 GitHub 告知我们。
问题排查
使用 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 依赖
hoist-pattern[]=*prisma*
这将确保 Prisma 依赖能够被 pnpm
正确解析。
解决 TypeError: Failed to resolve module specifier ".prisma/client/index-browser"
错误
如果在构建和预览您的应用后,在浏览器控制台中遇到以下错误消息
TypeError: Failed to resolve module specifier ".prisma/client/index-browser"
要解决此问题,请将以下配置添加到您的 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',
},
},
},
})
此配置确保模块说明符正确映射到相应的文件。
包管理器支持的限制
该模块设计用于与流行的包管理器一起工作,包括 npm、Yarn 和 pnpm。然而,截至 v0.2
版本,由于一个会导致无限安装循环的问题,它与 Bun 并不完全兼容。
此外,此包尚未在 Deno 上测试,因此不被官方 支持。
与 Prisma 保持联系
通过以下方式继续您的 Prisma 之旅: 我们活跃的社区。保持信息畅通,积极参与,并与其他开发者协作
- 在 X 上关注我们 获取公告、直播活动和实用技巧。
- 加入我们的 Discord 提问、与社区交流,并通过对话获得积极支持。
- 在 YouTube 上订阅 获取教程、演示和直播。
- 在 GitHub 上参与 通过标星仓库、报告问题或贡献解决问题。