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

# 設定

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

本頁說明這兩種機制。

## 專案設定

第一次執行 [`mastra deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 時，系統會自動產生 `.mastra-project.json`。它會將本機專案連結至 platform 專案。[GitHub 整合](https://mastra.zisheng.pro/zh-TW/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-TW/docs/mastra-platform/deploy) 會從三種來源解析變數：

- **受管理變數**：由[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)等 platform 資源注入。這些變數由 platform 定義，無法編輯。
- **已儲存變數**：透過控制面板儲存在專案或環境中。每次部署都會直接使用，不需要本機檔案。
- **本機 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 時寫入，並用於 platform 驗證。                                                                              |
| `MASTRA_PROJECT_ID`                      | Platform 專案的 UUID。`MastraPlatformExporter` 用它將 Observability 資料連結至 platform 專案。Studio 與 Server 部署會從 `.mastra-project.json` 讀取專案 ID。 |
| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` | 選用的 Observability 端點覆寫值。只有在本機開發 platform 時才會自動設定。預設為 `https://observability.mastra.ai`。                                             |
| `MASTRA_ORG_ID`                          | 覆寫 CLI 指令目前使用的組織。支援的指令也可透過 `--org` 旗標設定。                                                                                            |

`MastraPlatformExporter` 會讀取 `MASTRA_PLATFORM_ACCESS_TOKEN`，以驗證 platform 匯出作業。

## 多個環境

單一專案可在多個[環境](https://mastra.zisheng.pro/zh-TW/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
```

> **備註:** 舊版 platform 要求每個環境各自使用一個專案。現在 Environments 已取代該模式，因此請保留單一專案並部署至不同環境。