Mastra 开发指南：从环境搭建到本地验证的完整实践手册

Mastra 开发指南：从环境搭建到本地验证的完整实践手册

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本指南面向希望为 Mastra 仓库贡献代码或深入理解其构建流程的开发者。围绕仓库根目录的 DEVELOPMENT.md 展开，结合 package.json、turbo.json、pnpm-workspace.yaml 等真实配置，系统讲解开发环境搭建、包构建、本地测试的"三步迭代法"、Vitest 测试体系以及提交 PR 的完整规范。读完你将掌握 Mastra 这个大型 pnpm + Turborepo 单仓库的日常开发工作流，并能独立完成从改代码到验证再到提 PR 的全过程。

前置条件：工具链与版本要求

在开始之前，请确保本机满足以下环境要求：

需要注意两点版本细节：

• 仓库根目录 package.json 的engines字段声明"pnpm": ">=11.0.0"，而packageManager字段锁定为pnpm@11.21.0，因此建议通过 Corepack 启用 pnpm，保证与仓库锁定版本一致，避免因 pnpm 版本差异导致 lockfile 解析异常。
• preinstall脚本为npx only-allow pnpm（见 package.json），即使用 npm 或 yarn 安装依赖会被直接拦截——这是 Mastra 强制统一包管理器的第一道防线。

搭建开发环境

克隆仓库并启用 Corepack

git clone https://github.com/mastra-ai/mastra.git cd mastra

随后启用 Corepack，确保 pnpm 使用仓库锁定的版本：

corepack enable

安装依赖并构建初始包

pnpm run setup

setup脚本定义在 package.json："setup": "pnpm install && pnpm run build"。它先安装全部 workspace 依赖，再执行一次完整构建。这一步会构建 CLI 包（packages/cli），它是其他包在开发阶段被引用的前置产物——例如examples/agent的 devDependencies 就通过"mastra": "link:../../packages/cli"本地链接到 CLI 包（见 examples/agent/package.json）。

认识仓库结构

Mastra 是一个典型的 pnpm workspace 单仓库，pnpm-workspace.yaml 声明了所有纳入管理的包组，主要包括：

• packages/*：核心框架、CLI、RAG、Memory、Evals、MCP 等核心包
• stores/*：向量与数据存储适配器（pg、qdrant、redis、libsql 等）
• deployers/*：云部署适配器（cloudflare、vercel、netlify 等）
• server-adapters/*：服务端框架适配（express、fastify、hono、nestjs 等）
• client-sdks/*：客户端 SDK（client-js、react、ai-sdk）
• voice/*、auth/*、integrations/*、observability/*、channels/*等

根目录 turbo.json 定义了所有任务的执行规则：build任务dependsOn: ["^build"]（先构建依赖再构建自身），输出产物写入dist/**；dev任务持久运行且关闭缓存；typecheck同样依赖上游构建完成。

构建包：三种粒度与常见坑

构建全部包

pnpm build

该命令在 package.json 中的真实定义为：

pnpm turbo build --filter "!./examples/*" --filter "!./examples/**/*"

即通过 Turborepo 并行构建所有包，但显式排除examples/下的示例项目（示例项目是消费端，不参与发布构建）。

按组构建

Mastra 提供了按业务分组的构建脚本，对应脚本定义同样可在 package.json 中查到：

pnpm build:packages # 所有核心包（./packages/*） pnpm build:deployers # 所有部署适配器（./deployers/*） pnpm build:combined-stores # 所有向量与数据存储（./stores/*） pnpm build:speech # 所有语音处理包（./voice/* 语音能力） pnpm build:clients # 所有客户端 SDK（./client-sdks/*） pnpm build:server-adapters # 所有服务端框架适配（./server-adapters/*） pnpm build:integrations # 所有第三方集成（./integrations/*） pnpm build:auth # 认证相关（./auth/* + ./packages/auth + server-adapters） pnpm build:observability # 可观测性接入（./observability/*） pnpm build:workspaces # 工作空间/沙箱提供方（./workspaces/*）

构建单个包

pnpm build:core # 核心框架包（packages/core） pnpm build:cli # CLI 与 playground 包（packages/cli） pnpm build:deployer # 部署器包（packages/deployer） pnpm build:rag # RAG 包（packages/rag） pnpm build:memory # Memory 包（packages/memory） pnpm build:evals # 评估框架包（packages/evals） pnpm build:docs-mcp # MCP 文档服务器（packages/mcp-docs-server）

这些脚本在根 package.json 中都是pnpm turbo build --filter ./packages/<name>的形式，只触发目标包及其依赖链的构建。

内存溢出问题的解法

Mastra 的构建链路较长（TypeScript 编译 + 打包 + dts 生成），在机器内存有限时可能遇到：

Error [ERR_WORKER_OUT_OF_MEMORY]: Worker terminated due to reaching memory limit: JS heap out of memory

解决办法是为 Node 显式提高堆大小，在构建命令前加上：

NODE_OPTIONS="--max-old-space-size=4096" pnpm build

将堆上限调至 4GB 通常足以应对单包或全量构建；如果仍溢出可继续调大该值。

测试本地改动：经典三步迭代法

Mastra 官方推荐的本地开发流程非常简洁，只有三步：

1. 修改相关包的源码
2. 构建被改动的包
3. 在examples/agent项目中验证改动效果

第一步：修改源码

编辑目标包的源文件，同时记录下改动涉及的包名，便于下一步用--filter精确构建。若改动跨包（例如同时改了@mastra/core与mastra），则多个 filter 都要跟上。

第二步：用 Turborepo watch 模式构建

# 只监听并重建单个包，适合聚焦改动 pnpm turbo watch build --filter="@mastra/core" # 同时监听多个包 pnpm turbo watch build --filter="@mastra/core" --filter="mastra" # 监听全部包（不推荐，开销大；不确定依赖关系时可用） pnpm turbo watch build

turbo watch的核心价值在于：源码保存后自动增量重建对应包的dist，省去每次手动 build。它依赖 turbo.json 中build任务的outputs: ["dist/**", ".next/**", ...]声明，Turborepo 会据此判断哪些产物需要重建。若不需要 watch，可退回到一次性构建：

pnpm build

第三步：在 examples/agent 中验证

打开一个新终端，进入示例项目并安装依赖：

cd examples/agent pnpm install --ignore-workspace

务必使用--ignore-workspace，否则 pnpm 会尝试将示例项目接入 workspace 依赖解析，导致链接到源码路径的包无法正确安装。

安装完成后启动 Mastra 开发服务器：

pnpm mastra:dev

mastra:dev实际执行的是mastra dev（见 examples/agent/package.json）。由于第二步的turbo watch已在持续重建包产物，此时只需重启开发服务器即可看到改动生效。examples/agent是一个覆盖面很广的演示项目，其 src/ 中包含 agent 定义、MCP 工具、人机协同（hitl-approval-recall）、评估种子数据（seed-evaluation）等典型场景，可以方便地对各类改动做冒烟验证。

测试体系：Vitest 全量 / 分组 / 监听

Mastra 使用 Vitest 作为测试框架，根目录 vitest.config.ts 会自动发现各包（packages/*、stores/*、deployers/*、voice/*、server-adapters/*、client-sdks/*、auth/*、observability/*、pubsub/*、signals/*、workflows/*、code-mode/*等）的vitest.config.ts，并把它们注册为 Vitest 的 projects（workspace 模式），从而实现一条命令跑全仓测试。

常用测试命令

pnpm test # 运行全部测试（vitest run） pnpm test:watch # 监听模式，开发时持续运行 # 按包/分组运行 pnpm test:core # Core 包测试 pnpm test:cli # CLI 与 create-mastra 测试 pnpm test:rag # RAG 包测试 pnpm test:memory # Memory 包测试 pnpm test:evals # Evals 包测试 pnpm test:clients # 客户端 SDK 测试 pnpm test:combined-stores # 所有 stores 的测试 pnpm test:deployer # Deployer 包测试 pnpm test:server # Server 包测试 pnpm test:mcp # MCP 包测试 pnpm test:docs-mcp # MCP 文档服务器测试 pnpm test:auth # auth 目录 + server-adapters 测试

这些脚本同样可以在 package.json 中逐一核对，例如pnpm test:core的真实命令是pnpm --filter ./packages/core test。

环境变量与本地服务

部分测试依赖外部服务或 API Key（例如向量存储、模型提供商的集成测试）。根目录 package.json 提供了两个 docker-compose 包装脚本：

pnpm run dev:services:up pnpm run dev:services:down

dev:services:up会依据 .dev/docker-compose.yaml 启动以下开发服务：

对应的环境变量需要在仓库根目录创建.env文件：

OPENAI_API_KEY= COHERE_API_KEY= PINECONE_API_KEY= CLOUDFLARE_ACCOUNT_ID= CLOUDFLARE_API_TOKEN= DB_URL=postgresql://postgres:postgres@localhost:5432/mastra

DB_URL与 docker-compose 中默认的POSTGRES_USER=postgres、POSTGRES_PASSWORD=postgres、POSTGRES_DB=mastra完全对应。如果对某个测试具体需要哪些变量不确定，可以在 PR 中询问维护者，或直接交给 CI 运行验证。

其它质量检查命令

除了构建与测试，仓库还提供以下命令用于日常开发质量保障：

pnpm typecheck # 对所有包执行 TypeScript 类型检查（跳过 explorations） pnpm lint # oxlint + 格式检查（排除 examples/docs/explorations） pnpm format # 自动修复格式（eslint fix + oxfmt） pnpm affected-tests # 根据 git diff 计算受影响的测试并运行 pnpm check:core-imports # 校验 core 包导入规范（scripts/check-core-imports.ts）

其中affected-tests对应 scripts/affected-tests.mjs，会基于分支改动自动圈定受影响的测试范围，在大型 PR 中能显著节省本地验证时间。

贡献指南：从分支到合并

如果你打算提交 PR，请严格按照以下流程，并牢记核心约束：PR 必须链接到相关 issue，否则会被关闭。

1. 创建功能分支

git checkout -b feature/your-feature-name

2. 确保测试通过

pnpm test

3. 生成 changeset

pnpm changeset

Mastra 使用 Changesets 管理版本发布，根目录 package.json 中changeset脚本指向@internal/changeset-cli（仓库自带的定制版 changeset 工具）。按照交互提示选择受影响包、变更类型（patch/minor/major）并填写变更说明，生成的 changeset 文件会随 PR 一起提交。

4. 打开 PR

在 PR 描述中链接相关 issue（例如Fixes #1234），并清晰描述问题与解决方案。没有链接 issue 的 PR 会被自动关闭。

5. 处理自动化评审意见

提交后，Coderabbit 与 Mastra Platform 会在 PR 上自动留下评审意见。请逐一处理：要么按建议修改，要么在评论区说明不同意的理由，供维护者裁定。

社区协作补充

• issue 优先：相比直接开 PR，提交高质量、可复现的 issue 同样是高效的贡献方式。Mastra 要求"最小复现"（minimal reproduction）：从npm create mastra@latest创建全新项目，用最少的代码复现 bug，这既能帮助维护者定位，也常常能让提交者自己发现问题根源。详细要求见 CONTRIBUTING.md。
• 新功能先讨论：新增功能或改动现有行为前，应先提交 feature request 并等待维护者反馈；带有status: needs triage或status: needs approval标签的 issue 对应的 PR 会被自动关闭（见 CONTRIBUTING.md）。
• EE 代码的许可约定：仓库采用双许可模型，ee/目录下的代码属于 Mastra Enterprise License。向packages/core/src/auth/ee/等 EE 目录贡献代码即表示同意你的贡献以企业许可证授权（见 CONTRIBUTING.md）。

文档贡献

文档站点基于docs/目录构建，涉及文档修改时请遵循 docs/CONTRIBUTING.md 中的贡献指引，包括内容风格、frontmatter 校验、sidebar 排序等规范（docs 目录下还有配套的 validate-frontmatter.ts、validate-sidebar-docs.ts 等校验脚本）。

常见问题速查

总结

Mastra 的开发工作流可以浓缩为"构建驱动、示例验证、分层测试"三条主线：pnpm run setup一键就绪，pnpm turbo watch build --filter提供精确的增量构建，examples/agent作为最真实的验收沙箱，配合 Vitest 的 projects 机制实现全仓/单包灵活测试。这套模式对于大型 pnpm 单仓库项目具有很强的参考价值，无论是贡献 Mastra 本身，还是借鉴其工程化思路搭建自己的 AI 框架项目，都值得直接套用。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra