Monorepo

在 monorepo 中部署 Mastra 的流程与独立应用相同。本指南介绍 monorepo 特有的注意事项。核心构建和部署步骤请参阅部署 Mastra 服务器。

支持的 monorepo

Mastra 支持：

• npm workspaces
• pnpm workspaces
• Yarn workspaces
• Turborepo

已知限制：

• Bun workspaces —— 部分支持；存在已知问题
• Nx —— 你可以使用 Nx 支持的依赖策略，但工作区包中需要有 package.json 文件

示例结构

在此示例中，Mastra 应用位于 apps/api：

apps/
├── api/
│   ├── src/
│   │   └── mastra/
│   │       ├── agents/
│   │       ├── tools/
│   │       ├── workflows/
│   │       └── index.ts
│   ├── package.json
│   └── tsconfig.json
└── web/
packages/
├── ui/
└── utils/
package.json

从 monorepo 构建

使用你的 monorepo 工具在正确的包中运行构建命令。无需特殊参数。

示例：

npm

npm run build --workspace=apps/api

pnpm

pnpm --filter api run build

yarn

yarn workspace api build

Turborepo

turbo run build --filter=api

包的 build 脚本应运行 mastra build：

apps/api/package.json

{
  "scripts": {
    "build": "mastra build"
  }
}

工作区包

当 Mastra 应用从其他工作区包导入时，Mastra 会自动处理：

• 如果包已预编译（例如使用 tsc 或 tsdown 构建），Mastra 会导入编译后的 JavaScript
• 如果包包含未编译的 TypeScript，Mastra 会在构建期间转译它

大多数情况下无需配置即可工作。如果工作区包导入出现问题，请将该包添加到 transpilePackages：

src/mastra/index.ts

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/utils'],
  },
})

请将 bundler 保留为传给 new Mastra() 的对象的直接属性。支持的入口文件形式请参阅构建时配置。

环境变量

将 .env 文件存放在 Mastra 应用目录中（例如 apps/api/.env），而不是 monorepo 根目录。

部署配置

部署到云提供商时，请确保选择正确的包作为部署目标。选择 monorepo 根目录而不是应用目录（例如 apps/api）是常见错误。

大多数提供商允许你在仪表板或配置文件中指定根目录。

依赖管理

保持依赖一致，以避免版本冲突和构建错误：

• 在 monorepo 根目录使用单一 lockfile，以便所有包解析到相同版本
• 对齐共享库（如 Mastra 或框架）的版本，以避免重复

跳过依赖安装

默认情况下，mastra build 会将包管理器的 lockfile 复制到 .mastra/output，然后通过一次包管理器操作更新 lockfile 并安装依赖。在 CI 中该更新仍会启用。如果不存在源 lockfile，Mastra 会使用 npm 并生成 package-lock.json。封闭式构建系统（如 Bazel）会在外部提供 node_modules，并在无网络的沙箱中运行，此时该安装操作既多余又会导致失败。

将 MASTRA_BUILD_SKIP_INSTALL 设为 true 或 1，以跳过 lockfile 更新和输出目录安装：

MASTRA_BUILD_SKIP_INSTALL=1 mastra build

启用后，你需要自行在输出目录中提供 node_modules。

故障排查

找不到工作区包

如果 Mastra 无法解析工作区包，请确保：

• 该包已列在 package.json 的 dependencies 中
• lockfile 是最新的（pnpm install、npm install 等）
• 该包的 package.json 中有有效的 main 或 exports 字段

来自工作区包的 TypeScript 错误

如果未编译的工作区包出现类型错误，可以：

• 先构建该包（推荐，可加快 Mastra 构建）
• 将该包添加到 Mastra 配置中的 transpilePackages

相关内容

• Deploy a Mastra Server：核心构建与部署指南
• Configuration Reference：bundler.transpilePackages 及其他选项
• CLI Reference：构建命令参数