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

# 將 Mastra 部署至 Vercel

使用 `@mastra/deployer-vercel`，將 Mastra 伺服器以 serverless function 方式部署至 Vercel。deployer 會將程式碼打包，並產生符合 Vercel [Build Output API](https://vercel.com/docs/build-output-api/v3) 的 `.vercel/output` 目錄，無需額外配置即可部署。

> **資訊:** 本指南說明如何部署 [Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-server)。如果你使用[伺服器 adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters) 或[網絡框架](https://mastra.zisheng.pro/zh-HK/docs/deployment/web-framework)，請按該框架的慣常方式部署。

## 開始之前

你需要一個 [Mastra 應用程式](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)及一個 [Vercel](https://vercel.com/) 帳戶。

> **注意:** Vercel Functions 使用臨時檔案系統，因此你配置的任何儲存空間（包括可觀測性儲存空間）都必須在外部託管。如果你使用採用檔案 URL 的 [LibSQLStore](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)，請改用遠端託管的資料庫。

## 安裝

將 `@mastra/deployer-vercel` 套件加入你的項目：

**npm**:

```bash
npm install @mastra/deployer-vercel@latest
```

**pnpm**:

```bash
pnpm add @mastra/deployer-vercel@latest
```

**Yarn**:

```bash
yarn add @mastra/deployer-vercel@latest
```

**Bun**:

```bash
bun add @mastra/deployer-vercel@latest
```

匯入 [`VercelDeployer`](https://mastra.zisheng.pro/zh-HK/reference/deployer/vercel)，並在 Mastra 配置中將其設為 deployer：

```typescript
import { Mastra } from '@mastra/core'
import { VercelDeployer } from '@mastra/deployer-vercel'

export const mastra = new Mastra({
  deployer: new VercelDeployer(),
})
```

## 部署

1. 將項目推送至遠端 Git Provider（例如 GitHub），並將程式碼庫連接至 Vercel。

   Vercel 預設會運行 `npm run build`，從而觸發 `mastra build`。如果你沒有 build script，請將 `"build": "mastra build"` 加入 `package.json`。

   > **備註:** 請記得設定應用程式運行所需的環境變數（例如[模型 Provider](https://mastra.zisheng.pro/zh-HK/models/providers) 的 API 金鑰）。

2. 準備好後，按一下 **部署**，並等待首次部署完成。

3. 在 `https://<your-project>.vercel.app/api/agents` 驗證部署；該 URL 應傳回 Agent 的 JSON 清單。

   由於 Mastra 伺服器會在每個端點前加上 `/api`，提出請求時必須將它加入 URL。

4. 你現在可以透過 HTTP 調用 Mastra 端點。

   > **注意:** 公開端點前，請先設定[驗證](https://mastra.zisheng.pro/zh-HK/docs/server/auth)。

## Studio

啟用 `studio` 選項，即可在部署 API 的同時部署 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)。Studio 會部署為由 Vercel Edge CDN 提供的靜態資源，因此不會佔用 function invocation。

```typescript
import { Mastra } from '@mastra/core'
import { VercelDeployer } from '@mastra/deployer-vercel'

export const mastra = new Mastra({
  deployer: new VercelDeployer({
    studio: true,
  }),
})
```

部署後，可透過根 URL (`https://<your-project>.vercel.app/`) 存取 Studio，而 API 則仍位於 `/api/*`。Studio 會自動連接同源 API，因此你不需要額外設定環境變數。

Studio 會從 CDN 提供其本身的頁面，而所有其他路徑都會前往你的伺服器，因此使用 [`registerApiRoute()`](https://mastra.zisheng.pro/zh-HK/docs/server/custom-api-routes) 加入的 route 仍可透過其本身的路徑存取。請避免為自訂 route 指定 Studio 已使用的路徑（例如 `/agents` 或 `/workflows`），因為 Studio 會優先使用這些路徑。

> **注意:** Studio 連接 Mastra 伺服器後，便可完整存取你的 Agent、Workflow 及 Tool。請務必在正式環境中妥善保護 Studio（例如置於驗證機制或 VPN 等之後），以防止未經授權的存取。

## 選用覆寫設定

Vercel deployer 支援寫入 Vercel Output API function 配置的選項。有關 `maxDuration`、`memory` 和 `regions` 等可用選項，請參閱 [`VercelDeployer` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/deployer/vercel)。

## 可觀測性

Serverless function 可在傳回回應後立即終止。任何待處理的非同步工作（例如傳送 telemetry）都可能在完成前被終止。等待 `flush()` 完成可確保所有 Trace 都在 function 結束前送出。

```typescript
import type { VercelRequest, VercelResponse } from '@vercel/node'
import { mastra } from '../src/mastra'

export default async function handler(req: VercelRequest, res: VercelResponse) {
  const { message } = req.body
  const agent = mastra.getAgent('myAgent')
  const result = await agent.generate([{ role: 'user', content: message }])

  await mastra.observability.flush()

  return res.json(result)
}
```

> **注意:** Vercel deployer 不包含 `flush` 調用。如有需要，你必須自行包裝 handler，在傳回回應前加入相關邏輯。另一做法是部署至長時間運行的伺服器，例如不存在此問題的[虛擬機器](https://mastra.zisheng.pro/zh-HK/guides/deployment/digital-ocean)。

## 相關內容

- [VercelDeployer 參考資料](https://mastra.zisheng.pro/zh-HK/reference/deployer/vercel)
- [部署概覽](https://mastra.zisheng.pro/zh-HK/docs/deployment/overview)
- [伺服器 adapter](https://mastra.zisheng.pro/zh-HK/docs/server/server-adapters)
- [網絡框架整合](https://mastra.zisheng.pro/zh-HK/docs/deployment/web-framework)