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

# Mastra platform 上的 Studio

Mastra platform 上的 Studio 是一个托管的可视化 Workspace，可用于测试 Agent、运行 Workflow 和检查 Trace。当你希望与团队共享 Studio，但不想自行托管 Studio UI 时，请使用它。

你可以按下文所示通过 CLI 部署 Studio，也可以关联 GitHub 仓库以实现推送时部署。有关关联仓库的流程，请参阅 [GitHub 集成](https://mastra.zisheng.pro/docs/mastra-platform/github)。

> **备注:** `mastra studio deploy` 是早期拆分的部署路径。新项目应使用统一的 [`mastra deploy`](https://mastra.zisheng.pro/docs/mastra-platform/deploy) 命令，该命令增加了部署前验证、环境和由 CLI 管理的数据库。

## 快速入门

1. 按照[入门指南](https://mastra.zisheng.pro/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`。随后，它将输出打包为 artifact ZIP，再上传并部署到云端 Sandbox。

部署会依次经过 **queued → uploading → starting → running**；如果出现问题，则进入 **failed** 状态。如果项目已有正在运行的 Sandbox，platform 会原地更新，且不会停机。否则，它会创建新的 Sandbox。实例 URL 根据项目 slug 分配，并在不同部署间保持不变。

有关完整标志列表和 CI/CD 用法，请参阅 [`mastra studio deploy` CLI Reference](https://mastra.zisheng.pro/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/docs/mastra-platform/deploy) 命令。[环境](https://mastra.zisheng.pro/docs/mastra-platform/environments)取代了早期每个环境使用一个项目的模式。

## 以非交互方式创建新项目

`mastra studio deploy` 可以在首次运行时创建项目。如果 `--project <name>` 与现有项目不匹配，CLI 会将该值用作新项目名称，并在确认后创建项目。与 `--yes` 结合使用时，可完全通过脚本运行：

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

请在 CI 或 AI coding Agent 中使用这种方式，而不是只能交互运行的 `mastra studio projects create`。

## 自行托管 Studio

如需在自己的基础设施上部署 Studio，请参阅 [Studio 部署](https://mastra.zisheng.pro/docs/studio/deployment)。

## 相关内容

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