跳到主要内容

生成器

一个 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:要包含的预览功能
  • binaryTargetsprisma-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.prismasrc/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从环境中推断模块格式(esmcjs)。确定使用 import.meta.url 还是 __dirname
generatedFileExtensionts生成的 TypeScript 文件的文件扩展名(tsmtscts)。
importFileExtension从环境中推断import 语句中使用的文件扩展名。可以是 tsmtsctsjsmjscjs,或者为空(用于裸导入)。

输出拆分与类型导入

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。

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

© . All rights reserved.