跳至主要內容

升級至 Mastra v1

更新至最新 0.x 版本

升級至 v1 前，請確保你已更新至最新的 Mastra 0.x 版本。請先依照升級至最新 0.x 指南操作，再返回此處完成 v1 遷移。

Mastra v1 已於 2026 年 1 月推出。我們建議所有新項目都使用 Mastra v1，或升級現有項目，以繼續接收更新及支援。

本指南涵蓋從 Mastra 0.x 升級至 v1.0 時的重大變更。遷移內容按套件及功能範疇整理，協助你有系統地更新程式碼庫。

需要協助？

遷移時需要協助？歡迎加入我們的 Discord 社群提問。

從 Mastra Cloud 遷移？

舊版 Mastra Cloud 產品已由 Mastra 平台取代。平台將託管服務分成兩個獨立產品：Studio（視覺化環境、可觀察性）及伺服器（生產環境 API）。舊 Mastra Cloud 存取權杖不適用於 Mastra 平台。請使用 mastra auth tokens create 建立新權杖。

如果你升級至 v1 套件，卻沒有同時將 telemetry: 設定遷移至 observability: 並建立 Studio 項目，可觀察性資料便會停止傳送。請完整依照 Mastra Cloud 遷移指南操作。

遷移策略
遷移策略 的直接連結

將所有 Mastra 套件更新至 latest 標籤
update-all-mastra-packages-to-latest-tag 的直接連結

使用套件管理器更新項目的版本。請一併更新所有 Mastra 套件（所有 @mastra/* 套件及 mastra），以確保兼容。

以下是更新最常用套件的方法：

npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest

使用 @latest 標籤安裝任何其他 Mastra 套件，即可取得最新的可用 v1 版本。請確保更新所有 Mastra 套件（尤其是使用 monorepo 時），以免版本不一致。

更新 Node.js 版本
更新 Node.js 版本 的直接連結

Mastra v1 需要 Node.js 22.13.0 或以上版本。請相應更新開發及生產環境。

完成遷移核對清單
完成遷移核對清單 的直接連結

依照下方的遷移核對清單更新程式碼庫。每個項目都會連結至該項特定變更的詳細指南。

Codemod

我們已為你準備自動化 codemod。如有需要，你可以一次過執行所有 v1 codemod：

npx @mastra/codemod@latest v1
必須遷移資料庫

如果你使用 PostgreSQL 或 LibSQL 儲存空間，便需要執行資料庫遷移。詳情請參閱儲存空間遷移指南。

各範疇的重大變更
各範疇的重大變更 的直接連結

  • Mastra 類別 - 重新組織 import 及變更屬性存取方式。
  • Agent 類別 - 語音方法移至命名空間，並更新串流 API。
  • Tool - CreateTool 的 execute 簽名改為分開傳入輸入及內容。
  • Workflow - 函數名稱有變，並移除舊版功能。
  • 記憶體 - 設定現在需要明確參數，預設值亦有變更。
  • 儲存空間 - 分頁方式標準化，方法亦重新命名為 list 模式。
  • 向量 - 向量儲存方法重新命名為 list 模式。
  • RAG - 更新參數名稱，使其更清晰。
  • MCP - 重新組織 Tool 內容，並移除已棄用的 client 類別。
  • Tracing - 以專用可觀察性套件及 exporter 取代 OTEL telemetry。
  • Evals 及 Scorer - 整合 Scorer API，並採用新的命名慣例。
  • CLI - 移除命令及旗標，令介面更精簡。
  • 部署 - 更新 CloudflareDeployer 設定，改用標準 wrangler.json 屬性名稱。
  • Client SDK - 重新命名類型及工具函數，以保持一致。
  • 語音套件 - 套件名稱由 speech 改為 voice。

遷移核對清單
遷移核對清單 的直接連結

請按順序完成此核對清單，先處理會影響大部分應用程式的高影響變更。

Codemod

我們已為你準備自動化 codemod。在整份遷移指南中，你會找到針對特定變更使用這些 codemod 的指示。

如有需要，你可以一次過執行所有 v1 codemod：

npx @mastra/codemod@latest v1

高影響變更
高影響變更 的直接連結

  • 將 createTool Tool 簽名更新為 (inputData, context) 格式 - Tool
  • 重新組織 @mastra/core import，改用子路徑 import - Mastra 類別
  • 將分頁方式由 offset/limit 更新為 page/perPage - 儲存空間
  • 安裝 @mastra/observability，並以 new Observability() 包裝設定 - Tracing
  • 從 telemetry: 遷移至 observability: 設定（如從 0.x OTEL 升級）- Tracing

中等影響變更
中等影響變更 的直接連結

  • 在整個程式碼庫中將 RuntimeContext 重新命名為 RequestContext - Agent 類別、Tool、Workflow
  • 將儲存方法由 get* 更新為 list* 模式 - 儲存空間
  • 以 getter 方法取代直接存取屬性 - Mastra 類別、Agent 類別
  • 如果依賴預設 thread 範圍，請更新記憶體範圍 - 記憶體
  • 更新向量儲存呼叫以使用具名引數 - 儲存空間
  • 從 Agent 方法移除 format 參數 - Agent 類別
  • 更新語音方法，改用 agent.voice 命名空間 - Agent 類別
  • 將設定屬性 processors 重新命名為 spanOutputProcessors（如使用自訂 processor）- Tracing

低影響變更
低影響變更 的直接連結

  • 在分段選項中將 keepSeparator 重新命名為 separatorPosition - RAG
  • 將 createRunAsync 重新命名為 createRun - Workflow
  • 將語音套件名稱由 @mastra/speech-* 更新為 @mastra/voice-* - 語音套件
  • 更新 scorer 方法：runExperiment → runEvals、getScorerByName → getScorerById - Evals 及 Scorer
  • 移除已棄用的 CLI 旗標 - CLI
  • 將 Client SDK 類型由 Get* 更新為 List* - Client SDK
  • 以 retryCount 取代 runCount - Workflow
  • 將自訂 exporter 方法 exportEvent 更新為 exportTracingEvent（如使用自訂 exporter）- Tracing
On this page