跳到主要内容

管理 Prisma ORM 环境变量和设置

环境变量是存储在您机器本地环境中的字符串数据键值对。有关具体详细信息，请参阅我们的环境变量参考文档。

通常，变量的名称为大写，后跟等号，然后是变量的值

MY_VALUE=prisma

环境变量属于进程运行的环境。任何程序都可以读取和创建这些环境变量。它们是存储简单信息的廉价有效方法。

提示

在 Prisma ORM v6.4.0 中，我们发布了 prisma.config.ts 文件，供提前体验。此文件允许您以更灵活的方式管理环境变量和设置。

查看我们的参考以获取更多信息，并且不要忘记在我们的 GitHub 讨论中分享您的反馈！

Prisma ORM 如何使用环境变量​

Prisma ORM 始终从系统的环境中读取环境变量。

当您使用 prisma init 在项目中初始化 Prisma ORM 时，它会为您创建一个方便的 .env 文件，以便将您的connection url设置为环境变量。当您使用 Prisma CLI 或 Prisma Client 时，.env 文件内容以及其中定义的变量会添加到process.env 对象，Prisma ORM 可以在其中读取并使用它。

使用 .env 文件​

警告

不要将您的 .env 文件提交到版本控制中!

Prisma CLI 按照以下顺序查找 .env 文件

  1. 在项目的根文件夹中 (./.env)
  2. 从与 --schema 参数指定的 schema 相同的文件夹中
  3. 从与 package.json 中 "prisma": {"schema": "/path/to/schema.prisma"} 获取的 schema 相同的文件夹中
  4. 从 ./prisma 文件夹中

如果在步骤 1. 中找到 .env 文件，但在步骤 2.-4. 中找到其他冲突的 .env 变量，则 CLI 将抛出错误。例如，如果您在两个不同的 .env 文件中指定 DATABASE_URL 变量，您将收到以下错误

Error: There is a conflict between env vars in .env and prisma/.env
Conflicting env vars:
  DATABASE_URL

We suggest to move the contents of prisma/.env to .env to consolidate your env vars.

下表描述了 Prisma CLI 在哪里查找 .env 文件

命令schema 位置检查的 .env 文件位置，按顺序
prisma [命令]./prisma/schema.prisma./.env
./prisma/.env
prisma [命令] --schema=./a/b/schema.prisma./a/b/schema.prisma./.env
./a/b/.env
./prisma/.env
prisma [命令]"prisma": {"schema": "/path/to/schema.prisma"}.env
./path/to/schema/.env
./prisma/.env
prisma [命令]没有 schema（例如，在空目录中运行 prisma db pull 时）./.env
./prisma/.env

当运行 Prisma CLI 命令时，在该 .env 文件中定义的任何环境变量都将自动加载。

信息

想要使用多个 .env 文件？请参阅使用多个 .env 文件，了解如何设置和在应用程序中使用多个 .env 文件。

有关如果在两个地方定义了环境变量会发生什么，请参阅 dotenv 文档。

使用 .env 文件扩展变量​

可以使用 dotenv-expand 指定的格式扩展存储在 .env 文件中的变量。

.env
DATABASE_URL=postgresql://test:test@localhost:5432/test
DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=public

此外，您可以使用 外部 于 .env 文件设置的环境变量进行扩展。例如，在 Heroku 或类似的 PaaS 上设置的数据库 URL

# environment variable already set in the environment of the system
export DATABASE_URL=postgresql://test:test@localhost:5432/test
.env
DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=foo

这将使环境变量 DATABASE_URL_WITH_SCHEMA 的值 postgresql://test:test@localhost:5432/test?schema=foo 可供 Prisma ORM 使用。

在您的代码中使用环境变量​

如果您希望在运行时评估环境变量，则需要在应用程序代码中手动加载它们（例如，通过使用 dotenv）

import * as dotenv from 'dotenv'

dotenv.config() // Load the environment variables
console.log(`The connection URL is ${process.env.DATABASE_URL}`)

如果您为环境变量使用自定义文件名，您可以配置 dotenv 以使用该文件名

import * as dotenv from 'dotenv'

var envFile = path.resolve(join(__dirname, "myenv.env"))
dotenv.config({path: envFile}) // Load the environment variables
console.log(`The connection URL is ${process.env.DATABASE_URL}`)

如果您需要在环境文件之间进行变量扩展，您可以额外使用 dotenv-expand

import * as dotenv from 'dotenv'
const dotenvExpand = require('dotenv-expand')

var envFile = path.resolve(join(__dirname, "myenv.env"))
var mySqlEnv = dotenv.config({path: envFile})
dotenvExpand.expand(mySqlEnv)

如果您使用多个 .env 文件，您可以根据您运行的环境在项目的代码中引用环境文件。

import { config } from 'dotenv'

const envFile = process.env.NODE_ENV === 'development' ? '.env.development' : '.env.production'
config({ path: envFile })

手动设置环境变量​

由于 Prisma ORM 在查找环境变量时从系统环境读取，因此可以完全跳过使用 .env 并手动在本地系统上创建它们。

信息

以下示例将使用设置 DATABASE_URL 环境变量，该变量通常用于数据库连接 URL。

在 Mac/Linux 系统上手动设置环境变量​

在 Unix 机器 (Mac/Linux) 的终端中，您将变量导出为键值对。

export DATABASE_URL=postgresql://test:test@localhost:5432/test?schema=public

然后检查它是否已使用 printenv 成功设置

printenv DATABASE_URL
显示CLI结果
postgresql://test:test@localhost:5432/test?schema=public

在 Windows 系统上手动设置环境变量​

以下示例说明了如何根据您的偏好，使用命令提示符 (cmd.exe) 和 PowerShell 为当前用户设置环境变量。

set DATABASE_URL="postgresql://test:test@localhost:5432/test?schema=public"

然后检查它是否已成功设置

set DATABASE_URL

使用多个 .env 文件​

如果您在单个 .env 文件中存储指向每个环境的不同连接 URL，则存在生产数据库可能被删除的风险。

一种解决方案是拥有多个 .env 文件，每个文件代表不同的环境。实际上，这意味着您为每个环境创建一个文件

  • .env.development
  • .env.sample

然后使用像 dotenv-cli 这样的包，您可以为正在使用的环境加载正确的连接 URL。

信息

为了我们的目的，假设您有一个专用的开发数据库，供您在开发应用程序时使用。

  1. 将您的 .env 文件重命名为 .env.development
.env.development
DATABASE_URL="postgresql://prisma:prisma@localhost:5433/dev"
  1. 创建一个新的 .env.sample 文件，并将数据库名称更改为 sample（或您喜欢的名称）
.env.sample
DATABASE_URL="postgresql://prisma:prisma@localhost:5433/sample"
  1. 安装 dotenv-cli

为了让 Prisma ORM 和 Jest 知道要使用哪个 .env 文件，请更改您的 package.json 脚本以包含和调用 dotenv 包，并根据您正在运行的命令以及您希望它们在哪个环境中运行来指定要使用的文件。

信息

任何运行测试和迁移的顶级脚本都需要在其前面加上 dotenv 命令。这确保了来自 .env.sample 的环境变量被传递给所有命令，包括 Jest。

在不同环境中运行迁移​

您可以使用 dotenv-cli 包来指定运行迁移时 Prisma ORM 应使用的环境文件。

以下脚本使用 dotenv-cli 将 .env.sample 环境变量文件（其中包含 DATABASE_URL 连接字符串）传递给 Prisma ORM 迁移脚本。

迁移脚本​

package.json
  "scripts": {
    "migrate:postgres": "dotenv -e .env.sample -- npx prisma migrate deploy",
  },

在不同环境中运行测试​

在运行测试时，我们建议您模拟 Prisma Client。这样做时，您需要告诉 Jest 在运行测试时应使用哪个环境。

默认情况下，Prisma Client 将使用在项目根目录下的默认 .env 文件中指定的环境。

如果您创建了一个单独的 .env.sample 文件来指定您的测试数据库，则需要将此环境传递给 Jest。

以下脚本使用 dotenv-cli 将 .env.sample 环境变量文件（其中包含 DATABASE_URL 连接字符串）传递给 Jest。

package.json
  "scripts": {
    "test": "dotenv -e .env.sample -- jest -i"
  },