使用 Nuxt Prisma 模块
Nuxt Prisma 模块简化了将 Prisma ORM 集成到你的 Nuxt 应用中的过程。
Prisma ORM 是一个数据库库,允许你对数据库模式进行建模,提供自动生成的迁移,并让你以直观且类型安全的方式查询数据库。
此模块提供了多项功能,以简化在 Nuxt 应用中设置和使用 Prisma ORM 的过程,从而更容易与你的数据库进行交互。
功能
- 项目初始化: 在你的 Nuxt 项目中自动设置一个带有 SQLite 数据库的 Prisma ORM 项目。
- Composable: 提供一个自动导入的
usePrismaClient()
composable,用于你的 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
以应用任何模式更改。手动运行npx prisma migrate dev
命令可以更轻松和安全地管理迁移,并排查任何与迁移相关的错误。 - 安装并生成一个 Prisma Client,使你能够查询你的数据库
- 自动启动 Prisma Studio
-
你现在可以在你的项目中使用 Prisma ORM 了。如果你接受了添加 Prisma Studio 的提示,你可以通过 Nuxt Devtools 访问 Prisma Studio。请参阅使用方法章节以了解如何在你的应用中使用 Prisma Client。
使用不同的数据库提供商
@prisma/nuxt
模块可以与 Prisma ORM 支持的任何数据库提供商一起使用。你可以配置入门示例以使用你选择的数据库。对于没有现有数据的数据库和具有预先存在数据的数据库,步骤会有所不同。
使用没有现有数据的数据库
要配置 入门示例 以使用没有现有数据的 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
} - 使用你的 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" - 删除 SQLite 数据库文件和 migrations 文件夹
rm prisma/dev.db # Delete SQLite database file
rm -r prisma/migrations # Delete the pre-existing migrations folder - 运行开发服务器
启动开发服务器将提示你将模式更改迁移到数据库,你应该同意。然后同意提示以安装并从 Nuxt Devtools 访问 Prisma Studio。
npm run dev
@prisma/nuxt
模块已准备好与你的 PostgreSQL 数据库一起使用。请参阅使用方法章节以了解如何在你的应用中使用 Prisma Client。
使用具有预先存在数据的数据库
要配置 入门示例 以使用已包含数据的 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/
- 使用你的 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" - 要从现有数据库生成 Prisma Schema 和 migrations 文件夹,你必须内省数据库。完成内省指南中的步骤 1 到 步骤 4 并继续。
- 启动开发服务器将跳过提示将模式更改迁移到数据库,因为 migrations 文件夹已存在。同意提示以安装并从 Nuxt Devtools 访问 Prisma Studio。
@prisma/nuxt
模块已准备好与你的 PostgreSQL 数据库一起使用。请参阅使用方法章节以了解如何在你的应用中使用 Prisma Client。
使用方法
选项 A:usePrismaClient
composable
在你的 Nuxt 服务端组件中使用 composable
如果你正在使用 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 ,以根据模式更改更新客户端。 |
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 layer,则 prismaRoot 在基本 nuxt 配置中将为 ./database 。这指的是 Prisma 将被初始化或检查的文件夹。 |
prismaSchemaPath | string | undefined | 使用 Nuxt layers 时是必需的。例如,如果你有一个名为 database 的 Nuxt layer,则 prismaSchemaPath 在基本 nuxt 配置中将为 ./database/prisma/schema.prisma 。 |
runMigration | boolean | true | 是否自动运行 Prisma Migration。如果你正在使用 MongoDB 或 PlanetScale,请使用 npx prisma db push 命令。迁移不受这些数据库的支持,因此此命令将确保你的模式得到适当的更新。 |
限制
PrismaClient
构造函数选项在 usePrismaClient
composable 中不可配置
usePrismaClient
模块当前不允许配置 PrismaClient
构造函数选项。
usePrismaClient
composable 在边缘运行时中不受支持
usePrismaClient
composable 当前依赖于在边缘运行时中不起作用的 PrismaClient
实例。如果你需要 composable 的边缘支持,请在 Discord 或 GitHub 上告知我们。
故障排除
Prisma Studio 无法通过 pnpm
打开
如果你在使用 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*
这将确保 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 文件中
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 上互动 通过为仓库加星标、报告问题或为问题做出贡献。