跳到主要内容

将 Mastra 部署到 Vercel

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

信息

本指南介绍如何部署 Mastra Server。如果你使用的是 Server 适配器或 Web 框架，请按该框架的常规方式进行部署。

开始之前
开始之前的直接链接

你需要一个 Mastra 应用和一个 Vercel 账户。

注意

Vercel Functions 使用临时文件系统，因此配置的所有 Storage（包括 observability Storage）都必须在外部托管。如果你将 LibSQLStore 与文件 URL 配合使用，请改用远程托管的数据库。

安装
安装的直接链接

将 @mastra/deployer-vercel 包添加到项目：

npm install @mastra/deployer-vercel@latest

导入 VercelDeployer，并在 Mastra 配置中将其设置为 deployer：

src/mastra/index.ts
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 API Key）。

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

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

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

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

    注意

    在公开暴露端点之前，请设置身份验证。

Studio
Studio的直接链接

启用 studio 选项，即可将 Studio 与 API 一同部署。Studio 会部署为由 Vercel Edge CDN 提供的静态资源，因此不会消耗函数调用次数。

src/mastra/index.ts
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() 添加的路由仍可通过各自路径访问。请避免为自定义路由设置 Studio 已使用的路径（例如 /agents 或 /workflows），因为 Studio 会优先占用这些路径。

注意

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

可选覆盖配置
可选覆盖配置的直接链接

Vercel deployer 支持写入 Vercel Output API 函数配置的选项。有关 maxDuration、memory 和 regions 等可用选项，请参阅 VercelDeployer Reference。

Observability
Observability的直接链接

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

api/chat.ts
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，在返回响应前添加相应逻辑。也可以部署到虚拟机等长时运行的 Server 上，这样便不存在该问题。

On this page