Skip to main content

升级到 Mastra v1

🌐 Upgrade to Mastra v1

Update to latest 0.x version

Before upgrading to v1, make sure you've updated to the latest 0.x version of Mastra. Follow the upgrade to latest 0.x guide first, then return here to complete the v1 migration.

Mastra v1 于 2026 年 1 月发布。我们建议从 Mastra v1 开始任何新项目，或升级你现有的项目以继续获得更新和支持。

🌐 Mastra v1 was released in January 2026. We recommend starting any new projects with Mastra v1, or upgrading your existing project to continue receiving updates and support.

本指南提供了从 Mastra 0.x 升级到 v1.0 时的重大更改的全面概述。迁移按软件包和功能区域进行组织，以帮助你系统地更新代码库。

🌐 This guide provides a comprehensive overview of breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.

Need help?

Need help with the migration? Join our Discord community to ask questions.

迁移策略
Direct link to 迁移策略

🌐 Migration Strategy

将所有 Mastra 软件包更新到 latest 标签
Direct link to update-all-mastra-packages-to-latest-tag

🌐 Update all Mastra packages to latest tag

使用你的包管理器来更新项目的版本。确保同时更新所有 Mastra 包以保证兼容性（所有 @mastra/* 包和 mastra）。

🌐 Use your package manager to update your project's versions. Be sure to update all Mastra packages at the same time to ensure compatibility (all @mastra/* packages and mastra).

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

🌐 Here's how you update the most commonly used packages:

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

安装带有 @latest 标签的任何其他 Mastra 包，你将获得可用的最新 v1 版本。请确保更新所有 Mastra 包（尤其是如果你在一个 monorepo 中），以避免版本不匹配。

🌐 Install any other Mastra package with the @latest tag and you'll get the latest v1 version available. Be sure to update all Mastra packages (especially if you're in a monorepo) to avoid version mismatches.

更新 Node.js 版本
Direct link to 更新 Node.js 版本

🌐 Update Node.js version

Mastra v1 需要 Node.js 22.13.0 或更高版本。请相应地更新你的开发和生产环境。

🌐 Mastra v1 requires Node.js 22.13.0 or higher. Update your development and production environments accordingly.

查看迁移清单
Direct link to 查看迁移清单

🌐 Go through migration checklist

请根据下面的迁移清单逐项更新你的代码库。每一项都链接到关于该具体更改的详细指南。

🌐 Work through the migration checklist below to update your codebase. Each item links to a detailed guide for that specific change.

Codemods

我们为你准备了自动化的 代码转换。如果你愿意，可以一次性运行所有 v1 代码转换：

🌐 We prepared automated codemods for you. If you want, you can run all v1 codemods at once:

npx @mastra/codemod@latest v1
Database Migration Required

如果你使用的是 PostgreSQL 或 LibSQL 存储，你需要运行数据库迁移。详情请参阅存储迁移指南。

🌐 If you're using PostgreSQL or LibSQL storage, you'll need to run a database migration. See the Storage migration guide for details.

按字段划分的重大变更
Direct link to 按字段划分的重大变更

🌐 Breaking Changes by Area

  • Mastra 类 - 导入重构和属性访问变更。
  • Agent 类 - 语音方法已迁移到命名空间，并更新了流式 API。
  • 工具 - CreateTool 执行签名已更改为分离输入和上下文。
  • 工作流 - 功能名称已更改，已移除旧功能。
  • 内存 - 配置现在需要显式参数，默认值已更改。
  • 存储 - 分页已标准化，方法已重命名为列表模式。
  • 向量 - 向量存储方法已重命名为列表模式。
  • RAG - 参数命名已更新以提高清晰度。
  • MCP - 工具上下文已重新组织，已移除弃用的客户端类。
  • 追踪 - OTEL 遥测被专用的可观测性包和导出器所取代。
  • 评估与评分 - 评分 API 已整合并采用新的命名规范。
  • CLI - 为了简化界面，已移除命令和标志。
  • 部署 - CloudflareDeployer 配置已更新，以使用标准的 wrangler.json 属性名称。
  • 客户端 SDK - 类型和工具已重命名以保持一致性。
  • 语音包 - 包名称从“语音”改为“声音”。

迁移清单
Direct link to 迁移清单

🌐 Migration Checklist

按照此清单的顺序逐项处理，从影响大多数应用的高影响改动开始。

🌐 Work through this checklist in order, starting with high-impact changes that affect most applications.

Codemods

我们为你准备了自动化的 代码转换。在整个迁移指南中，你会找到关于如何将它们用于特定更改的说明。

🌐 We prepared automated codemods for you. Throughout the migration guide you'll find instructions on how to use them for specific changes.

如果你愿意，你可以一次性运行所有 v1 代码转换工具：

🌐 If you want, you can run all v1 codemods at once:

npx @mastra/codemod@latest v1

高影响力变革
Direct link to 高影响力变革

🌐 High Impact Changes

  • 将 createTool 工具签名更新为 (inputData, context) 格式 - 工具
  • 将 @mastra/core 导入重构为使用子路径导入 - Mastra 类
  • 将分页从 offset/limit 更新到 page/perPage - 存储
  • 安装 @mastra/observability 并使用 new Observability() 封装配置 - 追踪
  • 从 telemetry: 迁移到 observability: 配置（如果从 0.x OTEL 升级）- 追踪

中等影响的变化
Direct link to 中等影响的变化

🌐 Medium Impact Changes

  • 将代码库中的 RuntimeContext 重命名为 RequestContext - Agent 类、工具、工作流
  • 将存储方法从 get* 更新为 list* 模式 - 存储
  • 将直接属性访问替换为 getter 方法 - Mastra 类, Agent 类
  • 如果依赖默认的 thread 范围，请更新内存范围 - 内存
  • 更新向量存储调用以使用命名参数 - 存储
  • 从代理方法中移除 format 参数 - Agent 类
  • 更新语音方法以使用 agent.voice 命名空间 - Agent 类
  • 将配置属性 processors 重命名为 spanOutputProcessors（如果使用自定义处理器）- 追踪

低影响变更
Direct link to 低影响变更

🌐 Low Impact Changes

  • 在块选项中将 keepSeparator 重命名为 separatorPosition - RAG
  • 将 createRunAsync 重命名为 createRun - 工作流程
  • 将语音包名称从 @mastra/speech-* 更新为 @mastra/voice-* - 语音包
  • 更新评分方法：runExperiment → runEvals，getScorerByName → getScorerById - 评估与评分器
  • 移除已弃用的 CLI 标志 - CLI
  • 将客户端 SDK 类型从 Get* 更新到 List* - 客户端 SDK
  • 将 runCount 替换为 retryCount - 工作流程
  • 将自定义导出方法 exportEvent 更新为 exportTracingEvent（如果使用自定义导出器） - 追踪
目录