> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt # Studio 部署 Studio 是一個以 React 為基礎的單頁應用程式（SPA），在瀏覽器中運行，並連接至正在運行的 [Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)。 部署 Studio 主要有兩種方式： - Mastra 平台為你提供託管的 Studio，並讓你透過連結與團隊分享存取權限 - 在自己的基礎設施上自行託管 Studio，可以與 Mastra 伺服器一同部署，也可以作為獨立 SPA 分開部署 本頁將說明如何在自己的基礎設施上部署 Studio。由於部署細節會因你的需求和設定而有很大差異，我們將介紹適用的一般原則和可用選項。 ## 快速開始 運行 Studio 最簡單的方法是使用 [`mastra studio`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra) 命令。 `mastra dev` 會同時運行 Studio 和用於開發的 API，而 `mastra studio` 則用來提供獨立的靜態 UI，並連接至已在運行的 Mastra 伺服器。你可以按需要單獨部署 Studio，與 Mastra 伺服器分開運行。 開啟終端機，並在全域安裝 `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 ``` 運行 `mastra studio` 命令： ```bash mastra studio ``` 在瀏覽器中開啟 [localhost:3000](http://localhost:3000) 以查看 Studio UI。預設情況下，它會嘗試連接至在 `http://localhost:4111` 運行的 Mastra 伺服器。如果在該位置找不到伺服器，你會看到一份表單，可在當中輸入 Mastra 執行個體 URL 和 API 前綴。 此命令使用 Node 內置的 `http` 模組和 [`serve-handler`](https://www.npmjs.com/package/serve-handler) 來提供靜態檔案。 > **備註:** 如果你在子路徑下託管 Studio（例如置於 Nginx 後方的 `/agents`），請在啟動 Studio 前設定 `MASTRA_STUDIO_BASE_PATH`： > > ```bash > MASTRA_STUDIO_BASE_PATH=/agents mastra studio > ``` > > 這會更新 HTML 基礎 URL 和靜態資源路由，讓獨立的 Studio 能在該子路徑下正常運作。 ## Mastra 平台 如需了解 Mastra 平台上託管的 Studio，請參閱 [Mastra 平台上的 Studio](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/studio)。 ## 運行伺服器 將 `mastra studio` 作為長期運行的程序，與運行任何其他 Node.js 服務並無分別。所有部署最佳實務、工具和選項亦同樣適用。你可以使用 PM2 等程序管理器、Docker，或支援 Node.js 應用程式的雲端服務。與任何網絡服務一樣，你需要確保 CORS 設定正確，並監察錯誤。 > **注意:** Studio 連接至 Mastra 伺服器後，便可完整存取你的 Agent、Workflow 和 Tool。請確保在正式環境中妥善保護 Studio（例如設於身分驗證、VPN 等機制後方），以防止未經授權的存取。 > > 請瀏覽[身分驗證](https://mastra.zisheng.pro/zh-HK/docs/studio/auth)文件以了解詳情。 ### 與 API 一同部署 你亦可以在提供 [Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)的同時提供 Studio。這樣便只需部署和管理一項服務。 要這樣做，請使用 `--studio` 旗標運行 `mastra build`： ```bash mastra build --studio ``` 它會建立 `.mastra/output/studio` 資料夾，當中包含已建置的 Studio 資源。定義 `MASTRA_STUDIO_PATH` 環境變數後，Mastra 伺服器亦可提供 Studio UI。 ```bash MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs ``` ## 使用 CDN ### 自動部署 部分[雲端 Provider](https://mastra.zisheng.pro/zh-HK/docs/deployment/cloud-providers)提供將 Studio 與無伺服器函數一同部署的選項。目前支援的 Provider 包括： - [`VercelDeployer`](https://mastra.zisheng.pro/zh-HK/reference/deployer/vercel) ### 手動部署 你無法直接將已建置的 Studio 資源部署至 CDN，因為 UI 依賴部分執行階段設定。只需進行一些額外設定，便可利用已建置的資源建立獨立 SPA，並將它部署至任何靜態託管服務。 按照以下範例，使用 Vite 建立 SPA。 1. 建立新資料夾，並初始化新的 Node.js 項目： **npm**: ```bash mkdir studio-spa cd studio-spa npm init ``` **pnpm**: ```bash mkdir studio-spa cd studio-spa pnpm init ``` **Yarn**: ```bash mkdir studio-spa cd studio-spa yarn init ``` **Bun**: ```bash mkdir studio-spa cd studio-spa bun init ``` 2. 安裝 `vite` 和 `mastra` 作為依賴套件： **npm**: ```bash npm install vite mastra ``` **pnpm**: ```bash pnpm add vite mastra ``` **Yarn**: ```bash yarn add vite mastra ``` **Bun**: ```bash bun add vite mastra ``` 3. 在 `package.json` 中加入建置腳本： ```json { "scripts": { "build": "vite build" } } ``` 4. 建立預留位置 `index.html` 檔案： ```html ``` 5. 建立 `vite.config.js` 檔案。它會將已建置的 Studio 資源複製至 `dist` 資料夾，並以環境變數值取代 HTML 中的任何 `%%PLACEHOLDER%%` 值。 ```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, }, } }) ``` 6. 建立包含所需環境變數的 `.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= ``` 7. 運行建置腳本，在 `dist` 資料夾中產生靜態檔案： **npm**: ```bash npm run build ``` **pnpm**: ```bash pnpm run build ``` **Yarn**: ```bash yarn build ``` **Bun**: ```bash bun run build ``` 8. 將託管 Provider 指向 `dist` 資料夾，然後部署！