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

# 配置

部署至 Mastra platform 時，CLI 會產生 `.mastra-project.json` 配置檔案，並從平台以及你選擇使用的本機 `.env` 檔案解析環境變數。

本頁說明這兩種機制。

## 項目配置

首次執行 [`mastra deploy`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 時，系統會自動產生 `.mastra-project.json` 檔案。它會將你的本機項目連結至平台項目。[GitHub 整合](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/github)亦會將同一檔案寫入已連結的程式碼儲存庫。

請將它提交至版本控制，確保之後的部署（包括從 CI 進行的部署）會以正確的項目為目標。

檔案內容大致如下：

```json
{
  "projectId": "06daaac4-89b1-40f0-9e3f-0993e039a627",
  "projectName": "my-project",
  "organizationId": "org_01KNA5YSP52SX4M6YVSXC2MAHP"
}
```

| 欄位             | 說明                                |
| -------------- | --------------------------------- |
| projectId      | 項目的 UUID，在建立項目時指派。                |
| projectName    | 方便閱讀的項目名稱，在控制台及 CLI 輸出中用作顯示標籤。    |
| organizationId | 擁有項目的組織。所有部署、API 金鑰及資源的範圍均限定於此組織。 |

## 環境變數

本機 env 檔案並非必要。[`mastra deploy`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 會從三個來源解析變數：

- **受管理變數**：由[託管資料庫](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/database)等平台資源注入。這些變數由平台定義，你無法編輯。
- **已儲存變數**：透過控制台儲存在項目或環境中。每次部署時均會直接使用，無需本機檔案。
- **本機 env 檔案**：部署會在上述變數之上套用明確指定的 `--env-file`，或目前環境中的 `.env` 和 `.env.local` 檔案。`.env.local` 的變數會覆蓋 `.env` 中的變數。

如要指定部署使用某個 env 檔案，而非依賴預設選擇，請傳入 `--env-file`：

```bash
mastra deploy --env-file .env.production --yes
```

部署前請檢查並清理本機 env 檔案，以免上載只供開發使用的資料或個人秘密資料。

### Observability

以下環境變數用於配置 Mastra platform 上的 Observability 產品。

| 變數                                       | 說明                                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `MASTRA_PLATFORM_ACCESS_TOKEN`           | 範圍限定於組織的存取權杖。CLI 會在佈建 Observability 時寫入此值，並用它進行平台驗證。                                                                  |
| `MASTRA_PROJECT_ID`                      | 平台項目的 UUID。`MastraPlatformExporter` 會用它將 Observability 資料連結至平台項目。Studio 和 Server 部署會從 `.mastra-project.json` 讀取項目 ID。 |
| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` | 可選的 Observability 端點覆寫值。只有在本機進行平台開發時，系統才會自動設定此值。預設為 `https://observability.mastra.ai`。                                |
| `MASTRA_ORG_ID`                          | 覆寫 CLI 指令目前使用的組織。你亦可在支援的指令中使用 `--org` 旗標設定。                                                                           |

`MastraPlatformExporter` 會讀取 `MASTRA_PLATFORM_ACCESS_TOKEN`，以驗證向平台匯出資料的操作。

## 多個環境

單一項目可在多個[環境](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/environments)中執行同一程式碼庫，例如 `production` 和 `staging`。每個環境都有各自的 URL、已儲存變數和部署記錄。一個 `.mastra-project.json` 檔案已涵蓋所有環境：

```bash
mastra deploy --env production --yes
mastra deploy --env staging --env-file .env.staging --yes
```

> **備註:** 舊版平台要求每個環境使用一個項目。環境功能已取代此模式，因此請保留單一項目，並改為部署至不同環境。