在 monorepo 中部署

在 monorepo 中部署 Mastra 的流程與獨立應用程式相同。本指南說明 monorepo 特有的注意事項。核心建置與部署步驟請參閱部署 Mastra 伺服器。

支援的 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 Tool，從正確的套件執行建置指令。不需要特殊旗標。

範例：

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 script 應執行 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 根目錄。

部署設定

部署至雲端供應商時，請確保選取正確的套件作為部署目標。常見錯誤是選取 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

相關資源

• 部署 Mastra 伺服器：核心建置與部署指南
• 設定參考：bundler.transpilePackages 與其他選項
• CLI 參考：建置指令旗標