跳至主要内容

生成器

一个 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 需要同时启用 驱动程序适配器 (driver adapters) 预览功能。

使用 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 后，从你指定的路径导入类型

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

const prisma = new PrismaClient()

Prisma Client 现在已准备好在你的项目中使用。

字段参考​

在 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
    ├── index.ts
    ├── internal
    │   ├── class.ts
    │   └── prismaNamespace.ts
    ├── libquery_engine-darwin.dylib.node
    ├── models
    │   ├── Post.ts
    │   └── User.ts
    └── models.ts

社区生成器​

注意

如果你使用多文件 Prisma schema，现有的或新的生成器应该不会受到影响，除非生成器手动读取 schema。

以下是社区创建的生成器列表。