> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/docs/mastra-platform/overview)取代，托管功能拆分为两个独立产品：**Studio**（可视化环境、可观测性）和 **Server**（生产 API）。旧的 Mastra Cloud 访问令牌无法用于 Mastra 平台。请使用 `mastra auth tokens create` 创建新令牌。
>
> 如果升级到 v1 包，却没有同时将 `telemetry:` 配置迁移到 `observability:` 并创建 Studio 项目，可观测性数据将停止流入。请完整按照 [Mastra Cloud 迁移指南](https://mastra.zisheng.pro/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)更新代码库。每一项都链接到相应变更的详细指南。

> **Codemods:** 我们准备了自动化 [codemod](https://github.com/mastra-ai/mastra/tree/main/packages/codemod)。如有需要，可以一次运行所有 v1 codemod：
>
> ```bash
> npx @mastra/codemod@latest v1
> ```

> **需要迁移数据库:** 如果使用 PostgreSQL 或 LibSQL Storage，则需要运行数据库迁移。详情请参阅 [Storage 迁移指南](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/storage)。

## 按领域划分的破坏性变更

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

## 迁移清单

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

> **Codemods:** 我们准备了自动化 [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/guides/migrations/upgrade-to-v1/tools)
- 重构 `@mastra/core` 导入以使用子路径导入 — [Mastra 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/mastra)
- 将分页从 `offset/limit` 更新为 `page/perPage` — [Storage](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/storage)
- 安装 `@mastra/observability` 并使用 `new Observability()` 包装配置 — [Tracing](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/tracing)
- 从 `telemetry:` 迁移到 `observability:` 配置（从 0.x OTEL 升级时）— [Tracing](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/tracing)

### 中等影响变更

- 在整个代码库中将 `RuntimeContext` 重命名为 `RequestContext` — [Agent 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/agent)、[Tool](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/tools)、[Workflow](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/workflows)
- 将 Storage 方法从 `get*` 更新为 `list*` 模式 — [Storage](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/storage)
- 用 getter 方法替代直接属性访问 — [Mastra 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/mastra)、[Agent 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/agent)
- 如果依赖默认 `thread` 作用域，请更新 Memory 作用域 — [Memory](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/memory)
- 更新 Vector Store 调用以使用命名参数 — [Storage](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/storage)
- 从 Agent 方法中移除 `format` 参数 — [Agent 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/agent)
- 更新 Voice 方法以使用 `agent.voice` 命名空间 — [Agent 类](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/agent)
- 将配置属性 `processors` 重命名为 `spanOutputProcessors`（使用自定义 Processor 时）— [Tracing](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/tracing)

### 低影响变更

- 将分块选项中的 `keepSeparator` 重命名为 `separatorPosition` — [RAG](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/rag)
- 将 `createRunAsync` 重命名为 `createRun` — [Workflow](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/workflows)
- 将 Voice 包名从 `@mastra/speech-*` 更新为 `@mastra/voice-*` — [Voice 包](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/voice)
- 更新 scorer 方法：`runExperiment` → `runEvals`、`getScorerByName` → `getScorerById` — [Evals 和 scorer](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/evals)
- 移除已弃用的 CLI 标志 — [CLI](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/cli)
- 将 Client SDK 类型从 `Get*` 更新为 `List*` — [Client SDK](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/client)
- 用 `retryCount` 替换 `runCount` — [Workflow](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/workflows)
- 将自定义 exporter 方法 `exportEvent` 更新为 `exportTracingEvent` — [Tracing](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/tracing)