跳到主要內容

生成器

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

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

生成器決定了當你執行 prisma generate 命令時會建立哪些資產。

Prisma Client 有兩種生成器

  • prisma-client-js：將 Prisma Client 生成到 node_modules 中
  • prisma-client (搶先體驗)：prisma-client-js 的更新、更靈活版本，支援 ESM；它輸出純 TypeScript 程式碼並要求自定義 output 路徑

或者，你可以配置任何符合我們生成器規範的 npm 包。

prisma-client-js​

prisma-client-js 是 Prisma ORM 6.X 版本及更早版本的預設生成器。它需要 @prisma/client npm 包，並將 Prisma Client 生成到 node_modules 中。

欄位參考​

Prisma 的 JavaScript Client 生成器接受多個附加屬性

  • 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"`
}

二進位制目標​

注意

自 v6.7.0 起，Prisma ORM 擁有 queryCompiler 預覽功能。

啟用後，你的 Prisma Client 將不帶基於 Rust 的查詢引擎二進位制檔案生成。:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["queryCompiler", "driverAdapters"] 
}

請注意，驅動介面卡預覽功能是 queryCompiler 必需的。

當使用 queryCompiler 預覽功能時，binaryTargets 欄位已過時，不再需要。

prisma-client-js 生成器使用多個引擎。引擎是用 Rust 實現的，以可執行的、平臺依賴的引擎檔案的形式被 Prisma Client 使用。根據你執行程式碼的平臺，你需要正確的檔案。“二進位制目標”用於定義目標平臺應該存在哪些檔案。

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

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-client（搶先體驗）​

新的 prisma-client 生成器在使用 Prisma ORM 跨不同 JavaScript 環境（例如 ESM、Bun、Deno 等）時提供了更大的控制和靈活性。

它將 Prisma Client 生成到你應用程式程式碼庫中的自定義目錄，該目錄透過 generator 塊上的 output 欄位指定。這使你對生成的程式碼具有完全的可見性和控制。它還會將生成的 Prisma Client 庫拆分為多個檔案。

此生成器目前處於搶先體驗階段，它確保你可以完全按照自己的意願打包應用程式程式碼，而無需依賴隱藏或自動行為。

以下是與 prisma-client-js 相比的主要區別

  • 需要一個 output 路徑；不再“神奇地”生成到 node_modules 中
  • 透過 moduleFormat 欄位支援 ESM 和 CommonJS
  • 由於附加欄位而更靈活
  • 輸出純 TypeScript，它像你應用程式程式碼的其餘部分一樣進行打包

prisma-client 生成器將成為 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 path
}

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 客戶端程式碼，也包含查詢引擎。將查詢引擎包含在版本控制中可能會在不同機器上導致相容性問題。為避免此問題，請將生成的目錄新增到 .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.js"

const prisma = new PrismaClient()

Prisma Client 現在可以在你的專案中使用。

匯入生成的模型型別​

如果你正在匯入為模型生成的型別，可以如下操作

src/index.ts
import { User, Post } from "./generated/prisma/models.js"

匯入生成的列舉型別​

如果你正在匯入為列舉生成的型別，可以如下操作

src/index.ts
import { Role } from "./generated/prisma/enums.js"

欄位參考​

在 generator client { ... } 塊中使用以下選項。只有 output 是必需的。其他欄位具有預設值或從你的環境和 tsconfig.json 中推斷。

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

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

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

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

輸出拆分與型別匯入​

prisma-client-js 生成器曾將所有型別定義生成到一個 index.d.ts 檔案中，這可能導致在大型 schema 下編輯器變慢（例如破壞自動補全）。

新的 prisma-client 生成器現在將生成的 Prisma Client 庫拆分為多個檔案，從而避免了單個大型輸出檔案的問題。

之前 (prisma-client-js)

generated/
└── prisma
    ├── client.ts
    ├── index.ts # -> this is split into multiple files in 6.7.0
    └── libquery_engine-darwin.dylib.node

之後 (prisma-client)

generated/
└── prisma
    ├── client.ts
    ├── commonInputTypes.ts
    ├── enums.ts
    ├── internal
    │   ├── class.ts
    │   └── prismaNamespace.ts
    ├── libquery_engine-darwin.dylib.node
    ├── models
    │   ├── Post.ts
    │   └── User.ts
    └── models.ts

社群生成器​

注意

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

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

© . This site is unofficial and not affiliated with Prisma Data, Inc.