> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 在 monorepo 中部署

在 monorepo 中部署 Mastra 与部署独立应用遵循相同的流程。本指南介绍 monorepo 特有的注意事项。有关核心构建和部署步骤，请参阅[部署 Mastra Server](https://mastra.zisheng.pro/docs/deployment/mastra-server)。

## 支持的 monorepo

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

- npm workspaces
- pnpm workspaces
- Yarn workspaces
- Turborepo

已知限制：

- Bun workspaces——仅部分支持，存在已知问题
- Nx——可以使用 Nx [支持的依赖项策略](https://nx.dev/concepts/decisions/dependency-management)，但 Workspace 包内必须包含 `package.json` 文件

## 示例结构

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

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

## 从 monorepo 构建

使用 monorepo 工具从正确的包运行构建命令。无需使用特殊 flag。

示例：

**npm**:

```bash
npm run build --workspace=apps/api
```

**pnpm**:

```bash
pnpm --filter api run build
```

**yarn**:

```bash
yarn workspace api build
```

**Turborepo**:

```bash
turbo run build --filter=api
```

包的 `build` 脚本应运行 `mastra build`：

```json
{
  "scripts": {
    "build": "mastra build"
  }
}
```

## Workspace 包

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

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

对于大多数设置，无需配置即可正常工作。如果 Workspace 包导入出现问题，请将该包添加到 [`transpilePackages`](https://mastra.zisheng.pro/reference/configuration)：

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

请将 `bundler` 保留为传给 `new Mastra()` 的对象的直接属性。有关支持的入口文件形式，请参阅[构建时配置](https://mastra.zisheng.pro/docs/deployment/mastra-server)。

## 环境变量

请将 `.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`](https://mastra.zisheng.pro/reference/configuration)

## 相关内容

- [部署 Mastra Server](https://mastra.zisheng.pro/docs/deployment/mastra-server)：核心构建和部署指南
- [配置 Reference](https://mastra.zisheng.pro/reference/configuration)：`bundler.transpilePackages` 及其他选项
- [CLI Reference](https://mastra.zisheng.pro/reference/cli/mastra)：构建命令 flag