Mastra server

Mastra 会将你的应用编译为独立的 Node.js 服务器，可在任何支持 Node.js、Bun 或 Deno 的平台上运行。

提示

本指南介绍如何部署 mastra build 生成的独立服务器。如果你需要将 Mastra 集成到现有的 Express 或 Hono 应用中，请参阅服务端适配器。

构建应用

在项目根目录运行构建命令：

mastra build

这会创建一个包含生产就绪服务器的 .mastra 目录。所有可用参数请参阅 mastra build 参考。

构建输出

构建完成后，Mastra 会创建以下结构：

.mastra/
├── .build/                # Intermediate build artifacts (module maps, analysis)
└── output/
    ├── index.mjs          # Server entry point
    ├── mastra.mjs         # Your bundled Mastra configuration
    ├── tools.mjs          # Aggregated tool exports
    ├── tools/             # Individual tool bundles
    ├── package.json       # Production dependencies
    ├── node_modules/      # Installed dependencies
    ├── .npmrc             # Copied from your project (if present)
    ├── public/            # Static assets (if src/mastra/public exists)
    └── playground/        # Studio UI (if --studio flag used)

output 目录是自包含的。你可以将其复制到任意服务器并直接运行。

运行服务器

使用 Mastra CLI 启动服务器：

mastra start

或直接使用 Node.js 运行：

node .mastra/output/index.mjs

mastra start 命令提供额外功能：

• 从 .env.production 和 .env 加载环境变量
• 为缺失的模块提供有用的错误信息
• 处理进程信号以实现优雅关闭

所有可用参数请参阅 mastra start 参考。

构建配置

构建时配置

Mastra 在构建应用时会读取 bundler、deployer 和 server 选项。请将这些选项保留为传给 new Mastra() 的对象的直接属性，以便构建过程能够提取它们。

以下入口文件形式可以正常工作：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})

每个选项的值可以来自变量、导入或函数调用。选项本身必须保持为直接属性。不要将构建时选项隐藏在工厂调用或对象展开之后：

src/mastra/index.ts

const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })

当 Mastra 无法提取某个选项时，会使用该选项的默认构建行为。可用的 bundler、deployer 和 server 设置请参阅配置参考。

公共文件夹

如果 Mastra 目录中存在 public 文件夹（src/mastra/public），其内容会在构建期间复制到输出目录。这些文件会由服务器作为静态资源提供。

Mastra 配置

构建过程会遵循 Mastra 实例中的配置。有关 CORS、超时和中间件等服务端行为，请参阅服务器概览。所有可用选项请参阅配置参考。

构建过程

构建会执行以下步骤：

1. 定位入口文件：在 Mastra 目录中查找 index.ts 或 index.js。
2. 发现工具：扫描匹配 {mastraDir}/tools/**/*.{js,ts} 的工具文件，排除测试文件。
3. 分析依赖：确定哪些包需要打包，哪些需要在外部安装。
4. 打包代码：使用 Rollup 进行 tree-shaking，并可选择生成 source map。
5. 生成服务器：创建基于 Hono 的 HTTP 服务器，输出为 index.mjs。
6. 安装依赖：在输出目录中运行 npm install。
7. 复制资源：如存在 public 文件夹和 .npmrc，则一并复制。

环境变量

变量	描述
PORT	服务器端口（默认：4111）
MASTRA_STUDIO_PATH	Studio 构建目录的路径（默认：./playground）
MASTRA_SKIP_DOTENV	设置后跳过加载 .env 文件
NODE_OPTIONS	Node.js 选项（例如构建内存不足时使用 --max-old-space-size=4096）

服务器端点

构建后的服务器暴露用于健康检查、agents、workflows 等的端点：

端点	描述
GET /health	健康检查端点，返回 200 OK
GET /api/openapi.json	OpenAPI 规范（如果启用了 server.build.openAPIDocs）。
GET /swagger-ui	交互式 API 文档（如果启用了 server.build.swaggerUI）

此列表并不完整。要查看所有端点，请运行 mastra dev 并访问 http://localhost:4111/swagger-ui。

要添加自己的端点，请参阅自定义 API 路由。

优雅关闭与滚动部署

默认情况下，生成的服务器会处理 SIGINT 和 SIGTERM。它会停止接受连接，最多等待 server.drainTimeout 让活动请求和流完成，然后运行 mastra.shutdown()。关闭过程会为正在运行的工作流运行（包括持久化 agent 运行）提供相同的排空窗口，以便在拆除工作进程和 pub/sub 订阅之前完成。如果持久化 agent 运行在窗口结束后仍在执行，它会停止并释放对该运行的占用，从而下一次启动可以立即恢复它。排空超时默认为 5 秒。第二次信号会立即终止进程。如果你需要自行管理信号，请参阅 server.handleShutdownSignals。

当托管平台的终止宽限期可以容纳更长的轮次时，请增加 drainTimeout。HTTP 排空和工作流排空会依次执行，因此请为两者以及关闭清理留出足够时间。

如果你自行调用 mastra.shutdown()，请传入 drainTimeout 以控制等待正在运行的工作流运行的时间：

await mastra.shutdown({ drainTimeout: 30_000 })

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  server: {
    drainTimeout: 240_000,
  },
})

普通的 agent.stream() 调用在服务器进程退出后无法恢复。如果某个流在没有预期终止事件的情况下结束，请将该轮次视为已中断，并让客户端重试或进行核对。当轮次必须在进程替换后继续存活时，请使用持久化 agents。崩溃恢复需要共享的持久化运行存储和幂等工具。重启后重放错过的事件还需要共享的持久化缓存（例如 Redis），因为默认事件缓存是内存中的。从多个副本恢复需要支持运行围栏（run fencing）的存储适配器，或需要每个副本共享其租约的 PubSub 后端。参见多实例部署。

故障排查

构建期间的内存错误

如果遇到 JavaScript heap out of memory 错误：

NODE_OPTIONS="--max-old-space-size=4096" mastra build

相关内容

• Server Overview：配置服务器行为、中间件和认证
• Server Adapters：使用 Express 或 Hono 代替 mastra build
• Custom API Routes：添加自定义 HTTP 端点
• Durable Agents：持久化 agent 运行，使其在进程重启后继续存活
• Configuration Reference：完整配置选项