Prisma Config 参考

概述

¥Overview

Prisma 配置文件使用 TypeScript 配置 Prisma CLI，包括 migrate 和 studio 等子命令。

¥The Prisma Config file configures the Prisma CLI, including subcommands like migrate and studio, using TypeScript.

你可以通过以下两种方式之一定义你的配置：

¥You can define your config in either of two ways:

使用 defineConfig 助手：

¥Using the defineConfig helper:

import path from "node:path";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: path.join("prisma", "schema.prisma"),
  migrations: {
    path: path.join("db", "migrations"),
  },
  views: {
    path: path.join("db", "views"),
  },
  typedSql: {
    path: path.join("db", "queries"),
  }
});

将 TypeScript 的 satisfies 运算符与 PrismaConfig 类型结合使用：

¥Using TypeScript's satisfies operator with the PrismaConfig type:

import path from "node:path";
import type { PrismaConfig } from "prisma";

export default {
  schema: path.join("db", "schema.prisma"),
  migrations: {
    path: path.join("db", "migrations"),
  },
  views: {
    path: path.join("db", "views"),
  },
  typedSql: {
    path: path.join("db", "queries"),
  }
} satisfies PrismaConfig;

配置界面

¥Configuration interface

以下是 PrismaConfig 类型的简化版本：

¥Here is a simplified version of the PrismaConfig type:

export declare type PrismaConfig = {
  // Whether features with an unstable API are enabled.
  experimental: {
    adapter: true,
    externalTables: true,
    studio: true,
  },

  // The path to the schema file, or path to a folder that shall be recursively searched for *.prisma files.
  schema?: string;

  // The Driver Adapter used for Prisma CLI.
  adapter?: () => Promise<SqlMigrationAwareDriverAdapterFactory>;

  // The configuration for Prisma Studio.
  studio?: {
    adapter: () => Promise<SqlMigrationAwareDriverAdapterFactory>;
  };

  // Configuration for Prisma migrations.
  migrations?: {
    path: string;
    seed: string;
    initShadowDb: string;
  };

  // Configuration for the database view entities.
  views?: {
    path: string;
  };

  // Configuration for the `typedSql` preview feature.
  typedSql?: {
    path: string;
  };
};

支持的文件扩展名

¥Supported file extensions

Prisma 配置文件可以命名为 prisma.config.* 或 .config/prisma.*，并使用扩展名 js、ts、mjs、cjs、mts 或 cts。支持其他扩展，以确保与不同的 TypeScript 编译器设置兼容。

¥Prisma Config files can be named as prisma.config.* or .config/prisma.* with the extensions js, ts, mjs, cjs, mts, or cts. Other extensions are supported to ensure compatibility with different TypeScript compiler settings.

选项参考

¥Options reference

`schema`

配置 Prisma ORM 定位和加载架构文件的方式。可以是文件或文件夹路径。相对路径是相对于 prisma.config.ts 文件位置解析的。有关模式位置选项的更多信息，请参阅此处。

¥Configures how Prisma ORM locates and loads your schema file(s). Can be a file or folder path. Relative paths are resolved relative to the prisma.config.ts file location. See here for more info about schema location options.

属性	类型	必需的	默认
`schema`	`string`	不	`./prisma/schema.prisma` 和 `./schema.prisma`

`migrate`

配置 Prisma Migrate 与底层数据库的通信方式。有关详细信息，请参阅下面的子选项。

¥Configures how Prisma Migrate communicates with your underlying database. See sub-options below for details.

属性	类型	必需的	默认
`migrate`	`object`	不	`{}`

`adapter`

返回 Prisma 驱动程序适配器实例的函数，Prisma CLI 会使用该实例运行迁移。该函数应返回一个可解析为有效 Prisma 驱动程序适配器的 Promise。

¥A function that returns a Prisma driver adapter instance which is used by the Prisma CLI to run migrations. The function should return a Promise that resolves to a valid Prisma driver adapter.

属性	类型	必需的	默认
`adapter`	`() => Promise<SqlMigrationAwareDriverAdapterFactory>`	不	none

使用 Prisma ORM D1 驱动程序适配器的示例：

¥Example using the Prisma ORM D1 driver adapter:

import path from "node:path";
import type { PrismaConfig } from "prisma";
import { PrismaD1 } from "@prisma/adapter-d1";

// import your .env file
import "dotenv/config";

export default {
  experimental: {
    adapter: true
  },
  schema: path.join("prisma", "schema.prisma"),
  async adapter() {
    return new PrismaD1({
      CLOUDFLARE_D1_TOKEN: process.env.CLOUDFLARE_D1_TOKEN,
      CLOUDFLARE_ACCOUNT_ID: process.env.CLOUDFLARE_ACCOUNT_ID,
      CLOUDFLARE_DATABASE_ID: process.env.CLOUDFLARE_DATABASE_ID,
    });
  },
} satisfies PrismaConfig;

注意

从 Prisma ORM v6.11.0 开始，D1 适配器已从 PrismaD1HTTP 重命名为 PrismaD1。

¥As of Prisma ORM v6.11.0, the D1 adapter has been renamed from PrismaD1HTTP to PrismaD1.

`studio`

配置 Prisma Studio 如何连接到你的数据库。有关详细信息，请参阅下面的子选项。

¥Configures how Prisma Studio connects to your database. See sub-options below for details.

属性	类型	必需的	默认
`studio`	`object`	不	none

`studio.adapter`

返回 Prisma 驱动程序适配器实例的函数。该函数接收一个包含环境变量的 env 参数，并返回一个解析为有效 Prisma 驱动程序适配器的 Promise 参数。

¥A function that returns a Prisma driver adapter instance. The function receives an env parameter containing environment variables and should return a Promise that resolves to a valid Prisma driver adapter.

属性	类型	必需的	默认
`studio.adapter`	`(env: Env) => Promise<SqlMigrationAwareDriverAdapterFactory>`	不	none

使用 Prisma ORM LibSQL 驱动程序适配器的示例：

¥Example using the Prisma ORM LibSQL driver adapter:

import type { PrismaConfig } from "prisma";

export default {
  experimental: {
    studio: true
  },
  studio: {
    adapter: async (env: Env) => {
      const { PrismaLibSQL } = await import("@prisma/adapter-libsql");
      const { createClient } = await import("@libsql/client");

      const libsql = createClient({
        url: env.DOTENV_PRISMA_STUDIO_LIBSQL_DATABASE_URL,
      });
      return new PrismaLibSQL(libsql);
    },
  },
} satisfies PrismaConfig;

`tables.external` 和 `enums.external`

¥tables.external and enums.external

这些选项声明数据库中由外部管理（而非由 Prisma Migrate 管理）的表和枚举。你仍然可以使用 Prisma 客户端查询它们，但它们将被迁移忽略。

¥These options declare tables and enums in your database that are managed externally (not by Prisma Migrate). You can still query them with Prisma Client, but they will be ignored by migrations.

属性	类型	必需的	默认
`tables.external`	`string[]`	不	`[]`
`enums.external`	`string[]`	不	`[]`

示例：

¥Example:

import { defineConfig } from "prisma/config";

export default defineConfig({
  experimental: {
    externalTables: true,
  },
  tables: {
    external: ["public.users"],
  },
  enums: {
    external: ["public.role"],
  },
});

了解更多关于 externalTables 功能在此的信息。

¥Learn more about the externalTables feature here.

`migrations.path`

Prisma 存储迁移文件的目录路径，并查找它们。

¥The path to the directory where Prisma should store migration files, and look for them.

属性	类型	必需的	默认
`migrations.path`	`string`	不	none

`migrations.seed`

This option allows you to define a script that Prisma runs to seed your database after running migrations or using the npx prisma db seed command.The string should be a command that can be executed in your terminal, such as with node, ts-node, or tsx.

属性	类型	必需的	默认
`migrations.seed`	`string`	不	none

示例：

¥Example:

import { defineConfig } from "prisma/config";

export default defineConfig({
  migrations: {
    seed: `tsx db/seed.ts`,
  },
});

`migrations.initShadowDb`

此选项允许你在创建迁移之前定义 Prisma 在影子数据库上运行的 SQL 语句。在使用外部管理表时，此功能非常有用，因为 Prisma 需要了解这些表的结构才能正确生成迁移。

¥This option allows you to define SQL statements that Prisma runs on the shadow database before creating migrations. It is useful when working with external managed tables, as Prisma needs to know about the structure of these tables to correctly generate migrations.

属性	类型	必需的	默认
`migrations.initShadowDb`	`string`	不	none

示例：

¥Example:

import { defineConfig } from "prisma/config";

export default defineConfig({
  experimental: {
    externalTables: true,
  },
  tables: {
    external: ["public.users"],
  },
  migrations: {
    initShadowDb: `
      CREATE TABLE public.users (id SERIAL PRIMARY KEY);
    `,
  },
});

了解更多关于 externalTables 功能在此的信息。

¥Learn more about the externalTables feature here.

`views.path`

Prisma 查找 SQL 视图定义的目录路径。

¥The path to the directory where Prisma should look for the SQL view definitions.

属性	类型	必需的	默认
`views.path`	`string`	不	none

`typedSql.path`

Prisma 应在其中查找用于通过 typedSql 生成类型的 SQL 文件的目录路径。

¥The path to the directory where Prisma should look for the SQL files used for generating typings via typedSql.

属性	类型	必需的	默认
`typedSql.path`	`string`	不	none

`experimental`

在 Prisma CLI 中启用特定的实验性功能。

¥Enables specific experimental features in the Prisma CLI.

属性	类型	必需的	默认
`adapter`	`boolean`	不	`false`
`externalTables`	`boolean`	不	`false`
`studio`	`boolean`	不	`false`

示例：

¥Example:

import { defineConfig } from "prisma/config";

export default defineConfig({
  experimental: {
    adapter: true,
    externalTables: true,
    studio: true,
  },
  schema: "prisma/schema.prisma",
});

注意

如果你使用 adapter、studio 或 externalTables 等功能而未启用相应的实验性标志，Prisma 将抛出错误：

¥If you use features like adapter, studio or externalTables without enabling the corresponding experimental flag, Prisma will throw an error:

Failed to load config file "~" as a TypeScript/JavaScript module. Error: Error: The `studio` configuration requires `experimental.studio` to be set to `true`.

常见模式

¥Common patterns

设置你的项目

¥Setting up your project

要开始使用 Prisma Config，请在项目根目录中创建一个 prisma.config.ts 文件。你可以使用以下任一方法：

¥To get started with Prisma Config, create a prisma.config.ts file in your project root. You can use either of these approaches:

使用 defineConfig：

¥Using defineConfig:

import { defineConfig } from "prisma/config";

export default defineConfig({});

使用 TypeScript 类型：

¥Using TypeScript types:

import type { PrismaConfig } from "prisma";

export default {} satisfies PrismaConfig;

使用环境变量

¥Using environment variables

使用 prisma.config.ts 时，不会自动加载来自 .env 文件的环境变量。你需要：

¥When using prisma.config.ts, environment variables from .env files are not automatically loaded. You'll need to:

安装 dotenv 包：

¥Install the dotenv package:

npm install dotenv

在你的配置文件中导入 dotenv/config：

¥Import dotenv/config in your config file:

import "dotenv/config";
import type { PrismaConfig } from "prisma";

export default {
  // now you can use process.env variables
} satisfies PrismaConfig;

使用多文件模式

¥Using multi-file schemas

如果你要将 Prisma 模式拆分为多个文件，则需要通过 schema 属性指定 Prisma 模式文件夹的路径：

¥If you want to split your Prisma schema into multiple files, you need to specify the path to your Prisma schema folder via the schema property:

import path from "node:path";
import type { PrismaConfig } from "prisma";

export default {
  schema: path.join("prisma", "schema"),
} satisfies PrismaConfig;

在这种情况下，你的 migrations 目录必须位于定义 datasource 块的 .prisma 文件旁边。

¥In that case, your migrations directory must be located next to the .prisma file that defines the datasource block.

例如，假设 schema.prisma 定义了 datasource，则迁移文件夹的放置方式如下：

¥For example, assuming schema.prisma defines the datasource, here's how how need to place the migrations folder:

# `migrations` and `schema.prisma` are on the same level
.
├── migrations
├── models
│   ├── posts.prisma
│   └── users.prisma
└── schema.prisma

路径解析

¥Path resolution

Prisma CLI 命令（例如 prisma validate 或 prisma migrate）使用 prisma.config.ts（或 .config/prisma.ts）来定位 Prisma 模式和其他资源。

¥Prisma CLI commands such as prisma validate or prisma migrate use prisma.config.ts (or .config/prisma.ts) to locate your Prisma schema and other resources.

关键规则：

¥Key rules:

配置文件中定义的路径（例如 schema、migrations）始终相对于配置文件的位置解析，而不是你运行 CLI 命令的位置。

¥Paths defined in the config file (e.g., schema, migrations) are always resolved relative to the location of the config file, not where you run the CLI command from.
CLI 首先必须找到配置文件本身，这取决于 Prisma 的安装方式和所使用的包管理器。

¥The CLI must first find the config file itself, which depends on how Prisma is installed and the package manager used.

使用 `pnpm prisma` 的行为

¥Behavior with pnpm prisma

当 Prisma 在本地安装并通过 pnpm prisma 运行时，无论你是从项目根目录还是子目录运行命令，都会自动检测配置文件。

¥When Prisma is installed locally and run via pnpm prisma, the config file is detected automatically whether you run the command from the project root or a subdirectory.

示例项目树：

¥Example project tree:

.
├── node_modules
├── package.json
├── prisma-custom
│   └── schema.prisma
├── prisma.config.ts
└── src

从项目根目录运行示例：

¥Example run from the project root:

pnpm prisma validate
# → Loaded Prisma config from ./prisma.config.ts
# → Prisma schema loaded from prisma-custom/schema.prisma

从子目录运行示例：

¥Example run from a subdirectory:

cd src
pnpm prisma validate
# → Still finds prisma.config.ts and resolves schema correctly

使用 `npm exec prisma` 或 `bun prisma` 的行为

¥Behavior with npm exec prisma or bun prisma

当通过 npm exec prisma 或 bun prisma 运行时，CLI 仅当命令从项目根目录（其中 package.json 声明了 Prisma）运行时才会检测配置文件。

¥When running via npm exec prisma or bun prisma, the CLI only detects the config file if the command is run from the project root (where package.json declares Prisma).

从项目根目录运行示例：

¥Example run from the project root:

npm exec prisma validate
# → Works as expected

从子目录运行（失败）：

¥Run from a subdirectory (fails):

cd src
npm exec prisma validate
# → Error: Could not find Prisma Schema...

要解决此问题，你可以使用 --config 标志：

¥To fix this, you can use the --config flag:

npm exec prisma -- --config ../prisma.config.ts validate

全球 Prisma 安装

¥Global Prisma installations

如果 Prisma 是全局安装的（npm i -g prisma），默认情况下它可能找不到你的 prisma.config.ts 或 prisma/config 模块。避免问题：

¥If Prisma is installed globally (npm i -g prisma), it may not find your prisma.config.ts or prisma/config module by default. To avoid issues:

建议在项目中本地安装 Prisma。

¥Prefer local Prisma installations in your project.
或者在本地使用 @prisma/config，并将 --config 传递到你的配置文件。

¥Or use @prisma/config locally and pass --config to point to your config file.

Monorepos

如果 Prisma 安装在工作区根目录中，pnpm prisma 将从子目录中检测配置文件。

¥If Prisma is installed in the workspace root, pnpm prisma will detect the config file from subdirectories.
如果 Prisma 安装在子包中（例如 ./packages/db），请从该包目录或更深层次的目录中运行命令。

¥If Prisma is installed in a subpackage (e.g., ./packages/db), run commands from that package directory or deeper.

自定义配置位置

¥Custom config location

你可以在运行 Prisma CLI 命令时为配置文件指定自定义位置：

¥You can specify a custom location for your config file when running Prisma CLI commands:

prisma validate --config ./path/to/myconfig.ts

概述​

配置界面​

支持的文件扩展名​

选项参考​

schema​

migrate​

adapter​

studio​

studio.adapter​

tables.external 和 enums.external​

migrations.path​

migrations.seed​

migrations.initShadowDb​

views.path​

typedSql.path​

experimental​

常见模式​

设置你的项目​

使用环境变量​

使用多文件模式​

路径解析​

使用 pnpm prisma 的行为​

使用 npm exec prisma 或 bun prisma 的行为​

全球 Prisma 安装​

Monorepos​

自定义配置位置​

概述

配置界面

支持的文件扩展名

选项参考

`schema`

`migrate`

`adapter`

`studio`

`studio.adapter`

`tables.external` 和 `enums.external`

`migrations.path`

`migrations.seed`

`migrations.initShadowDb`

`views.path`

`typedSql.path`

`experimental`

常见模式

设置你的项目

使用环境变量

使用多文件模式

路径解析

使用 `pnpm prisma` 的行为

使用 `npm exec prisma` 或 `bun prisma` 的行为

全球 Prisma 安装

Monorepos

自定义配置位置