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

# 在 monorepo 中部署

在 monorepo 中部署 Mastra 的流程與部署獨立應用程式相同。本指南會說明 monorepo 特有的注意事項。如需了解核心建置及部署步驟，請參閱[部署 Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/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 工具，從正確的套件執行建置命令，毋須使用特殊旗標。

範例：

**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` script 應執行 `mastra build`：

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

## Workspace 套件

當 Mastra 應用程式從其他 Workspace 套件匯入內容時，Mastra 會自動處理：

- 如果套件已預先編譯（例如使用 `tsc` 或 `tsdown` 建置），Mastra 會匯入已編譯的 JavaScript
- 如果套件包含未編譯的 TypeScript，Mastra 會在建置期間將其轉譯

大多數設定均毋須配置即可運作。如果 Workspace 套件匯入出現問題，請將該套件加入 [`transpilePackages`](https://mastra.zisheng.pro/zh-HK/reference/configuration)：

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

請將 `bundler` 保留為傳遞至 `new Mastra()` 的物件中的直接屬性。如需了解支援的進入點文件結構，請參閱[建置階段配置](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)。

## 環境變數

請將 `.env` 文件儲存在 Mastra 應用程式目錄中（例如 `apps/api/.env`），而非 monorepo 根目錄。

## 部署配置

部署至雲端 Provider 時，請確保選取正確的套件作為部署目標。常見錯誤是選取 monorepo 根目錄，而非應用程式目錄（例如 `apps/api`）。

大多數 Provider 都可讓你在其控制台或配置文件中指定根目錄。

## 依賴套件管理

請保持依賴套件一致，以避免版本衝突及建置錯誤：

- 在 monorepo 根目錄使用**單一 lockfile**，讓所有套件解析至相同版本
- 統一**共用程式庫**（例如 Mastra 或框架）的版本，以避免重複

## 疑難排解

### 找不到 Workspace 套件

如果 Mastra 無法解析 Workspace 套件，請確保：

- 套件已列於 `package.json` 的 dependencies 中
- lockfile 已是最新版本（`pnpm install`、`npm install` 等）
- 套件有有效的 `main` 或 `exports` 欄位，並已列於其 `package.json` 中

### Workspace 套件引起的 TypeScript 錯誤

如果未編譯的 Workspace 套件引起類型錯誤，你可以：

- 先建置該套件（建議做法，可加快 Mastra 建置速度）
- 在 Mastra 配置中將該套件加入 [`transpilePackages`](https://mastra.zisheng.pro/zh-HK/reference/configuration)

## 相關內容

- [部署 Mastra 伺服器](https://mastra.zisheng.pro/zh-HK/docs/deployment/mastra-server)：核心建置及部署指南
- [配置參考](https://mastra.zisheng.pro/zh-HK/reference/configuration)：`bundler.transpilePackages` 及其他選項
- [CLI 參考](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)：建置命令旗標