管理 Prisma ORM 环境变量和设置

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

通常，变量名使用大写字母，后跟一个等号，然后再是变量值。

MY_VALUE=prisma

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

tip

随着 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` 文件

warning

不要将你的 .env 文件提交到版本控制系统!

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

在项目根文件夹中 (./.env)
在 --schema 参数指定的 schema 文件所在的文件夹中
在 package.json 中 "prisma": {"schema": "/path/to/schema.prisma"} 指定的 schema 文件所在的文件夹中
在 ./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 [command]`	`./prisma/schema.prisma`	`./.env` `./prisma/.env`
`prisma [command] --schema=./a/b/schema.prisma`	`./a/b/schema.prisma`	`./.env` `./a/b/.env` `./prisma/.env`
`prisma [command]`	`"prisma": {"schema": "/path/to/schema.prisma"}`	`.env` `./path/to/schema/.env` `./prisma/.env`
`prisma [command]`	无 schema（例如，在空目录中运行 `prisma db pull` 时）	`./.env` `./prisma/.env`

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

info

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

有关环境变量在两个位置定义时会发生什么的信息，请参阅 dotenv 文档的这一部分。

使用 `.env` 文件扩展变量

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

.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

这将使值为 postgresql://test:test@localhost:5432/test?schema=foo 的环境变量 DATABASE_URL_WITH_SCHEMA 可供 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 文件，并在本地系统上手动创建环境变量。

info

以下示例将使用设置 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 系统上手动设置环境变量

以下示例说明了如何使用 Command Prompt (cmd.exe) 和 PowerShell 为当前用户设置环境变量，具体取决于你的偏好。

Command Prompt
Powershell

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

[Environment]::SetEnvironmentVariable("DATABASE_URL", "postgresql://test:test@localhost:5432/test?schema=public")

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

Command Prompt
Powershell

set DATABASE_URL

Get-ChildItem Env:DATABASE_URL

使用多个 `.env` 文件

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

一个解决方案是使用多个 .env 文件，每个文件代表不同的环境。实际上，这意味着你需要为每个环境创建一个文件：

.env.development
.env.sample

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

info

为了方便起见，我们假设你有一个专用的开发数据库，你在开发应用程序时使用它。

将你的 .env 文件重命名为 .env.development

.env.development

DATABASE_URL="postgresql://prisma:prisma@localhost:5433/dev"

创建一个新的 .env.sample 文件，并将数据库名称更改为 sample（或你偏好的名称）

.env.sample

DATABASE_URL="postgresql://prisma:prisma@localhost:5433/sample"

安装 dotenv-cli

为了让 Prisma ORM 和 Jest 知道使用哪个 .env 文件，修改你的 package.json 脚本，使其包含并调用 dotenv 包，并根据你运行的命令和想要运行的环境来指定要使用的文件。

info

任何运行测试和迁移的顶级脚本都需要在前面加上 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"
  },

Prisma ORM 如何使用环境变量​

使用 .env 文件​

使用 .env 文件扩展变量​

在代码中使用环境变量​

手动设置环境变量​

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

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

使用多个 .env 文件​

在不同环境上运行迁移​

迁移脚本

在不同环境上运行测试​

Prisma ORM 如何使用环境变量

使用 `.env` 文件

使用 `.env` 文件扩展变量

在代码中使用环境变量

手动设置环境变量

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

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

使用多个 `.env` 文件

在不同环境上运行迁移

在不同环境上运行测试