> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Environments

每個 platform 專案都包含一或多個環境。

環境是隔離的部署目標，擁有自己的 URL、環境變數與部署記錄，也可擁有自己的[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)。

使用 Environments，即可在單一專案中執行相同程式碼的 `production`、`staging` 與預覽版本。

第一次執行 [`mastra deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 會建立 `production` 環境。可透過 CLI 建立更多環境，也可部署至尚不存在的名稱來建立。

## 建立環境

明確建立環境：

```bash
mastra env create staging
```

或在部署時建立，CLI 會要求確認：

```bash
mastra deploy --env staging
```

`mastra env create` 預設使用 `staging` 類型。傳入 `--type` 可明確設定 `staging` 或 `preview`，傳入 `--region` 則可選擇環境的執行位置：

```bash
mastra env create eu-preview --type preview --region eu
```

每個專案只有一個 `production` 環境，由第一次部署建立。區域在建立時固定。附加至環境的資料庫會自動佈建在靠近該環境區域的位置，Observability 資料則會路由至符合資料駐留分區的擷取區域。支援的區域、資料庫位置與 Observability 共置方式請參閱[區域](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/regions)。每個專案可有的環境數取決於方案。

## 列出環境

```bash
mastra env list
```

輸出會顯示各環境的名稱、區域、作用中部署狀態，以及附加資料庫注入的受管理環境變數。在 CI 中可傳入 `--json` 取得機器可讀輸出。

所有 `mastra env` 指令依序從 `MASTRA_PROJECT_ID`、`--project` 旗標或第一次部署寫入的 `.mastra-project.json` 解析專案。只要從專案目錄執行，就無須指定專案名稱。

## 環境變數

環境會從三種範圍解析變數：

- **受管理變數**：由附加的[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)注入（例如 `TURSO_DATABASE_URL`）。這些變數由 platform 定義，無法編輯。
- **環境範圍變數**：透過控制面板儲存在單一環境。適合用於各環境不同的值，例如測試與正式服務的 API 金鑰。
- **專案範圍變數**：儲存在專案中，由所有環境共用。

環境範圍與專案範圍變數合稱 [Deploy](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 頁面所述的已儲存變數。

變數會在部署開始時套用。若要在不完整重新部署的情況下，將變更後的變數套用至執行中的服務：

```bash
mastra env restart staging
```

若要查看環境部署實際使用的完整集合（合併環境範圍與專案範圍值，並按名稱列出受管理變數），可將它們提取至本機 env 檔案：

```bash
mastra env vars pull staging --output .env.staging
```

受管理變數的值會在部署時注入，絕不寫入檔案；檔案只會以註解列出名稱。

> **備註:** 環境變數不會覆寫受管理資料庫變數。若要讓環境指向不同資料庫，請改為附加[環境範圍資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)。

## 部署記錄

列出所有環境的部署，或篩選單一環境：

```bash
mastra env deploys
mastra env deploys staging
```

每列會顯示部署狀態、環境、時間戳記，以及目前作用中的部署。部署會依序經歷 **queued → uploading → building → deploying → running**，只有新版本開始處理流量後，platform 才會回報 **running**。

## 隔離環境資料

託管資料庫預設限定於單一環境，因此正式與測試環境會各自讀寫自己的資料庫：

```bash
mastra env db create production --kind turso --name my-project-production-db
mastra env db create staging --kind turso --name my-project-staging-db
```

若希望所有環境共用一個資料庫，請改用 `--shared` 附加：`mastra env db create --kind turso --shared`。

環境對每個 Provider 只能使用一個資料庫。若專案已有相同 Provider 的共用 (`--shared`) 資料庫，附加環境範圍資料庫會因變數名稱衝突而遭拒；請先以 `mastra env db delete` 刪除共用資料庫。刪除資料庫會連同 Provider 上的所有資料一起銷毀，因此請先匯出需要保留的內容。完整範圍模型請參閱[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)。

## 刪除環境

```bash
mastra env delete staging
```

CLI 會在刪除前要求確認。刪除環境會移除其部署與已儲存變數。

## 相關內容

- [Deploy](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy)
- [區域](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/regions)
- [託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)
- [`mastra env` CLI 參考](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)