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"
  output   = "../generated/prisma"
}

生成器确定当你运行 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（推荐）：更新、更灵活的 prisma-client-js 版本，支持 ESM；它输出纯 TypeScript 代码，并需要自定义 output 路径（有关 此处 的更多信息，请参阅）

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

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

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

或者，你可以配置任何符合我们生成器规范的 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.16.0 开始，Prisma ORM 可以在生产应用中不使用 Rust 引擎使用。了解更多 此处。

¥As of v6.16.0, Prisma ORM can be used without Rust engines in production applications. Learn more here.

启用后，你的 Prisma 客户端将不包含基于 Rust 的查询引擎二进制文件：

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

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

请注意，如果你想在不使用 Rust 引擎的情况下使用 Prisma ORM，则需要 驱动适配器。

¥Note that driver adapters are required if you want to use Prisma ORM without Rust engines.

使用不带 Rust 的 Prisma ORM 时，binaryTargets 字段已过时且不再需要。

¥When using Prisma ORM without Rust, the binaryTargets field is obsolete and not needed.

你可以在我们的博客上了解此更改。

¥You can read about the performance and DX improvements of this change on our blog.

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 生成器在不同的 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.

此生成器确保你可以按照所需的方式打包应用代码，而无需依赖隐藏或自动行为。

¥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 路径；不再将 "magic" 生成到 node_modules 中

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

  • 运行时不加载 .env；使用 dotenv 或手动设置环境变量

    ¥Doesn't load .env at runtime; use dotenv or set environment variables manually instead

  • 通过 moduleFormat 字段支持 ESM 和 CommonJS

    ¥Supports ESM and CommonJS via the moduleFormat field

  • 新增 fields，让你更加灵活

    ¥More flexible thanks to additional fields

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

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

prisma-client 生成器已正式发布，因为 v6.16.0 将成为 Prisma ORM v7 的新默认生成器。

¥The prisma-client generator has been Generally Available since v6.16.0 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
}

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";

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 { UserModel, PostModel } from "./generated/prisma/models";

导入生成的枚举类型​

¥Importing generated enum types

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

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

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

在浏览器环境中导入​

¥Importing in browser environments

如果你需要在前端代码中访问生成的类型，可以按如下方式导入它们：

¥If you need to access generated types in your frontend code, you can import them as follows:

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

请注意，./generated/prisma/browser 不会暴露 PrismaClient。

¥Note that ./generated/prisma/browser does not expose a PrismaClient.

字段参考​

¥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
  engineType             = "client"
  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、deno、bun、workerd（别名 cloudflare）、vercel-edge（别名 edge-light）、react-native。
moduleFormat从环境推断模块格式（esm 或 cjs）。确定使用 import.meta.url 还是 __dirname。
generatedFileExtensionts生成的 TypeScript 文件（ts、mts、cts）的文件扩展名。
importFileExtension从环境推断导入语句中使用的文件扩展名。可以是 ts、mts、cts、js、mjs、cjs 或空（用于裸导入）。
注意

nodejs、deno 和 bun 都映射到相同的内部代码路径，但为了清晰起见，它们保留为单独的面向用户的值。

¥nodejs, deno, and bun all map to the same internal codepath but are preserved as separate user-facing values for clarity.

导入类型​

¥Importing types

新的 prisma-client 生成器会创建单独的 .ts 文件，以便更精细地导入类型。这可以提升编译和类型检查的性能，并且对 tree-shaking 也很有用。你仍然可以使用通过单个导入导出所有类型的顶层 barrel 文件。

¥The new prisma-client generator creates individual .ts files which allow for a more fine granular import of types. This can improve compile and typecheck performance and be useful for tree-shaking, too. You can still use the top level barrel files that export all types through a single import.

生成的输出的整体结构如下所示：

¥The overall structure of the generated output looks like this:

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

client.ts​

用于服务器代码。

¥For use in your server code.

  • 提供对 PrismaClient 实例以及所有模型和工具类型的访问权限。

    ¥Provides access to the PrismaClient instance and all model and utility types.

  • 与 prisma-client-js 生成的输出保持最佳兼容性。

    ¥Provides best compatibility with the prisma-client-js generated output.

  • 包含对服务器端软件包的传递依赖，因此无法在浏览器环境中使用。

    ¥Contains transitive dependencies on server only-packages, so cannot be used in browser contexts.

示例：

¥Example:

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

browser.ts​

用于在前端（即在浏览器中运行的代码）中使用类型。

¥For using types in your frontend (i.e. code that runs in the browser).

  • 不包含对 Node.js 或其他服务器端软件包的传递依赖。

    ¥Contains no transitive dependencies on Node.js or other server-only packages.

  • 不包含真正的 PrismaClient 构造函数。

    ¥Contains no real PrismaClient constructor.

  • 包含所有模型和枚举类型及值。

    ¥Contains all model and enum types and values.

  • 提供对各种实用程序（例如 Prisma.JsonNull 和 Prisma.Decimal）的访问权限。

    ¥Provides access to various utilities like Prisma.JsonNull and Prisma.Decimal.

  • 自 v6.16.0 起可用。

    ¥Available since v6.16.0.

注意

旧的 prisma-client-js 生成器会创建一个 node_modules 包，并使用导出映射来动态提供生成的 Prisma 客户端库的浏览器兼容导出。由于新的 prisma-client 生成器直接创建 TypeScript 源代码，而不再创建 package.json 文件，因此这种方法不可行。因此，你需要明确你的导入以及程序是在服务器还是客户端上运行！

¥The old prisma-client-js generator created a node_modules package and used export maps to dynamically provide a browser compatible export of the generated Prisma Client library. As the new prisma-client generator creates direct TypeScript source code and no package.json file anymore, this approach is not possible. Hence you need to be explicit about your imports and whether things run on server or client!

你仍然可以将生成的代码封装在一个包中，并使用与 prisma-client-js 类似的方法自行处理。

¥You can still wrap the generated code in a package and use a similar approach as with prisma-client-js on your own.

示例：

¥Example:

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

enums.ts​

对用户定义的枚举类型和值的隔离访问。

¥Isolated access to user defined enum types and values.

  • 不包含传递依赖，并且非常精简。

    ¥Contains no transitive dependencies and is very slim.

  • 可用于后端和前端。

    ¥Can be used on backend and frontend.

  • 访问枚举时，为了获得最佳的摇树优化和类型检查性能，建议使用此版本。

    ¥Prefer this for optimal tree shaking and typecheck performance when accessing enums.

示例：

¥Example:

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

models.ts​

对所有模型类型的隔离访问。

¥Isolated access to all model types.

  • 可用于后端和前端。

    ¥Can be used on backend and frontend.

  • 包含所有模型，包括其派生的工具类型，例如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。

    ¥Contains all models including their derived utility types like <ModelName>WhereInput or <ModelName>UpdateInput>.

注意

普通模型类型在此处公开为 <ModelName>Model（例如 PostModel）。这与 client.ts 和 browser.ts 中暴露的名称 <ModelName>（例如 Post）相反。

¥Plain model types are exposed here as <ModelName>Model (e.g. PostModel). This is in contrast to the exposed name in client.ts and browser.ts which is simply <ModelName> (e.g. Post).

由于内部约束，这样做是必要的，以避免与内部类型发生潜在的命名冲突。

¥This is necessary due to internal constraints to avoid potential naming conflicts with internal types.

示例：

¥Example:

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

models/<ModelName>.ts​

对单个模型类型的隔离访问。

¥Isolated access to the types for an individual model.

  • 可用于后端和前端。

    ¥Can be used on backend and frontend.

  • 包含模型及其派生的工具类型，例如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。

    ¥Contains the models including its derived utility types like <ModelName>WhereInput or <ModelName>UpdateInput>.

注意

普通模型类型在此处显示为 <ModelName>Model（例如 PostModel）。

¥The plain model type is exposed here as <ModelName>Model (e.g. PostModel).

示例：

¥Example:

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

commonInputTypes.ts​

提供你很少直接需要的共享工具类型。

¥Provides shared utility types that you should rarely directly need.

示例：

¥Example:

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

internal/*​

警告

请勿直接从这些文件导入！它们不属于生成代码的稳定 API，并且随时可能以重大方式发生变化。

¥Do not directly import from these files! They are not part of the stable API of the generated code and can change at any time in breaking ways.

通常，你可能需要的任何内容都会通过 Prisma 命名空间下的 browser.ts 或 client.ts 公开。

¥Usually anything you might need from there is exposed via browser.ts or client.ts under the Prisma namespace.

prisma-client-js 的重大变更​

¥Breaking changes from prisma-client-js

  • 需要 generator 块上的 output 路径

    ¥Requires an output path on the generator block

  • 没有 Prisma.validator 功能；你可以改用 TypeScript 原生 satisfies 关键字

    ¥No Prisma.validator function; you can use TypeScript native satisfies keyword instead

示例​

¥Examples

要了解新的 prisma-client 生成器的实际效果，请查看我们的极简 可立即运行的示例 生成器：

¥To see what the new prisma-client generator looks like in practice, check out our minimal and ready-to-run examples:

示例框架打包器运行时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（中间件）不适用
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不适用

社区生成器​

¥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.