Studio 部署

Studio 是一個以 React 為基礎的單頁應用程式（SPA），在瀏覽器中運行，並連接至正在運行的 Mastra 伺服器。

部署 Studio 主要有兩種方式：

Mastra 平台為你提供託管的 Studio，並讓你透過連結與團隊分享存取權限
在自己的基礎設施上自行託管 Studio，可以與 Mastra 伺服器一同部署，也可以作為獨立 SPA 分開部署

本頁將說明如何在自己的基礎設施上部署 Studio。由於部署細節會因你的需求和設定而有很大差異，我們將介紹適用的一般原則和可用選項。

快速開始
快速開始的直接連結

運行 Studio 最簡單的方法是使用 mastra studio 命令。

mastra dev 會同時運行 Studio 和用於開發的 API，而 mastra studio 則用來提供獨立的靜態 UI，並連接至已在運行的 Mastra 伺服器。你可以按需要單獨部署 Studio，與 Mastra 伺服器分開運行。

開啟終端機，並在全域安裝 mastra CLI：

npm
pnpm
Yarn
Bun

npm install -g mastra

pnpm add -g mastra

yarn global add mastra

bun add --global mastra

運行 mastra studio 命令：

mastra studio

在瀏覽器中開啟 localhost:3000 以查看 Studio UI。預設情況下，它會嘗試連接至在 http://localhost:4111 運行的 Mastra 伺服器。如果在該位置找不到伺服器，你會看到一份表單，可在當中輸入 Mastra 執行個體 URL 和 API 前綴。

此命令使用 Node 內置的 http 模組和 serve-handler 來提供靜態檔案。

備註

如果你在子路徑下託管 Studio（例如置於 Nginx 後方的 /agents），請在啟動 Studio 前設定 MASTRA_STUDIO_BASE_PATH：

MASTRA_STUDIO_BASE_PATH=/agents mastra studio

這會更新 HTML 基礎 URL 和靜態資源路由，讓獨立的 Studio 能在該子路徑下正常運作。

Mastra 平台
Mastra 平台的直接連結

如需了解 Mastra 平台上託管的 Studio，請參閱 Mastra 平台上的 Studio。

運行伺服器
運行伺服器的直接連結

將 mastra studio 作為長期運行的程序，與運行任何其他 Node.js 服務並無分別。所有部署最佳實務、工具和選項亦同樣適用。你可以使用 PM2 等程序管理器、Docker，或支援 Node.js 應用程式的雲端服務。與任何網絡服務一樣，你需要確保 CORS 設定正確，並監察錯誤。

注意

Studio 連接至 Mastra 伺服器後，便可完整存取你的 Agent、Workflow 和 Tool。請確保在正式環境中妥善保護 Studio（例如設於身分驗證、VPN 等機制後方），以防止未經授權的存取。

請瀏覽身分驗證文件以了解詳情。

與 API 一同部署
與 API 一同部署的直接連結

你亦可以在提供 Mastra 伺服器的同時提供 Studio。這樣便只需部署和管理一項服務。

要這樣做，請使用 --studio 旗標運行 mastra build：

mastra build --studio

它會建立 .mastra/output/studio 資料夾，當中包含已建置的 Studio 資源。定義 MASTRA_STUDIO_PATH 環境變數後，Mastra 伺服器亦可提供 Studio UI。

MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs

使用 CDN
使用 CDN 的直接連結

自動部署
自動部署的直接連結

部分雲端 Provider提供將 Studio 與無伺服器函數一同部署的選項。目前支援的 Provider 包括：

VercelDeployer

手動部署
手動部署的直接連結

你無法直接將已建置的 Studio 資源部署至 CDN，因為 UI 依賴部分執行階段設定。只需進行一些額外設定，便可利用已建置的資源建立獨立 SPA，並將它部署至任何靜態託管服務。

按照以下範例，使用 Vite 建立 SPA。

建立新資料夾，並初始化新的 Node.js 項目：

npm
pnpm
Yarn
Bun

mkdir studio-spa
cd studio-spa
npm init

mkdir studio-spa
cd studio-spa
pnpm init

mkdir studio-spa
cd studio-spa
yarn init

mkdir studio-spa
cd studio-spa
bun init

安裝 vite 和 mastra 作為依賴套件：

npm
pnpm
Yarn
Bun

npm install vite mastra

pnpm add vite mastra

yarn add vite mastra

bun add vite mastra

在 package.json 中加入建置腳本：

package.json
{
  "scripts": {
    "build": "vite build"
  }
}

建立預留位置 index.html 檔案：

index.html
<!doctype html>
<html>
  <head></head>
  <body></body>
</html>

建立 vite.config.js 檔案。它會將已建置的 Studio 資源複製至 dist 資料夾，並以環境變數值取代 HTML 中的任何 %%PLACEHOLDER%% 值。

vite.config.js
import { defineConfig, loadEnv } from 'vite'
import { readFileSync, cpSync, writeFileSync } from 'node:fs'
import { resolve, join } from 'node:path'

const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'MASTRA_')

  return {
    plugins: [
      {
        name: 'mastra-studio',
        closeBundle() {
          const outDir = resolve(import.meta.dirname, 'dist')
          cpSync(studioDir, outDir, { recursive: true })

          const indexPath = join(outDir, 'index.html')
          const html = readFileSync(indexPath, 'utf-8')
          writeFileSync(
            indexPath,
            html.replaceAll(/%%(\w+)%%/g, (_, key) => env[key] ?? ''),
          )
        },
      },
    ],
    build: {
      emptyOutDir: true,
    },
  }
})

建立包含所需環境變數的 .env 檔案。

.env
MASTRA_SERVER_HOST=localhost
MASTRA_SERVER_PORT=4111
MASTRA_SERVER_PROTOCOL=http
MASTRA_API_PREFIX=/api
MASTRA_HIDE_CLOUD_CTA=false
MASTRA_CLOUD_API_ENDPOINT=
MASTRA_EXPERIMENTAL_FEATURES=false
MASTRA_TEMPLATES=false
MASTRA_TELEMETRY_DISABLED=true
MASTRA_REQUEST_CONTEXT_PRESETS=
MASTRA_THEME_TOGGLE=false
MASTRA_EXPERIMENTAL_UI=false
MASTRA_STUDIO_BASE_PATH=

運行建置腳本，在 dist 資料夾中產生靜態檔案：
- npm
- pnpm
- Yarn
- Bun
npm run build
pnpm run build
yarn build
bun run build
將託管 Provider 指向 dist 資料夾，然後部署！

快速開始快速開始 的直接連結

Mastra 平台Mastra 平台 的直接連結

運行伺服器運行伺服器 的直接連結

與 API 一同部署與 API 一同部署 的直接連結

使用 CDN使用 CDN 的直接連結

自動部署自動部署 的直接連結

手動部署手動部署 的直接連結