管理 Prisma ORM 环境变量和设置

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

通常，变量名采用大写形式，后跟等号，然后是变量值。

MY_VALUE=prisma

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

提示

随着 Prisma ORM v6.4.0 的发布，我们推出了 prisma.config.ts 文件。此文件允许您以更灵活的方式管理环境变量和设置。查看我们的参考资料以获取更多信息。

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"

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

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

set DATABASE_URL

Get-ChildItem Env:DATABASE_URL

使用多个 .env 文件

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

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

• .env.development
• .env.sample

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

信息

出于我们的目的，假设您在开发应用程序时使用专用开发数据库。

1. 将您的 .env 文件重命名为 .env.development。

.env.development

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

2. 创建一个新的 .env.sample 文件，并将数据库名称更改为 sample（或您喜欢的名称）。

.env.sample

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

3. 安装 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"
  },