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

# 在 monorepo 中部署

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

範例：

**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-TW/reference/configuration)：

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

請將 `bundler` 保留為傳入 `new Mastra()` 之物件的直接屬性。支援的進入檔案形式請參閱[建置階段設定](https://mastra.zisheng.pro/zh-TW/docs/deployment/mastra-server)。

## 環境變數

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

## 部署設定

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

大多數供應商都能在控制台或設定檔中指定根目錄。

## 相依性管理

維持相依性一致，以避免版本衝突與建置錯誤：

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

## 疑難排解

### 找不到 Workspace 套件

若 Mastra 無法解析 Workspace 套件，請確認：

- 套件已列於 `package.json` 的 dependencies 中
- lockfile 為最新狀態（`pnpm install`、`npm install` 等）
- 套件的 `package.json` 中有有效的 `main` 或 `exports` 欄位

### Workspace 套件發生 TypeScript 錯誤

若未編譯的 Workspace 套件出現型別錯誤，請採用下列任一方式：

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

## 相關資源

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