在 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 工具，從正確的套件執行建置命令，毋須使用特殊旗標。

範例：

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 根目錄。

部署配置

部署至雲端 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

相關內容

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