跳至主要內容

升級至 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（視覺化環境、可觀測性）與 Server（正式環境 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

安裝任何其他 Mastra 套件時加上 @latest 標籤，即可取得最新可用的 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 類別 - 匯入結構與屬性存取方式變更。
  • Agent 類別 - Voice 方法移至命名空間，串流 API 也已更新。
  • Tool - createTool 的 execute 簽章變更為將輸入與內容分開傳入。
  • Workflow - 函式名稱變更，並移除舊版功能。
  • Memory - 設定現在必須明確提供參數，且預設值已變更。
  • 儲存空間 - 分頁已標準化，方法也重新命名為 list 模式。
  • 向量 - 向量儲存方法重新命名為 list 模式。
  • RAG - 更新參數名稱以提升清晰度。
  • MCP - Tool 內容重新組織，並移除已棄用的使用者端類別。
  • Tracing - 以專用的可觀測性套件與 exporter 取代 OTEL 遙測。
  • Evals 與 scorer - 使用新的命名慣例整合 scorer API。
  • CLI - 移除命令與旗標，讓介面更精簡。
  • 部署 - CloudflareDeployer 設定更新為使用標準的 wrangler.json 屬性名稱。
  • 使用者端 SDK - 重新命名型別與公用程式，以保持一致。
  • Voice 套件 - 套件從 speech 重新命名為 voice。

遷移檢查清單
「遷移檢查清單」的直接連結

請依序完成此檢查清單，先處理影響大多數應用程式的高影響變更。

Codemod

我們已為你準備自動化 codemod。整份遷移指南中會提供針對特定變更使用它們的指示。

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

npx @mastra/codemod@latest v1

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

  • 將 createTool Tool 簽章更新為 (inputData, context) 格式 - Tool
  • 重整 @mastra/core 匯入，改用子路徑匯入 - 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 範圍，請更新 Memory 範圍 - Memory
  • 更新向量儲存呼叫以使用具名引數 - 儲存空間
  • 從 Agent 方法移除 format 參數 - Agent 類別
  • 更新 Voice 方法以使用 agent.voice 命名空間 - Agent 類別
  • 將設定屬性 processors 重新命名為 spanOutputProcessors（如果使用自訂處理器）- Tracing

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

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