Skip to main content

部署 Mastra 服务器

🌐 Deploy a Mastra Server

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

🌐 Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.

tip

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

🌐 This guide covers deploying the standalone server generated by mastra build. If you need to integrate Mastra into an existing Express or Hono application, see Server Adapters instead.

构建你的应用
Direct link to 构建你的应用

🌐 Building your application

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

🌐 Run the build command from your project root:

mastra build

这将创建一个包含你可投入生产使用的服务器的 .mastra 目录。

🌐 This creates a .mastra directory containing your production-ready server.

info

请阅读 mastra build 参考以获取所有可用的标志。

🌐 Read the mastra build reference for all available flags.

构建输出
Direct link to 构建输出

🌐 Build output

构建后，Mastra 会生成以下结构：

🌐 After building, Mastra creates the following structure:

.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 目录是自包含的。你可以将它复制到任何服务器上并直接运行。

🌐 The output directory is self-contained. You can copy it to any server and run it directly.

运行服务器
Direct link to 运行服务器

🌐 Running the server

使用 Mastra CLI 启动服务器：

🌐 Start the server using the Mastra CLI:

mastra start

或者直接使用 Node.js 运行：

🌐 Or run directly with Node.js:

node .mastra/output/index.mjs

mastra start 命令提供以下附加功能：

🌐 The mastra start command provides additional features:

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

请阅读 mastra start 参考资料以了解所有可用的选项标志。

🌐 Read the mastra start reference for all available flags.

构建配置
Direct link to 构建配置

🌐 Build configuration

公共文件夹
Direct link to 公共文件夹

🌐 Public folder

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

🌐 If a public folder exists in your Mastra directory (src/mastra/public), its contents are copied to the output directory during build. These files are served as static assets by the server.

Mastra 配置
Direct link to Mastra 配置

🌐 Mastra configuration

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

🌐 The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see server overview. For all available options, see the configuration reference.

构建过程
Direct link to 构建过程

🌐 Build process

构建步骤如下：

🌐 The build follows these steps:

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

环境变量
Direct link to 环境变量

🌐 Environment variables

变量描述
PORT服务器端口（默认：4111）
MASTRA_STUDIO_PATHStudio 构建目录路径（默认：./playground）
MASTRA_SKIP_DOTENV设置后跳过加载 .env 文件
NODE_OPTIONSNode.js 选项（例如，用于构建内存问题的 --max-old-space-size=4096）

服务器端点
Direct link to 服务器端点

🌐 Server endpoints

已搭建的服务器提供用于健康检查、代理、工作流等的端点：

🌐 The built server exposes endpoints for health checks, agents, workflows, and more:

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

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

🌐 This list is not exhaustive. To view all endpoints, run mastra dev and visit http://localhost:4111/swagger-ui.

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

🌐 To add your own endpoints, see Custom API Routes.

故障排除
Direct link to 故障排除

🌐 Troubleshooting

构建过程中出现内存错误
Direct link to 构建过程中出现内存错误

🌐 Memory errors during build

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

🌐 If you encounter JavaScript heap out of memory errors:

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

🌐 Related

目录