跳到主要內容

使用 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 相依性。請依照 Prisma Studio 步驟以取得詳細指示。

  3. 啟動開發伺服器

    npm run dev

    啟動開發伺服器將會

    1. 自動安裝 Prisma CLI
    2. 使用 SQLite 初始化 Prisma 專案
    3. 在 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
       }
    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 Schema 和遷移資料夾，您必須內省資料庫。完成內省指南中的步驟 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>

選項 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 的功能。以下是使用 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 Schema 檔案。
installStudio布林值true是否在 Nuxt Devtools 中安裝和啟動 Prisma Studio。
autoSetupPrisma布林值false是否略過設定期間的所有提示。此選項適用於自動化腳本或 CI/CD 管道中的 Prisma 設定。
skipPromptsfalsefalse略過所有提示
prismaRoot字串false使用 Nuxt 層時為必要項。例如，如果您有名為 database 的 Nuxt 層，則 prismaRoot 在基本 nuxt 配置中會是 ./database。這指的是將初始化或檢查 Prisma 的資料夾。
prismaSchemaPath字串未定義使用 Nuxt 層時為必要項。例如，如果您有名為 database 的 Nuxt 層，則 prismaSchemaPath 在基本 nuxt 配置中會是 ./database/prisma/schema.prisma。

限制​

PrismaClient 建構函式選項在 usePrismaClient 可組合項中無法配置​

usePrismaClient 模組目前不允許配置 PrismaClient 建構函式選項。

邊緣執行階段不支援 usePrismaClient 可組合項​

usePrismaClient 可組合項目前依賴在邊緣執行階段中無法運作的 PrismaClient 執行個體。如果您需要可組合項的邊緣支援，請在 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 相依性

.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',
      },
    },
  },
})

此配置可確保模組指定器正確對應到適當的檔案。

套件管理器支援中的限制​

此模組旨在與熱門的套件管理器搭配使用，包括 npm、Yarn 和 pnpm。但是，截至 v0.2，由於導致無限安裝迴圈的問題，它與 Bun 不完全相容。

此外，此套件尚未在 Deno 上測試過，因此未正式支援。