管理 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 檔案，供您將連線網址設定為環境變數。當您使用 Prisma CLI 或 Prisma Client 時，.env 檔案內容和其中定義的變數會被新增到process.env 物件，Prisma ORM 可以在其中讀取並使用它。

使用 `.env` 檔案

警告

不要將您的 .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 [命令]`	`./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 檔案外部設定的。例如，在 PaaS (如 Heroku 或類似平台) 上設定的資料庫網址

# 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 環境變數，該變數通常用於資料庫連線網址。

在 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 (取決於您的偏好) 設定環境變數 (針對目前使用者)。

命令提示字元
Powershell

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

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

然後檢查是否已成功設定

命令提示字元
Powershell

set DATABASE_URL

Get-ChildItem Env:DATABASE_URL

使用多個 `.env` 檔案

如果您在單個 .env 檔案中儲存指向不同環境的不同連線網址，則您的生產資料庫可能會被刪除的風險。

一種解決方案是使用多個 .env 檔案，每個檔案代表不同的環境。實際上，這表示您為每個環境建立一個檔案

.env.development
.env.sample

然後使用像 dotenv-cli 這樣的套件，您可以為您正在工作的環境載入正確的連線網址。

資訊

就我們的目的而言，假設您有一個專用的開發資料庫，供您在開發應用程式時使用。

將您的 .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 套件，並指定要使用的檔案，具體取決於您正在執行的命令以及您希望它們在哪個環境中運行。

資訊

任何正在運行測試和遷移的頂層指令碼都需要在其前面加上 dotenv 命令。這確保了 .env.sample 中的 env 變數被傳遞到所有命令，包括 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 檔案​

在不同環境中執行遷移​

遷移指令碼​

在不同環境中執行測試​