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

# 部署至 Mastra platform

[`mastra deploy`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra) 是將 Mastra 應用程式發佈至 [Mastra platform](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview) 的單一指令。

此指令會在納入任何內容前建置並驗證專案；第一次執行時也會建立 platform 專案與環境、進行部署、串流建置記錄，並在部署開始提供流量服務後列出公開 URL。

```bash
mastra deploy
```

> **備註:** 本頁說明統一部署流程。先前分開的指令 [`mastra server deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/server) 與 [`mastra studio deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/studio) 仍然可用，但建議使用 `mastra deploy`。

## 開始之前

你需要一個 [Mastra 應用程式](https://mastra.zisheng.pro/zh-TW/guides/getting-started/quickstart)及 [Mastra platform](https://projects.mastra.ai) 帳戶。如果尚未驗證身分，CLI 會在第一次使用時提示你登入。

本機 `.env` 檔案並非必要。部署時會直接使用儲存在 platform 上的環境變數，[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)等受管理資源也會注入自己的變數。只有想在其上疊加本機值時，才需傳入 `--env-file`。

## 第一次部署

1. 在專案目錄中執行：

   ```bash
   mastra deploy
   ```

   第一次執行時，CLI 會提示你建立 platform 專案（以 `package.json` 命名）與 `production` 環境。接受提示，或傳入 `--yes` 直接接受預設值而不確認。

2. CLI 會在發佈任何內容前執行部署前檢查。若儲存空間會回退至本機檔案路徑（在 platform 的暫時性檔案系統中無法留存），通常會阻擋部署：

   ```text
   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
   ```

   CLI 不會直接回報錯誤，而會讓你就地修正：

   ```text
   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)
   ```

   接受提示後，佈建只需幾秒；資料庫連線變數會自動注入部署，完全不必複製至 `.env` 檔案。若拒絕，或在非互動式 shell（CI、`--yes`）中執行，CLI 會回復先前的行為：列出要自行執行的確切指令。

   ```bash
   mastra env db create production --kind turso
   ```

   環境 slug（上述 `production`）會符合 CLI 原本要部署的環境。這一點很重要，因為專案有多個環境時，在非互動式 shell 中執行 `mastra env db create` 必須提供環境引數。

   > **備註:** 如果部署前檢查回報的是硬式編碼的本機路徑（`Build contains a host-local storage URL`），便無法提供就地修正。請先以環境變數保護路徑，讓該檔案只在本機開發期間使用：
   >
   > ```ts
   > new LibSQLStore({
   >   id: 'mastra-storage',
   >   // Uses the hosted database when deployed, a local file during development
   >   url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
   >   authToken: process.env.TURSO_AUTH_TOKEN,
   > })
   > ```

3. 再次執行 `mastra deploy`。通過部署前檢查後，建置會上傳，CLI 也會持續串流建置記錄，直到部署上線。完整建置和部署預計需時 30 秒至數分鐘。只有新版本開始提供流量服務後，才會列出成功訊息。

4. 使用 CLI 列出的 URL 驗證部署。附加 `/api/agents`，確認它會傳回 Agent 的 JSON 清單。

   > **警告:** 對外公開端點前，請先設定[驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth)。

第一次部署會寫入 `.mastra-project.json` 檔案，將你的目錄連結至 platform 專案。請提交此檔案，讓後續部署、CI 執行及 [`mastra env`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/environments) 指令不必提供額外旗標，也能指向同一專案。

## 部署至其他環境

`mastra deploy` 預設以 `production` 環境為目標。傳入 `--env` 可指定其他環境。如果環境尚不存在，CLI 會提示你建立：

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

每個環境都有各自的 URL 與環境變數，也可以擁有自己的[託管資料庫](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/database)。

如需完整模型，請參閱[環境](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/environments)。

## 選擇區域

部署建立新環境時，傳入 `--region` 可控制執行位置。請使用 `us` 或 `eu` 簡寫：

```bash
mastra deploy --env production --region eu
```

區域會在建立環境時固定。附加至環境的資料庫會自動放在靠近該環境區域的位置，可觀測性資料則會路由至符合環境資料駐留區域的擷取區域。如需支援區域、資料庫位置及可觀測性共置的完整清單，請參閱[區域](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/regions)。

## 部署前檢查

部署前檢查會在納入任何內容前驗證建置輸出，且只會標示自有程式碼中的問題：

- **本機儲存路徑**：會直接阻擋。每次部署都會遺失檔案型儲存空間（例如 `file:./mastra.db`）。若路徑由環境變數保護，且該變數已在本機設定、儲存於 platform，或由受管理資料庫提供，即可通過部署前檢查：

  ```ts
  import { LibSQLStore } from '@mastra/libsql'

  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })
  ```

- **缺少環境變數**：程式碼讀取的變數沒有任何來源提供時會顯示警告。只由程式庫程式碼參照的變數不包含在內。

遇到部署前檢查阻擋時，建議修正原因，通常是附加託管資料庫或將變數儲存至 platform。`--skip-preflight` 是緊急避用選項，但會略過用於防止部署失敗的檢查。

執行檢查但不部署：

```bash
mastra lint --preflight
```

`mastra lint` 只能讀取本機環境檔案，無法得知儲存在 platform 或由受管理資料庫注入的變數。因此，即使 lint 仍回報錯誤，部署仍可能通過部署前檢查。

## 環境變數

部署會從三個來源解析環境變數：

- **受管理變數**：由託管資料庫等 platform 資源注入（例如 `TURSO_DATABASE_URL`）。這些變數由 platform 定義，無法編輯。
- **已儲存變數**：透過控制面板儲存在專案或環境中。每次部署都會直接使用，不需要本機檔案。
- **本機環境檔案**：部署會在其上疊加明確指定的 `--env-file`，或目前的 `.env` 與 `.env.local` 檔案。

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

若要變更執行中服務的變數而不重新部署，請在控制面板更新後執行 [`mastra env restart`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)。

## 專案解析

每次部署都會依下列順序解析目標專案：

1. `MASTRA_PROJECT_ID` 環境變數
2. `--project <name|slug|id>` 旗標
3. 目前目錄中的 `.mastra-project.json` 檔案

在 CI 中，請設定 `MASTRA_PROJECT_ID` 和 `MASTRA_API_TOKEN`，並傳入 `--yes`：

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

## 相關內容

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