VercelDeployer

VercelDeployer 类负责将独立的 Mastra 应用部署到 Vercel。它管理配置和部署，并在基础 Deployer 类的基础上扩展了 Vercel 特有的功能。

🌐 The VercelDeployer class handles deployment of standalone Mastra applications to Vercel. It manages configuration, deployment, and extends the base Deployer class with Vercel specific functionality.

warning

Vercel Functions 使用临时文件系统。请从你的 Mastra 配置中移除所有使用带有文件 URL 的 LibSQLStore 的情况。请使用内存存储（:memory:）或外部存储提供商，如 Turso、PostgreSQL 或 Upstash。

安装

🌐 Installation

npm

npm install @mastra/deployer-vercel@latest

pnpm

pnpm add @mastra/deployer-vercel@latest

Yarn

yarn add @mastra/deployer-vercel@latest

Bun

bun add @mastra/deployer-vercel@latest

使用示例

🌐 Usage example

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { VercelDeployer } from "@mastra/deployer-vercel";

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

有关所有可用的配置选项，请参见 VercelDeployer API 参考。

可选覆盖

🌐 Optional overrides

Vercel 部署器可以将一些高价值的设置写入 Vercel 输出 API 的函数配置（.vc-config.json）：

🌐 The Vercel deployer can write a few high‑value settings into the Vercel Output API function config (.vc-config.json):

• maxDuration?: number — 函数执行超时（秒）
• memory?: number — 函数内存分配 (MB)
• regions?: string[] — 地区（例如 ['sfo1','iad1']）

示例：

🌐 Example:

src/mastra/index.ts

deployer: new VercelDeployer({
  maxDuration: 600,
  memory: 1536,
  regions: ["sfo1", "iad1"],
});

持续集成

🌐 Continuous integration

在将你的 Mastra 项目的 Git 仓库连接到 Vercel 后，更新项目设置。在 Vercel 仪表板中，进入 设置 > 构建和部署，在 框架设置 下，进行如下设置：

🌐 After connecting your Mastra project’s Git repository to Vercel, update the project settings. In the Vercel dashboard, go to Settings > Build and Deployment, and under Framework settings, set the following:

• 构建命令：npm run build（可选）

环境变量

🌐 Environment variables

在你第一次部署之前，确保添加应用使用的任何环境变量。例如，如果你使用 OpenAI 作为 LLM，你需要在 Vercel 项目设置中设置 OPENAI_API_KEY。

🌐 Before your first deployment, make sure to add any environment variables used by your application. For example, if you're using OpenAI as the LLM, you'll need to set OPENAI_API_KEY in your Vercel project settings.

有关更多详情，请参见 环境变量。

你的项目现在已配置为自动部署，每当你将代码推送到 GitHub 仓库中配置的分支时，部署就会自动发生。

🌐 Your project is now configured with automatic deployments which occur whenever you push to the configured branch of your GitHub repository.

手动部署

🌐 Manual deployment

也可以使用 Vercel CLI 手动部署。安装 Vercel CLI 后，在项目根目录运行以下命令来部署你的应用。

🌐 Manual deployments are also possible using the Vercel CLI. With the Vercel CLI installed run the following from your project root to deploy your application.

npm run build && vercel --prod --prebuilt --archive=tgz

你也可以在项目根目录下运行 vercel dev 来本地测试你的 Mastra 应用。

构建输出

🌐 Build output

使用 VercelDeployer 构建 Mastra 应用的输出包括项目中的所有代理、工具和工作流，以及在 Vercel 上运行应用所需的 Mastra 特定文件。

🌐 The build output for Mastra applications using the VercelDeployer includes all agents, tools, and workflows in your project, along with Mastra specific files required to run your application on Vercel.

.vercel/
├── output/
│   ├── functions/
│   │   └── index.func/
│   │       └── index.mjs
│   └── config.json
└── package.json

VercelDeployer 会在 .vercel/output 中自动生成一个 config.json 配置文件，包含以下设置：

🌐 The VercelDeployer automatically generates a config.json configuration file in .vercel/output with the following settings:

{
  "version": 3,
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/"
    }
  ]
}

可观测性

🌐 Observability

要在 Vercel 上启用可观测性，请配置外部存储（因为 Vercel 的临时文件系统不支持本地文件存储）并设置你首选的导出器。

🌐 To enable observability on Vercel, configure external storage (since Vercel's ephemeral filesystem doesn't support local file storage) and set up your preferred exporter(s).

存储配置

🌐 Storage configuration

使用像 Neon 或 Supabase 这样的 PostgreSQL 提供程序进行持久化存储：

🌐 Use a PostgreSQL provider like Neon or Supabase for persistent storage:

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { PinoLogger } from "@mastra/loggers";
import { PostgresStore } from "@mastra/pg";
import { Observability, DefaultExporter, CloudExporter } from "@mastra/observability";

export const mastra = new Mastra({
  logger: new PinoLogger(),
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL!,
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: "my-mastra-app",
        exporters: [
          // Choose based on your observability platform:
          new DefaultExporter(), // Your storage → Mastra Studio
          new CloudExporter(),   // Mastra Cloud
          // new ArizeExporter(),   // Arize
          // new LaminarExporter(), // Laminar
          // etc.
        ],
      },
    },
  }),
  // ... agents, tools, workflows
});

请参阅追踪文档了解所有可用的导出器。

🌐 See the Tracing documentation for all available exporters.

环境变量

🌐 Environment variables

根据你的配置，将这些添加到你的 Vercel 项目设置中：

🌐 Add these to your Vercel project settings based on your configuration:

变量	描述
DATABASE_URL	PostgreSQL 连接字符串（存储必填）
MASTRA_CLOUD_ACCESS_TOKEN	使用 CloudExporter 时必填
OPENAI_API_KEY	你的 LLM 提供商 API 密钥

冲洗痕迹

🌐 Flushing traces

在无服务器环境中，调用 flush() 以确保在函数完成前导出跟踪：

🌐 In serverless environments, call flush() to ensure traces are exported before the function completes:

app/api/chat/route.ts

import { mastra } from "@/mastra";

export async function POST(req: Request) {
  const { message } = await req.json();
  const agent = mastra.getAgent("myAgent");

  const result = await agent.generate([{ role: "user", content: message }]);

  // Flush traces before the serverless function completes
  const observability = mastra.getObservability();
  await observability.flush();

  return Response.json(result);
}

有关跟踪配置的更多详细信息，请参阅跟踪文档。

🌐 For more details on tracing configuration, see the Tracing documentation.

下一步

🌐 Next steps

• Mastra 客户端 SDK