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

# 将 Mastra 部署到 Vercel

使用 `@mastra/deployer-vercel` 将 Mastra Server 作为 Serverless Function 部署到 Vercel。该 deployer 会打包代码并生成符合 Vercel [Build Output API](https://vercel.com/docs/build-output-api/v3) 的 `.vercel/output` 目录，无需额外配置即可部署。

> **信息:** 本指南介绍如何部署 [Mastra Server](https://mastra.zisheng.pro/docs/server/mastra-server)。如果你使用的是 [Server 适配器](https://mastra.zisheng.pro/docs/server/server-adapters)或 [Web 框架](https://mastra.zisheng.pro/docs/deployment/web-framework)，请按该框架的常规方式进行部署。

## 开始之前

你需要一个 [Mastra 应用](https://mastra.zisheng.pro/guides/getting-started/quickstart)和一个 [Vercel](https://vercel.com/) 账户。

> **注意:** Vercel Functions 使用临时文件系统，因此配置的所有 Storage（包括 observability Storage）都必须在外部托管。如果你将 [LibSQLStore](https://mastra.zisheng.pro/reference/storage/libsql) 与文件 URL 配合使用，请改用远程托管的数据库。

## 安装

将 `@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/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": "mastra build"` 添加到 `package.json`。

   > **备注:** 请设置运行应用所需的环境变量（例如[模型 Provider](https://mastra.zisheng.pro/models/providers) API Key）。

2. 准备就绪后，单击 **Deploy（部署）**，等待首次部署完成。

3. 访问 `https://<your-project>.vercel.app/api/agents` 验证部署；该端点应返回 Agent 的 JSON 列表。

   由于 Mastra Server 会为每个端点添加 `/api` 前缀，因此发出请求时必须将其添加到 URL 中。

4. 现在可以通过 HTTP 调用 Mastra 端点。

   > **注意:** 在公开暴露端点之前，请设置[身份验证](https://mastra.zisheng.pro/docs/server/auth)。

## Studio

启用 `studio` 选项，即可将 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 与 API 一同部署。Studio 会部署为由 Vercel Edge CDN 提供的静态资源，因此不会消耗函数调用次数。

```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 提供自身页面，其他所有路径都转到 Server，因此使用 [`registerApiRoute()`](https://mastra.zisheng.pro/docs/server/custom-api-routes) 添加的路由仍可通过各自路径访问。请避免为自定义路由设置 Studio 已使用的路径（例如 `/agents` 或 `/workflows`），因为 Studio 会优先占用这些路径。

> **注意:** Studio 连接到 Mastra Server 后，便能完全访问 Agent、Workflow 和 Tool。在生产环境中，请务必采取适当的安全保护措施（例如置于身份验证或 VPN 之后），防止未经授权的访问。

## 可选覆盖配置

Vercel deployer 支持写入 Vercel Output API 函数配置的选项。有关 `maxDuration`、`memory` 和 `regions` 等可用选项，请参阅 [`VercelDeployer` Reference](https://mastra.zisheng.pro/reference/deployer/vercel)。

## Observability

Serverless Function 可能会在返回响应后立即终止。所有待处理的异步工作（例如发送遥测数据）都可能在完成前被中止。等待 `flush()` 可以确保在函数退出前发送所有 Trace。

```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/guides/deployment/digital-ocean)等长时运行的 Server 上，这样便不存在该问题。

## 相关内容

- [VercelDeployer Reference](https://mastra.zisheng.pro/reference/deployer/vercel)
- [部署概览](https://mastra.zisheng.pro/docs/deployment/overview)
- [Server 适配器](https://mastra.zisheng.pro/docs/server/server-adapters)
- [Web 框架集成](https://mastra.zisheng.pro/docs/deployment/web-framework)