跳到主要内容

升级到 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 或更高版本。请相应更新开发环境和生产环境。

完成迁移清单
完成迁移清单的直接链接

按照下面的迁移清单更新代码库。每一项都链接到相应变更的详细指南。

Codemods

我们准备了自动化 codemod。如有需要，可以一次运行所有 v1 codemod：

npx @mastra/codemod@latest v1
需要迁移数据库

如果使用 PostgreSQL 或 LibSQL Storage，则需要运行数据库迁移。详情请参阅 Storage 迁移指南。

按领域划分的破坏性变更
按领域划分的破坏性变更的直接链接

  • Mastra 类 — 重构导入并更改属性访问方式。
  • Agent 类 — Voice 方法迁移到命名空间，并更新流式 API。
  • Tool — CreateTool execute 签名改为独立的输入和上下文参数。
  • Workflow — 更改函数名并移除旧版功能。
  • Memory — 配置现在需要显式参数，默认值也已变更。
  • Storage — 标准化分页，并将方法重命名为 list 模式。
  • Vector — Vector Store 方法重命名为 list 模式。
  • RAG — 更新参数命名，使含义更清晰。
  • MCP — 重新组织 Tool 上下文，并移除已弃用的客户端类。
  • Tracing — 用专用 observability 包和 exporter 替代 OTEL telemetry。
  • Evals 和 scorer — 使用新的命名约定统一 scorer API。
  • CLI — 移除命令和标志，简化界面。
  • 部署 — 更新 CloudflareDeployer 配置，使用标准 wrangler.json 属性名。
  • Client SDK — 重命名类型和工具函数以保持一致。
  • Voice 包 — 包名从 speech 改为 voice。

迁移清单
迁移清单的直接链接

请按顺序完成此清单，从影响大多数应用的高影响变更开始。

Codemods

我们准备了自动化 codemod。迁移指南各处都提供了针对特定变更的使用说明。

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

npx @mastra/codemod@latest v1

高影响变更
高影响变更的直接链接

  • 将 createTool Tool 签名更新为 (inputData, context) 格式 — Tool
  • 重构 @mastra/core 导入以使用子路径导入 — Mastra 类
  • 将分页从 offset/limit 更新为 page/perPage — Storage
  • 安装 @mastra/observability 并使用 new Observability() 包装配置 — Tracing
  • 从 telemetry: 迁移到 observability: 配置（从 0.x OTEL 升级时）— Tracing

中等影响变更
中等影响变更的直接链接

  • 在整个代码库中将 RuntimeContext 重命名为 RequestContext — Agent 类、Tool、Workflow
  • 将 Storage 方法从 get* 更新为 list* 模式 — Storage
  • 用 getter 方法替代直接属性访问 — Mastra 类、Agent 类
  • 如果依赖默认 thread 作用域，请更新 Memory 作用域 — Memory
  • 更新 Vector Store 调用以使用命名参数 — Storage
  • 从 Agent 方法中移除 format 参数 — Agent 类
  • 更新 Voice 方法以使用 agent.voice 命名空间 — Agent 类
  • 将配置属性 processors 重命名为 spanOutputProcessors（使用自定义 Processor 时）— Tracing

低影响变更
低影响变更的直接链接

  • 将分块选项中的 keepSeparator 重命名为 separatorPosition — RAG
  • 将 createRunAsync 重命名为 createRun — Workflow
  • 将 Voice 包名从 @mastra/speech-* 更新为 @mastra/voice-* — Voice 包
  • 更新 scorer 方法：runExperiment → runEvals、getScorerByName → getScorerById — Evals 和 scorer
  • 移除已弃用的 CLI 标志 — CLI
  • 将 Client SDK 类型从 Get* 更新为 List* — Client SDK
  • 用 retryCount 替换 runCount — Workflow
  • 将自定义 exporter 方法 exportEvent 更新为 exportTracingEvent — Tracing
On this page