跳至主要内容

生成器

Prisma schema 可以有一个或多个生成器，由 generator 块表示。

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

生成器决定了当你运行 prisma generate 命令时会创建哪些资产。

Prisma Client 的默认生成器是 prisma-client，它输出纯 TypeScript 代码，并且需要一个自定义的 output 路径（在此阅读更多信息）。

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

prisma-client​

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

它将 Prisma Client 生成到应用程序代码库中一个自定义目录，该目录通过 generator 块上的 output 字段指定。这让你对生成的代码拥有完全的可见性和控制权。它还 将 生成的 Prisma Client 库拆分成多个文件。

此生成器确保你可以完全按照自己的意愿打包应用程序代码，而无需依赖隐藏或自动行为。

以下是与 prisma-client-js 的主要区别

  • 需要一个 output 路径；不再“魔法”生成到 node_modules
  • 运行时不加载 .env；请改用 dotenv 或手动设置环境变量
  • 通过 moduleFormat 字段支持 ESM 和 CommonJS
  • 由于增加了额外的字段，更加灵活
  • 输出纯 TypeScript，与应用程序代码的其余部分一样进行捆绑

prisma-client 生成器自 v6.16.0 起已普遍可用，并且是 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
}

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

const prisma = new PrismaClient();

Prisma Client 现在可以在你的项目中使用。

导入生成的模型类型​

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

src/index.ts
import { UserModel, PostModel } from "./generated/prisma/models";

导入生成的枚举类型​

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

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

在浏览器环境中导入​

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

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

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

字段参考​

在 generator client { ... } 块中使用以下选项。只有 output 是必需的。其他字段具有默认值或从你的环境和 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 生成器的选项

选项默认值描述
output (必需)Prisma Client 生成的目录，例如 ../src/generated/prisma。
运行时nodejs目标运行时环境。
支持的值
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 都映射到相同的内部代码路径，但为了清晰起见，它们被保留为单独的用户可见值。

导入类型​

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

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

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

client.ts​

用于您的服务器代码。

  • 提供对 PrismaClient 实例以及所有模型和实用程序类型的访问。
  • 提供与 prisma-client-js 生成输出的最佳兼容性。
  • 包含对仅服务器包的传递依赖，因此不能在浏览器上下文中使用。

示例

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

browser.ts​

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

  • 不包含对 Node.js 或其他仅服务器包的传递依赖。
  • 不包含真正的 PrismaClient 构造函数。
  • 包含所有模型和枚举类型及值。
  • 提供对各种实用程序的访问，如 Prisma.JsonNull 和 Prisma.Decimal。
  • 从 v6.16.0 开始可用。
注意

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

你仍然可以将生成的代码包装成一个包，并像 prisma-client-js 那样自行使用类似的方法。

示例

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

enums.ts​

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

  • 不包含传递依赖项，非常精简。
  • 可在后端和前端使用。
  • 访问枚举时，优先使用此选项以获得最佳的 tree shaking 和类型检查性能。

示例

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

models.ts​

隔离访问所有模型类型。

  • 可在后端和前端使用。
  • 包含所有模型，包括其派生实用类型，如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。
注意

此处暴露的普通模型类型为 <ModelName>Model（例如 PostModel）。这与 client.ts 和 browser.ts 中暴露的名称不同，后者仅为 <ModelName>（例如 Post）。

这是由于内部限制，为了避免与内部类型可能发生的命名冲突。

示例

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

models/<ModelName>.ts​

单独访问单个模型的类型。

  • 可在后端和前端使用。
  • 包含模型及其派生实用类型，如 <ModelName>WhereInput 或 <ModelName>UpdateInput>。
注意

此处暴露的普通模型类型为 <ModelName>Model（例如 PostModel）。

示例

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

commonInputTypes.ts​

提供您很少直接需要的共享实用类型。

示例

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

internal/*​

警告

请勿直接从这些文件导入！它们不是生成代码稳定 API 的一部分，并且随时可能以破坏性方式更改。

通常，您可能需要的所有内容都通过 browser.ts 或 client.ts 在 Prisma 命名空间下公开。

prisma-client-js 的重大更改​

  • 在 generator 块上需要一个 output 路径
  • 没有 Prisma.validator 函数；您可以改用 TypeScript 原生 satisfies 关键字

示例​

要了解新的 prisma-client 生成器在实践中的样子，请查看我们最小且可运行的示例

示例框架捆绑器运行时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不适用

prisma-client-js (已弃用)​

已弃用

prisma-client-js 生成器自 Prisma 7 起已弃用。它是 Prisma ORM 6.X 及更早版本的默认生成器。我们建议新项目迁移到 prisma-client，并在可能的情况下更新现有项目。

prisma-client-js 生成器需要 @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.16.0起，Prisma ORM 可以在生产应用程序中不使用 Rust 引擎。在此处了解更多信息。

启用后，您的 Prisma Client 将在生成时不包含基于 Rust 的查询引擎二进制文件:

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

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

当不使用 Rust 运行 Prisma ORM 时，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 schema，则现有生成器或新生成器不应受影响，除非生成器手动读取 schema。

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

打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.