在 monorepo 中部署

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

支持的 monorepo

Mastra 可与以下工具配合使用：

• npm workspaces
• pnpm workspaces
• Yarn workspaces
• Turborepo

已知限制：

• Bun workspaces——仅部分支持，存在已知问题
• Nx——可以使用 Nx 支持的依赖项策略，但 Workspace 包内必须包含 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 工具从正确的包运行构建命令。无需使用特殊 flag。

示例：

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"
  }
}

Workspace 包

当 Mastra 应用从其他 Workspace 包导入内容时，Mastra 会自动进行处理：

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

对于大多数设置，无需配置即可正常工作。如果 Workspace 包导入出现问题，请将该包添加到 transpilePackages：

src/mastra/index.ts

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

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

环境变量

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

部署配置

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

大多数 Provider 都允许在 dashboard 或配置文件中指定根目录。

依赖项管理

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

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

故障排除

找不到 Workspace 包

如果 Mastra 无法解析 Workspace 包，请确保：

• 该包已列在 package.json 的依赖项中
• lockfile 为最新状态（已运行 pnpm install、npm install 等）
• 该包的 package.json 中包含有效的 main 或 exports 字段

Workspace 包中的 TypeScript 错误

如果看到来自未编译 Workspace 包的类型错误，可以选择：

• 先构建该包（建议这样做，可加快 Mastra 构建）
• 将该包添加到 Mastra 配置的 transpilePackages

相关内容

• 部署 Mastra Server：核心构建和部署指南
• 配置 Reference：bundler.transpilePackages 及其他选项
• CLI Reference：构建命令 flag