Skip to main content

生成器

Prisma 模式可以有一个或多个生成器，由 generator 块表示：

¥A Prisma schema can have one or more generators, represented by the generator block:

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

生成器确定当你运行 prisma generate 命令时创建哪些资源。

¥A generator determines which assets are created when you run the prisma generate command.

Prisma 客户端有两个生成器：

¥There are two generators for Prisma Client:

  • prisma-client-js：将 Prisma 客户端生成到 node_modules

    ¥prisma-client-js: Generates Prisma Client into node_modules

  • prisma-client (抢先体验):更新、更灵活的 prisma-client-js 版本，支持 ESM；它输出纯 TypeScript 代码，并需要自定义 output 路径。

    ¥prisma-client (Early Access): Newer and more flexible version of prisma-client-js with ESM support; it outputs plain TypeScript code and requires a custom output path

或者，你可以配置任何符合我们生成器规范的 npm 包。

¥Alternatively, you can configure any npm package that complies with our generator specification.

prisma-client-js​

prisma-client-js 是 Prisma ORM 6.X 及之前版本默认的生成器。它需要 @prisma/client npm 包，并将 Prisma 客户端生成到 node_modules 中。

¥The prisma-client-js is the default generator for Prisma ORM 6.X versions and before. It requires the @prisma/client npm package and generates Prisma Client into node_modules.

字段参考​

¥Field reference

Prisma JavaScript 客户端的生成器接受多个附加属性：

¥The generator for Prisma's JavaScript Client accepts multiple additional properties:

  • previewFeatures：预览功能 包括

    ¥previewFeatures: Preview features to include

  • binaryTargets：prisma-client-js 的引擎二进制目标（例如，如果你要部署到 Ubuntu 18+，则为 debian-openssl-1.1.x；如果你在本地工作，则为 native）

    ¥binaryTargets: Engine binary targets for prisma-client-js (for example, debian-openssl-1.1.x if you are deploying to Ubuntu 18+, or native if you are working locally)

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["sample-preview-feature"]
  binaryTargets   = ["debian-openssl-1.1.x"] // defaults to `"native"`
}

二进制目标​

¥Binary targets

注意

从 v6.7.0 开始，Prisma ORM 具有 queryCompiler 预览功能。

¥As of v6.7.0, Prisma ORM has the queryCompiler Preview feature.

启用后，你的 Prisma 客户端将生成 无需基于 Rust 的查询引擎二进制文件：

¥When enabled, your Prisma Client will be generated without a Rust-based query engine binary:

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

请注意，驱动适配器 预览功能与 queryCompiler 功能同时启用。

¥Note that the driver adapters Preview feature is required alongside queryCompiler.

使用 queryCompiler 预览功能时，binaryTargets 字段已过时且不再需要。

¥When using the queryCompiler Preview feature, the binaryTargets field is obsolete and not needed.

prisma-client-js 生成器使用多个 engines。引擎使用 Rust 实现，并以可执行的、平台相关的引擎文件的形式由 Prisma 客户端使用。根据你执行代码的平台，你需要正确的文件。"二进制目标" 用于定义目标平台应存在哪些文件。

¥The prisma-client-js generator uses several engines. Engines are implemented in Rust and are used by Prisma Client in the form of executable, platform-dependent engine files. Depending on which platform you are executing your code on, you need the correct file. "Binary targets" are used to define which files should be present for the target platform(s).

当你的应用投入生产时，正确的文件尤其重要，因为生产环境通常与你的本地开发环境不同。

¥The correct file is particularly important when deploying your application to production, which often differs from your local development environment.

native 二进制目标​

¥The native binary target

native 二进制目标很特殊。它不映射到具体的操作系统。相反，当在 binaryTargets 中指定 native 时，Prisma Client 会检测当前操作系统并自动为其指定正确的二进制目标。

¥The native binary target is special. It doesn't map to a concrete operating system. Instead, when native is specified in binaryTargets, Prisma Client detects the current operating system and automatically specifies the correct binary target for it.

例如，假设你正在运行 macOS 并指定以下生成器：

¥As an example, assume you're running macOS and you specify the following generator:

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

在这种情况下，Prisma 客户端会检测你的操作系统并根据 支持的操作系统列表 找到正确的二进制文件。 如果你使用 macOS Intel x86 (darwin)，则将选择为 darwin 编译的二进制文件。如果你使用 macOS ARM64 (darwin-arm64)，则将选择为 darwin-arm64 编译的二进制文件。

¥In that case, Prisma Client detects your operating system and finds the right binary file for it based on the list of supported operating systems . If you use macOS Intel x86 (darwin), then the binary file that was compiled for darwin will be selected. If you use macOS ARM64 (darwin-arm64), then the binary file that was compiled for darwin-arm64 will be selected.

注意：native 二进制目标是默认值。如果你希望包含额外的 二进制目标 以部署到不同的环境，你可以明确设置它。

¥Note: The native binary target is the default. You can set it explicitly if you wish to include additional binary targets for deployment to different environments.

prisma-client（抢先体验版）​

¥prisma-client (Early Access)

新的 prisma-client 生成器在不同的 JavaScript 环境（例如 ESM、Bun、Deno 等）中使用 Prisma ORM 时，提供了更强大的控制力和灵活性。

¥The new prisma-client generator offers greater control and flexibility when using Prisma ORM across different JavaScript environments (such as ESM, Bun, Deno, ...).

它会将 Prisma 客户端生成到应用代码库中的自定义目录中，该目录通过 generator 块中的 output 字段指定。这将使你能够完全查看和控制生成的代码。它还将生成的 Prisma 客户端库 splits 到多个文件中。

¥It generates Prisma Client into a custom directory in your application's codebase that's specified via the output field on the generator block. This gives you full visibility and control over the generated code. It also splits the generated Prisma Client library into multiple files.

目前在 抢先体验 中，此生成器可确保你以所需的方式打包应用代码，而无需依赖隐藏或自动行为。

¥Currently in Early Access, this generator ensures you can bundle your application code exactly the way you want, without relying on hidden or automatic behaviors.

与 prisma-client-js 相比，主要区别如下：

¥Here are the main differences compared to prisma-client-js:

  • 需要 output 路径；不再需要“魔法”生成 node_modules。

    ¥Requires an output path; no “magic” generation into node_modules any more

  • 通过 moduleFormat 字段支持 ESM 和 CommonJS

    ¥Supports ESM and CommonJS via the moduleFormat field

  • 由于添加了字段，因此更加灵活

    ¥More flexible thanks to additional fields

  • 输出纯 TypeScript，与应用的其他代码一样打包在一起。

    ¥Outputs plain TypeScript that's bundled just like the rest of your application code

prisma-client 生成器将成为 Prisma ORM v7 的新默认生成器。

¥The prisma-client generator will become the new default with Prisma ORM v7.

入门​

¥Getting started

按照以下步骤在你的项目中使用新的 prisma-client 生成器。

¥Follow these steps to use the new prisma-client generator in your project.

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

¥ Configure the prisma-client generator in schema.prisma

更新你的 generator 块：

¥Update your generator block:

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

output 选项是必需的，它告诉 Prisma ORM 将生成的 Prisma 数据放在何处客户端代码。你可以选择任何适合你项目结构的位置。例如，如果你有以下布局：

¥The output option is required and tells Prisma ORM where to put the generated Prisma Client code. You can choose any location suitable for your project structure. For instance, if you have the following layout:

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

然后，../src/generated/prisma 将生成的代码放置在 src/generated/prisma 中，并相对于 schema.prisma 进行放置。

¥Then ../src/generated/prisma places the generated code in src/generated/prisma relative to schema.prisma.

2. 生成 Prisma 客户端​

¥ Generate Prisma Client

运行以下命令生成 Prisma 客户端：

¥Generate Prisma Client by running:

npx prisma generate

这会将 Prisma 客户端的代码（包括查询引擎二进制文件）生成到指定的 output 文件夹中。

¥This generates the code for Prisma Client (including the query engine binary) into the specified output folder.

3. 从版本控制中排除生成的目录​

¥ Exclude the generated directory from version control

新的生成器包含 TypeScript 客户端代码和 查询引擎。将查询引擎纳入版本控制可能会导致不同机器上的兼容性问题。为避免这种情况，请将生成的目录添加到 .gitignore：

¥The new generator includes both the TypeScript client code and the query engine. Including the query engine in version control can cause compatibility issues on different machines. To avoid this, add the generated directory to .gitignore:

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

将来，你可以在 Prisma ORM 已完全从 Rust 过渡到 TypeScript 时安全地将生成的目录包含在版本控制中。

¥In the future, you can safely include the generated directory in version control when Prisma ORM is fully transitioned from Rust to TypeScript.

4. 在应用中使用 Prisma 客户端​

¥ Use Prisma Client in your application

导入 Prisma 客户端​

¥Importing Prisma Client

生成 Prisma 客户端后，从你指定的路径导入它：

¥After generating the Prisma Client, import it from the path you specified:

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

const prisma = new PrismaClient()

Prisma 客户端现在可以在你的项目中使用了。

¥Prisma Client is now ready to use in your project.

导入生成的模型类型​

¥Importing generated model types

如果你要导入为模型生成的类型，可以按如下方式操作：

¥If you're importing types generated for your models, you can do so as follows:

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

导入生成的枚举类型​

¥Importing generated enum types

如果你要导入为枚举生成的类型，可以按如下方式操作：

¥If you're importing types generated for your enums, you can do so as follows:

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

字段参考​

¥Field reference

在 generator client { ... } 块中使用以下选项。仅需要 output。其他字段使用默认值，或根据你的环境和 tsconfig.json 推断得出。

¥Use the following options in the generator client { ... } block. Only output is required. The other fields have defaults or are inferred from your environment and 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 生成器的选项：

¥Below are the options for the prisma-client generator:

选项默认描述
output（必需）生成 Prisma 客户端的目录，例如 ../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从环境推断导入语句中使用的文件扩展名。可以是 ts、mts、cts、js、mjs、cjs 或空（用于裸导入）。

输出拆分和导入类型​

¥Output splitting and importing types

prisma-client-js 生成器用于将所有类型生成到单个 index.d.ts 文件中，这可能会导致大型架构出现 降低编辑器速度（例如，破坏自动补齐功能）。

¥The prisma-client-js generator used to generate all typings into a single index.d.ts file, which could lead to slowing down editors (e.g. breaking auto-complete) with large schemas.

新的 prisma-client 生成器现在将生成的 Prisma 客户端库拆分为多个文件，从而避免了单个输出文件过大的问题。

¥The new prisma-client generator now splits the generated Prisma Client library into multiple files and thus avoids the problems of a single, large output file.

之前 (prisma-client-js)

¥Before (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) 之后

¥After (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

社区生成器​

¥Community generators

注意

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

¥Existing generators or new ones should not be affected if you are using a multi-file Prisma schema, unless a generator reads the schema manually.

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

¥The following is a list of community created generators.