> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt # 升級至 Mastra v1 > **更新至最新的 0.x 版本:** 升級至 v1 前，請確認已更新至最新的 Mastra 0.x 版本。先依照[升級至最新 0.x 指南](https://mastra.ai/guides/v0/migrations/upgrade-to-latest-0x)操作，再回到此處完成 v1 遷移。 Mastra v1 已於 2026 年 1 月發布。我們建議所有新專案都從 Mastra v1 開始，或升級現有專案，以繼續取得更新與支援。 本指南涵蓋從 Mastra 0.x 升級至 v1.0 時的破壞性變更。遷移內容依套件與功能領域分類，協助你有系統地更新程式碼庫。 > **需要協助嗎？:** 遷移時需要協助嗎？歡迎加入我們的 [Discord 社群](https://discord.gg/BTYqqHKUrf)提問。 > **從 Mastra Cloud 遷移？:** 舊版 Mastra Cloud 產品已由 [Mastra 平台](https://mastra.zisheng.pro/zh-TW/docs/mastra-platform/overview)取代，託管功能拆分成兩項獨立產品：**Studio**（視覺化環境、可觀測性）與 **Server**（正式環境 API）。舊版 Mastra Cloud 存取權杖無法用於 Mastra 平台。請使用 `mastra auth tokens create` 建立新的權杖。 > > 如果升級至 v1 套件，卻沒有同時將 `telemetry:` 設定遷移至 `observability:` 並建立 Studio 專案，可觀測性資料將停止傳送。請從頭到尾完成 [Mastra Cloud 遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/mastra-cloud)。 ## 遷移策略 ### 將所有 Mastra 套件更新至 `latest` 標籤 使用套件管理員更新專案版本。請一併更新**所有** Mastra 套件，以確保相容性（所有 `@mastra/*` 套件及 `mastra`）。 以下是更新最常用套件的方式： **npm**: ```bash npm install @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **pnpm**: ```bash pnpm add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **Yarn**: ```bash yarn add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` **Bun**: ```bash bun add @mastra/core@latest @mastra/loggers@latest @mastra/memory@latest mastra@latest ``` 安裝任何其他 Mastra 套件時加上 `@latest` 標籤，即可取得最新可用的 v1 版本。請務必更新所有 Mastra 套件（尤其是使用 monorepo 時），以免版本不一致。 ### 更新 Node.js 版本 Mastra v1 需要 Node.js **22.13.0** 或更新版本。請據此更新開發與正式環境。 ### 依序完成遷移檢查清單 依照下方的[遷移檢查清單](#migration-checklist)更新程式碼庫。每個項目都會連結到該項變更的詳細指南。 > **Codemod:** 我們已為你準備自動化 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)。如果需要，可以一次執行所有 v1 codemod： > > ```bash > npx @mastra/codemod@latest v1 > ``` > **必須進行資料庫遷移:** 如果你使用 PostgreSQL 或 LibSQL 儲存空間，必須執行資料庫遷移。詳情請參閱[儲存空間遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage)。 ## 各領域的破壞性變更 - **[Mastra 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/mastra)** - 匯入結構與屬性存取方式變更。 - **[Agent 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/agent)** - Voice 方法移至命名空間，串流 API 也已更新。 - **[Tool](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tools)** - createTool 的 execute 簽章變更為將輸入與內容分開傳入。 - **[Workflow](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/workflows)** - 函式名稱變更，並移除舊版功能。 - **[Memory](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/memory)** - 設定現在必須明確提供參數，且預設值已變更。 - **[儲存空間](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage)** - 分頁已標準化，方法也重新命名為 list 模式。 - **[向量](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/vectors)** - 向量儲存方法重新命名為 list 模式。 - **[RAG](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/rag)** - 更新參數名稱以提升清晰度。 - **[MCP](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/mcp)** - Tool 內容重新組織，並移除已棄用的使用者端類別。 - **[Tracing](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tracing)** - 以專用的可觀測性套件與 exporter 取代 OTEL 遙測。 - **[Evals 與 scorer](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/evals)** - 使用新的命名慣例整合 scorer API。 - **[CLI](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/cli)** - 移除命令與旗標，讓介面更精簡。 - **[部署](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/deployment)** - CloudflareDeployer 設定更新為使用標準的 wrangler.json 屬性名稱。 - **[使用者端 SDK](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/client)** - 重新命名型別與公用程式，以保持一致。 - **[Voice 套件](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/voice)** - 套件從 speech 重新命名為 voice。 ## 遷移檢查清單 請依序完成此檢查清單，先處理影響大多數應用程式的高影響變更。 > **Codemod:** 我們已為你準備自動化 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)。整份遷移指南中會提供針對特定變更使用它們的指示。 > > 如果需要，可以一次執行所有 v1 codemod： > > ```bash > npx @mastra/codemod@latest v1 > ``` ### 高影響變更 - 將 `createTool` Tool 簽章更新為 `(inputData, context)` 格式 - [Tool](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tools) - 重整 `@mastra/core` 匯入，改用子路徑匯入 - [Mastra 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/mastra) - 將分頁從 `offset/limit` 更新為 `page/perPage` - [儲存空間](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage) - 安裝 `@mastra/observability`，並使用 `new Observability()` 包裝設定 - [Tracing](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tracing) - 將 `telemetry:` 遷移至 `observability:` 設定（如果從 0.x OTEL 升級）- [Tracing](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tracing) ### 中影響變更 - 在整個程式碼庫中將 `RuntimeContext` 重新命名為 `RequestContext` - [Agent 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/agent)、[Tool](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tools)、[Workflow](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/workflows) - 將儲存空間方法從 `get*` 更新為 `list*` 模式 - [儲存空間](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage) - 使用 getter 方法取代直接屬性存取 - [Mastra 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/mastra)、[Agent 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/agent) - 如果依賴預設的 `thread` 範圍，請更新 Memory 範圍 - [Memory](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/memory) - 更新向量儲存呼叫以使用具名引數 - [儲存空間](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/storage) - 從 Agent 方法移除 `format` 參數 - [Agent 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/agent) - 更新 Voice 方法以使用 `agent.voice` 命名空間 - [Agent 類別](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/agent) - 將設定屬性 `processors` 重新命名為 `spanOutputProcessors`（如果使用自訂處理器）- [Tracing](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tracing) ### 低影響變更 - 在分塊選項中將 `keepSeparator` 重新命名為 `separatorPosition` - [RAG](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/rag) - 將 `createRunAsync` 重新命名為 `createRun` - [Workflow](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/workflows) - 將 Voice 套件名稱從 `@mastra/speech-*` 更新為 `@mastra/voice-*` - [Voice 套件](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/voice) - 更新 scorer 方法：`runExperiment` → `runEvals`、`getScorerByName` → `getScorerById` - [Evals 與 scorer](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/evals) - 移除已棄用的 CLI 旗標 - [CLI](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/cli) - 將使用者端 SDK 型別從 `Get*` 更新為 `List*` - [使用者端 SDK](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/client) - 使用 `retryCount` 取代 `runCount` - [Workflow](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/workflows) - 將自訂 exporter 方法 `exportEvent` 更新為 `exportTracingEvent`（如果使用自訂 exporter）- [Tracing](https://mastra.zisheng.pro/zh-TW/guides/migrations/upgrade-to-v1/tracing)