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

# Mastra platform 上的 Studio

Mastra platform 上的 Studio 是一個託管的視覺化 Workspace，可用於測試 Agent、執行 Workflow，以及檢查 Trace。如果你希望與團隊共享 Studio，而毋須自行託管 Studio UI，便可使用此服務。

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

> **備註:** `mastra studio deploy` 是較早期的分拆部署路徑。新項目應使用統一的 [`mastra deploy`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 指令；此指令新增了部署前驗證、環境，以及由 CLI 管理的數據庫。

## 快速開始

1. 按照[入門指南](https://mastra.zisheng.pro/zh-HK/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，過程不會中斷服務。否則，platform 會建立全新的 Sandbox。執行個體 URL 會按項目 slug 指派，並在多次部署之間保持不變。

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

## 環境檔案

本機環境檔案並非必要。如果項目目錄中有 `.env` 或 `.env.*` 檔案，部署時便會一併封裝當中的環境變數。

如果有多個環境檔案，CLI 會提示你選擇其中一個。如要在非互動模式下選取，請傳入 `--env-file`：

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

如要讓同一程式碼庫在 `production` 和 `staging` 環境運行，請改用統一的 [`mastra deploy --env`](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/deploy) 指令。[環境](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/environments)取代了以往每個環境使用一個項目的做法。

## 以非互動方式建立新項目

`mastra studio deploy` 可在首次執行時建立項目。如果 `--project <name>` 與任何現有項目不符，CLI 會將該值用作新項目名稱，並在確認後建立項目。配合 `--yes` 使用時，整個流程均可編寫成指令碼：

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

在 CI 或 AI 編程助手中，請使用此方式，而非只支援互動模式的 `mastra studio projects create`。

## 自行託管 Studio

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

## 相關內容

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