> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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-HK/docs/mastra-platform/overview)取代。平台將託管服務分成兩個獨立產品：**Studio**（視覺化環境、可觀察性）及**伺服器**（生產環境 API）。舊 Mastra Cloud 存取權杖不適用於 Mastra 平台。請使用 `mastra auth tokens create` 建立新權杖。 > > 如果你升級至 v1 套件，卻沒有同時將 `telemetry:` 設定遷移至 `observability:` 並建立 Studio 項目，可觀察性資料便會停止傳送。請完整依照 [Mastra Cloud 遷移指南](https://mastra.zisheng.pro/zh-HK/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 ``` 使用 `@latest` 標籤安裝任何其他 Mastra 套件，即可取得最新的可用 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-HK/guides/migrations/upgrade-to-v1/storage)。 ## 各範疇的重大變更 - **[Mastra 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/mastra)** - 重新組織 import 及變更屬性存取方式。 - **[Agent 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/agent)** - 語音方法移至命名空間，並更新串流 API。 - **[Tool](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tools)** - CreateTool 的 execute 簽名改為分開傳入輸入及內容。 - **[Workflow](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/workflows)** - 函數名稱有變，並移除舊版功能。 - **[記憶體](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/memory)** - 設定現在需要明確參數，預設值亦有變更。 - **[儲存空間](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/storage)** - 分頁方式標準化，方法亦重新命名為 list 模式。 - **[向量](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/vectors)** - 向量儲存方法重新命名為 list 模式。 - **[RAG](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/rag)** - 更新參數名稱，使其更清晰。 - **[MCP](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/mcp)** - 重新組織 Tool 內容，並移除已棄用的 client 類別。 - **[Tracing](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tracing)** - 以專用可觀察性套件及 exporter 取代 OTEL telemetry。 - **[Evals 及 Scorer](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/evals)** - 整合 Scorer API，並採用新的命名慣例。 - **[CLI](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/cli)** - 移除命令及旗標，令介面更精簡。 - **[部署](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/deployment)** - 更新 CloudflareDeployer 設定，改用標準 wrangler.json 屬性名稱。 - **[Client SDK](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/client)** - 重新命名類型及工具函數，以保持一致。 - **[語音套件](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/voice)** - 套件名稱由 speech 改為 voice。 ## 遷移核對清單 請按順序完成此核對清單，先處理會影響大部分應用程式的高影響變更。 > **Codemod:** 我們已為你準備自動化 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)。在整份遷移指南中，你會找到針對特定變更使用這些 codemod 的指示。 > > 如有需要，你可以一次過執行所有 v1 codemod： > > ```bash > npx @mastra/codemod@latest v1 > ``` ### 高影響變更 - 將 `createTool` Tool 簽名更新為 `(inputData, context)` 格式 - [Tool](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tools) - 重新組織 `@mastra/core` import，改用子路徑 import - [Mastra 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/mastra) - 將分頁方式由 `offset/limit` 更新為 `page/perPage` - [儲存空間](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/storage) - 安裝 `@mastra/observability`，並以 `new Observability()` 包裝設定 - [Tracing](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tracing) - 從 `telemetry:` 遷移至 `observability:` 設定（如從 0.x OTEL 升級）- [Tracing](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tracing) ### 中等影響變更 - 在整個程式碼庫中將 `RuntimeContext` 重新命名為 `RequestContext` - [Agent 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/agent)、[Tool](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tools)、[Workflow](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/workflows) - 將儲存方法由 `get*` 更新為 `list*` 模式 - [儲存空間](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/storage) - 以 getter 方法取代直接存取屬性 - [Mastra 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/mastra)、[Agent 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/agent) - 如果依賴預設 `thread` 範圍，請更新記憶體範圍 - [記憶體](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/memory) - 更新向量儲存呼叫以使用具名引數 - [儲存空間](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/storage) - 從 Agent 方法移除 `format` 參數 - [Agent 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/agent) - 更新語音方法，改用 `agent.voice` 命名空間 - [Agent 類別](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/agent) - 將設定屬性 `processors` 重新命名為 `spanOutputProcessors`（如使用自訂 processor）- [Tracing](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tracing) ### 低影響變更 - 在分段選項中將 `keepSeparator` 重新命名為 `separatorPosition` - [RAG](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/rag) - 將 `createRunAsync` 重新命名為 `createRun` - [Workflow](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/workflows) - 將語音套件名稱由 `@mastra/speech-*` 更新為 `@mastra/voice-*` - [語音套件](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/voice) - 更新 scorer 方法：`runExperiment` → `runEvals`、`getScorerByName` → `getScorerById` - [Evals 及 Scorer](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/evals) - 移除已棄用的 CLI 旗標 - [CLI](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/cli) - 將 Client SDK 類型由 `Get*` 更新為 `List*` - [Client SDK](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/client) - 以 `retryCount` 取代 `runCount` - [Workflow](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/workflows) - 將自訂 exporter 方法 `exportEvent` 更新為 `exportTracingEvent`（如使用自訂 exporter）- [Tracing](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/tracing)