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

# Mastra platform 上的 Studio

Mastra platform 上的 Studio 是託管的視覺化 Workspace，可用來測試 Agent、執行 Workflow 及檢查 Trace。若想與團隊共用 Studio，又不想自行託管 Studio UI，請使用此服務。

你可以如下所示從 CLI 部署 Studio，也可以連結 GitHub 儲存庫以在推送時部署。儲存庫連結流程請參閱 [GitHub 整合](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/github)。

> **備註:** `mastra studio deploy` 是較早期的分開部署方式。新專案應使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 指令；它新增了部署前驗證、Environments，以及由 CLI 管理的資料庫。

## 快速開始

1. 依照[開始使用指南](https://mastra.zisheng.pro/zh-TW/docs)建立第一個 Mastra 專案。

2. 全域安裝 `mastra` CLI：

   **npm**:

   ```bash
   npm install -g mastra
   ```

   **pnpm**:

   ```bash
   pnpm add -g mastra
   ```

   **Yarn**:

   ```bash
   yarn global add mastra
   ```

   **Bun**:

   ```bash
   bun add --global mastra
   ```

3. 使用單一指令部署 Studio：

   ```bash
   mastra studio deploy
   ```

   部署成功後，CLI 會輸出已部署 Studio 執行個體的 URL。

第一次部署時，CLI 會提示你建立新專案或選取現有專案，接著在專案目錄中建立 `.mastra-project.json`。此檔案會將本機專案連結至 platform 專案，並包含 `projectId`、`projectName` 與 `organizationId`。請將它提交至儲存庫，讓 CI/CD 知道要部署至哪個專案。

## 部署的運作方式

`mastra studio deploy` 指令會建置專案，並將 `src/mastra/` 編譯至 `.mastra/output`。接著把輸出封裝為成品 ZIP，然後上傳並部署至雲端 Sandbox。

部署會依序經歷 **queued → uploading → starting → running**；若發生問題則進入 **failed**。若專案已有執行中的 Sandbox，platform 會就地更新且不造成停機；否則會建立新的 Sandbox。執行個體 URL 依專案 slug 指派，並在各次部署間保持不變。

完整旗標清單與 CI/CD 用法請參閱 [`mastra studio deploy` CLI 參考](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)。

## 環境檔案

本機 env 檔案並非必要。專案目錄中有 `.env` 或 `.env.*` 時，部署會封裝其中的環境變數。

有多個 env 檔案時，CLI 會提示你選擇。若要以非互動方式選取，請傳入 `--env-file`：

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

若要讓相同程式碼在 `production` 與 `staging` 中執行，請改用統一的 [`mastra deploy --env`](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/deploy) 指令。[Environments](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/environments) 已取代每個環境各用一個專案的舊模式。

## 以非互動方式建立新專案

`mastra studio deploy` 可在第一次執行時建立專案。若 `--project <name>` 與任何現有專案都不相符，CLI 會將該值用作新專案名稱，並在確認後建立專案。搭配 `--yes` 即可完全以指令碼執行：

```bash
mastra studio deploy --project "my-new-project" --yes
```

在 CI 或 AI 程式設計 Agent 中，請使用此方式，而不是只能互動操作的 `mastra studio projects create`。

## 自行託管 Studio

若要在自己的基礎架構上部署 Studio，請參閱 [Studio 部署](https://mastra.zisheng.pro/zh-TW/docs/studio/deployment)。

## 相關內容

- [`mastra studio deploy`](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)