跳至主要內容

產生器

Prisma schema 可以有一個或多個產生器，由 generator 區塊表示

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

產生器決定了當你執行 prisma generate 指令時會建立哪些產出物。

Prisma Client 的預設產生器是 prisma-client，它會輸出純 TypeScript 程式碼，並且需要自定義 output 路徑（在 這裡 閱讀更多相關資訊）。

或者，您可以配置任何符合我們產生器規範的 npm 套件。

prisma-client​

新的 prisma-client 產生器在不同的 JavaScript 環境（如 ESM、Bun、Deno...）中使用 Prisma ORM 時，提供了更大的控制權與靈活性。

它會將 Prisma Client 產生到應用程式程式碼庫中的自定義目錄，該目錄透過 generator 區塊上的 output 欄位指定。這讓您對產生的程式碼擁有完整的可見性與控制權。它還會將產生的 Prisma Client 函式庫 拆分 成多個檔案。

此產生器可確保您可以完全按照想要的方式打包應用程式程式碼，而無需依賴隱藏或自動的行為。

以下是與 prisma-client-js 相比的主要差異

  • 需要 output 路徑；不再有產出至 node_modules 的「魔術」行為
  • 不會在執行階段載入 .env；請改用 dotenv 或手動設定環境變數
  • 透過 moduleFormat 欄位支援 ESM 和 CommonJS
  • 由於額外的 欄位 而更具彈性
  • 輸出純 TypeScript，可以像應用程式的其他程式碼一樣進行打包

prisma-client 產生器自 v6.16.0 起已正式發布 (GA)，並從 Prisma ORM v7 開始成為預設產生器。

快速入門​

請按照以下步驟在您的專案中使用新的 prisma-client 產生器。

1. 在 schema.prisma 中配置 prisma-client 產生器​

更新您的 generator 區塊

prisma/schema.prisma
generator client {
  provider = "prisma-client"            // Required
  output   = "../src/generated/prisma"  // Required
}

output 選項是必填的，它會告訴 Prisma ORM 將產生的 Prisma Client 程式碼放在哪裡。您可以選擇任何適合您專案結構的位置。例如，如果您有以下佈局

.
├── package.json
├── prisma
│   └── schema.prisma
├── src
│   └── index.ts
└── tsconfig.json

那麼 ../src/generated/prisma 會將產生的程式碼放置在相對於 schema.prisma 的 src/generated/prisma 目錄中。

2. 產生 Prisma Client​

透過執行以下指令來產生 Prisma Client

npx prisma generate

這會將 Prisma Client 的程式碼（包括查詢引擎二進位檔）產生到指定的 output 資料夾中。

3. 將產生的目錄從版本控制中排除​

新的產生器包含 TypeScript 客戶端程式碼以及 查詢引擎 (query engine)。將查詢引擎包含在版本控制中可能會導致不同機器上的相容性問題。為了避免這種情況，請將產生的目錄新增到 .gitignore 中

.gitignore
# Keep the generated Prisma Client + query engine out of version control
/src/generated/prisma
注意

未來，當 Prisma ORM 完全從 Rust 轉換為 TypeScript 時，您就可以放心地將產生的目錄包含在版本控制中。

4. 在您的應用程式中使用 Prisma Client​

匯入 Prisma Client​

產生 Prisma Client 後，從您指定的路徑匯入它

src/index.ts
import { PrismaClient } from "./generated/prisma/client";

const prisma = new PrismaClient();

Prisma Client 現在已準備好在您的專案中使用。

匯入產生的模型型別​

如果您要匯入為模型產生的型別，可以按照以下方式進行

src/index.ts
import { UserModel, PostModel } from "./generated/prisma/models";

匯入產生的列舉型別​

如果您要匯入為列舉產生的型別，可以按照以下方式進行

src/index.ts
import { Role, User } from "./generated/prisma/enums";

在瀏覽器環境中匯入​

如果您需要在前端程式碼中存取產生的型別，可以按照以下方式匯入

src/index.ts
import { Role } from "./generated/prisma/browser";

請注意，./generated/prisma/browser 不會暴露 PrismaClient。

欄位參考​

在 generator client { ... } 區塊中使用以下選項。只有 output 是必填的。其他欄位具有預設值，或從您的環境和 tsconfig.json 推導而來。

schema.prisma
generator client {
  // Required
  provider = "prisma-client"
  output   = "../src/generated/prisma"

  // Optional
  engineType             = "client"
  runtime                = "nodejs"
  moduleFormat           = "esm"
  generatedFileExtension = "ts"
  importFileExtension    = "ts"
}

以下是 prisma-client 產生器的選項

選項預設值描述
output (必填)產生 Prisma Client 的目錄，例如 ../src/generated/prisma。
runtimenodejs目標執行環境。
支援的值
nodejs, deno, bun, workerd (別名 cloudflare), vercel-edge (別名 edge-light), react-native。
moduleFormat從環境推導模組格式 (esm 或 cjs)。決定使用 import.meta.url 還是 __dirname。
generatedFileExtensionts產生的 TypeScript 檔案的副檔名 (ts, mts, cts)。
importFileExtension從環境推導在 匯入語句 (import statements) 中使用的副檔名。可以是 ts, mts, cts, js, mjs, cjs，或者為空（用於裸匯入）。
注意

nodejs、deno 和 bun 都對應到相同的內部程式碼路徑，但為了清晰起見，保留為獨立的面向使用者的值。

匯入型別​

新的 prisma-client 產生器會建立個別的 .ts 檔案，這允許對型別進行更細粒度的匯入。這可以提高編譯和型別檢查效能，並且對 tree-shaking 也有幫助。您仍然可以使用透過單一匯入導出所有型別的頂層 barrel 檔案。

產生輸出的整體結構如下所示

generated/
└── prisma
    ├── browser.ts
    ├── client.ts
    ├── commonInputTypes.ts
    ├── enums.ts
    ├── internal
    │   ├── ...
    ├── models
    │   ├── Post.ts
    │   └── User.ts
    └── models.ts

client.ts​

用於您的伺服器端程式碼。

  • 提供對 PrismaClient 實例以及所有模型和實用型別的存取。
  • 提供與 prisma-client-js 產生輸出的最佳相容性。
  • 包含對僅限伺服器套件的遞移依賴，因此不能在瀏覽器環境中使用。

範例

import { Prisma, type Post, PrismaClient } from "./generated/prisma/client"

browser.ts​

用於在前端（即在瀏覽器中執行的程式碼）使用型別。

  • 不包含對 Node.js 或其他僅限伺服器套件的遞移依賴。
  • 不包含真正的 PrismaClient 建構函數。
  • 包含所有模型和列舉型別及其值。
  • 提供對各種實用工具的存取，例如 Prisma.JsonNull 和 Prisma.Decimal。
  • 自 v6.16.0 起可用。
注意

舊的 prisma-client-js 產生器會建立一個 node_modules 套件，並使用導出映射 (export maps) 動態提供產生之 Prisma Client 函式庫的瀏覽器相容導出。由於新的 prisma-client 產生器直接產生 TypeScript 原始碼，且不再包含 package.json 檔案，因此這種方法已不再可行。因此，您必須明確地指定匯入內容，以及程式碼是在伺服器端還是客戶端執行！

您仍然可以將產生的程式碼包裝在套件中，並自行使用與 prisma-client-js 類似的方法。

範例

import { Prisma, type Post } from "./generated/prisma/browser"

enums.ts​

獨立存取使用者定義的列舉型別和值。

  • 不包含遞移依賴，體積非常精簡。
  • 可用於後端和前端。
  • 存取列舉時，優先使用此檔案以獲得最佳的 tree shaking 和型別檢查效能。

範例

import { MyEnum } from "./generated/prisma/enums"

models.ts​

獨立存取所有模型型別。

  • 可用於後端和前端。
  • 包含所有模型，包括其衍生的實用型別，例如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。
注意

純模型型別在這裡暴露為 <ModelName>Model（例如 PostModel）。這與 client.ts 和 browser.ts 中暴露的名稱不同，後者僅為 <ModelName>（例如 Post）。

這是由於內部限制，為了避免與內部型別產生潛在的命名衝突而必須採取的做法。

範例

import type { UserModel, PostModel, PostWhereInput, UserUpdateInput } from "./generated/prisma/models"

models/<ModelName>.ts​

獨立存取單個模型的型別。

  • 可用於後端和前端。
  • 包含模型及其衍生的實用型別，例如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。
注意

純模型型別在這裡暴露為 <ModelName>Model（例如 PostModel）。

範例

import type { UserModel, UserWhereInput, UserUpdateInput } from "./generated/prisma/models/User"

commonInputTypes.ts​

提供您很少會直接需要的共享實用型別。

範例

import type { IntFilter } from "./generated/prisma/commonInputTypes"

internal/*​

警告

請勿直接從這些檔案匯入！它們不屬於產生程式碼穩定 API 的一部分，並且可能隨時發生破壞性更改。

通常您可能需要的任何內容都會透過 browser.ts 或 client.ts 在 Prisma 命名空間下暴露。

來自 prisma-client-js 的破壞性更改​

  • 需要在 generator 區塊上指定 output 路徑
  • 沒有 Prisma.validator 函式；您可以改用 TypeScript 原生的 satisfies 關鍵字

範例​

要查看新的 prisma-client 產生器在實踐中的樣子，請查看我們精簡且 可立即執行的範例

範例框架 (Framework)打包工具 (Bundler)執行環境 (Runtime)Monorepo
nextjs-starter-webpackNext.js 15WebpackNode.js不適用
nextjs-starter-turbopackNext.js 15Turbopack (alpha)Node.js不適用
nextjs-starter-webpack-monorepoNext.js 15WebpackNode.jspnpm
nextjs-starter-webpack-with-middlewareNext.js 15WebpackNode.js (主要頁面), vercel-edge (middleware)不適用
nextjs-starter-webpack-turborepoNext.js 15WebpackNode.jsturborepo
react-router-starter-nodejsReact Router 7Vite 6Node.js不適用
react-router-starter-cloudflare-workerdReact Router 7不適用
nuxt3-starter-nodejsNuxt 3Vite 6Node.js不適用
nuxt4-starter-nodejsNuxt 4Vite 7Node.js不適用
bun無無Deno 2不適用
deno無無Deno 2不適用

prisma-client-js (已廢棄)​

已廢棄

prisma-client-js 產生器自 Prisma 7 起已廢棄。它是 Prisma ORM 6.X 及更早版本的預設產生器。我們建議新專案遷移到 prisma-client，並在可能的情況下更新現有專案。

prisma-client-js 產生器需要 @prisma/client npm 套件，並將 Prisma Client 產生到 node_modules 中。

欄位參考​

Prisma 的 JavaScript 客戶端產生器接受多個額外的屬性

  • previewFeatures：要包含的 預覽功能
  • binaryTargets：prisma-client-js 的引擎二進位目標（例如，如果您要部署到 Ubuntu 18+，則為 debian-openssl-1.1.x，或者如果您在本地工作，則為 native）
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["sample-preview-feature"]
  binaryTargets   = ["debian-openssl-1.1.x"] // defaults to `"native"`
}

二進位目標 (Binary targets)​

注意

自 v6.16.0 起，Prisma ORM 可以在生產環境應用程式中不使用 Rust 引擎。請點擊 這裡 了解更多資訊。

啟用後，您的 Prisma Client 將在沒有基於 Rust 的查詢引擎二進位檔的情況下產生:

generator client {
  provider   = "prisma-client-js" // or "prisma-client"
  output     = "../src/generated/prisma"
  engineType = "client"           // no Rust engine
}

請注意，如果您想在不使用 Rust 引擎的情況下使用 Prisma ORM，則需要使用 驅動適配器 (driver adapters)。

當在不使用 Rust 的情況下使用 Prisma ORM 時，binaryTargets 欄位是過時且不需要的。

您可以在我們的部落格上閱讀關於此變更的效能與開發體驗提升。

prisma-client-js 產生器使用多個 引擎。引擎是用 Rust 實作的，並由 Prisma Client 以可執行且依賴於平台的引擎檔案形式使用。根據您執行程式碼的平台，您需要正確的檔案。「二進位目標 (Binary targets)」用於定義目標平台應存在哪些檔案。

將您的應用程式 部署 到生產環境時，正確的檔案尤為重要，因為生產環境通常與您的本地開發環境不同。

native 二進位目標​

native 二進位目標非常特殊。它並不對應到具體的作業系統。相反地，當在 binaryTargets 中指定 native 時，Prisma Client 會偵測當前作業系統並自動為其指定正確的二進位目標。

舉例來說，假設您正在執行 macOS 並指定了以下產生器

prisma/schema.prisma
generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native"]
}

在這種情況下，Prisma Client 會根據 支援的作業系統列表 偵測您的作業系統並找到對應的二進位檔案。如果您使用 macOS Intel x86 (darwin)，則會選擇為 darwin 編譯的二進位檔案。如果您使用 macOS ARM64 (darwin-arm64)，則會選擇為 darwin-arm64 編譯的二進位檔案。

注意：native 二進位目標是預設值。如果您希望包含額外的 二進位目標 以部署到不同的環境，則可以明確設定它。

社群產生器​

注意

如果您使用 多檔案 Prisma schema，現有的產生器或新的產生器應該不會受到影響，除非產生器是手動讀取 schema。

以下是社群建立的產生器列表。

開啟於
複製為 Markdown
於 Claude 開啟
在 ChatGPT 中開啟
在 T3.chat 中開啟
在 GitHub 中編輯
© . This site is unofficial and not affiliated with Prisma Data, Inc.