跳到主要内容

管理 Prisma ORM 环境变量和设置

环境变量是存储在你机器本地环境中的字符串数据的键值对。请参阅我们的 环境变量参考文档 获取具体细节。

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

MY_VALUE=prisma

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

提示

在 Prisma ORM v6.4.0 中，我们发布了 prisma.config.ts 文件的 Early Access 版本。该文件允许你以更灵活的方式管理你的环境变量和设置。

查看我们的参考文档 以获取更多信息，并且不要忘记在我们的 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 文件扩展变量​

存储在 .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

这将使环境变量 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"
  },