create-mastra 快速上手指南：一行命令搭建 Mastra AI 应用项目

create-mastra 快速上手指南一行命令搭建 Mastra AI 应用项目【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastracreate-mastra是 Mastra 官方推荐的项目初始化工具用于快速生成基于 TypeScript 的 AI 应用与 Agent 工程骨架。本文围绕该工具的使用方式展开覆盖三种主流包管理器的调用方法、交互式引导流程、全部非交互 CLI 选项并结合仓库源码剖析其背后的三种创建模式、模板克隆、依赖安装与版本解析机制帮助你从「跑起来」到「跑明白」。环境要求与安装create-mastra是一个一次性项目生成器one-time project generator无需提前安装通过包管理器直接执行即可。唯一的硬性环境要求是 Node.js 版本[!IMPORTANT] 请确保系统已安装Node.js 22.13.0 或更高版本。这一要求与 package.json 中声明的engines.node: 22.13.0完全一致Node 版本不满足时包管理器会直接阻止运行。根据你使用的包管理器选择对应的调用方式# npm npx create-mastralatest # Yarn yarn dlx create-mastralatest # pnpm pnpm create mastralatest三种写法分别利用了npx、yarn dlx和pnpm create的「下载即执行」能力因此你不需要先在全局或本地安装create-mastra包。每次运行都会拉取 npm 上最新的发布版本。交互式使用流程直接运行上述命令后create-mastra会进入交互式引导。从 create.ts 的提示逻辑可以还原出完整流程项目命名询问What do you want to name your project?默认占位my-mastra-app。工具会校验目录名是否合法非空、不以.或..结尾、不含路径分隔符、不是 Windows 保留名等并检查当前目录下是否已存在同名文件或目录选择默认模型提供商从 OpenAI、Anthropic、GeminiGoogle、xAI 四个选项中挑选一个作为默认 LLM provider填写 API Key可选可以「Skip for now」跳过也可以当场以密码输入方式填写API Key 会被写入生成项目的.env可观测性接入可选询问是否启用 Mastra platform observability选择 Yes 会触发登录与组织选择流程脚手架生成克隆默认模板、按所选 provider 适配配置、安装依赖、初始化 Git 仓库并在检测到编码助手Coding Agent时安装对应的 Mastra Skills。如果中途按下CtrlCSIGINTCLI 会通过 runCreatePrompt 中的 AbortController 优雅取消操作而不是留下半成品目录。非交互式 CLI 选项交互式引导覆盖了大部分场景对于 CI 或脚本化初始化可以传入命令行参数跳过提问。先查看完整帮助npx create-mastralatest --help以下选项均来自 configureCreateCommand 的真实定义选项说明默认值/备注[project-name]位置参数指定项目目录名缺省时交互式询问--empty创建空项目仅生成最小脚手架与--template互斥-l, --llm provider指定模型提供商openai、anthropic、google、xai仅限默认模板managed 模式-k, --llm-api-key key直接提供模型提供商 API Key仅限默认模板managed 模式--no-skills不安装 Mastra Skills默认安装--no-git不初始化 Git 仓库默认初始化--no-install跳过依赖安装默认安装-t, --template [template]从模板 slug 或公开 GitHub URL 创建省略值时交互式选择模板与--empty互斥--timeout milliseconds依赖安装超时时间默认60000ms需要注意几个隐含约束由 validateCreateOptionConflicts 强制校验--empty与--template不能同时使用--llm/--llm-api-key只能配合默认模板使用即不能与--empty、--template同时出现否则直接报错。例如用 OpenAI 作为默认 provider、跳过交互、命名项目my-agent的全自动命令形如npx create-mastralatest my-agent --llm openai --llm-api-key sk-xxx三种创建模式从源码看create-mastra存在三种明确的创建模式CreateMode见 command.tsmanaged默认克隆官方默认的 Agent Harness 模板并按你选择的 provider 自动适配.env、模型配置等是绝大多数场景的首选template通过-t/--template从社区/官方模板仓库创建。模板可来自模板 slug例如template-browser-agent仓库内模板清单见 templates 目录也可以直接传一个公开 GitHub URLempty通过--empty生成一个尽可能精简的空脚手架不克隆任何模板。模式判定逻辑getCreateMode非常简单--empty优先返回empty否则有--template返回template都不带则走managed见 command.ts。默认模板Agent Harness当处于 managed 模式且未指定模板时工具克隆的是 template-agent-harness源码常量DEFAULT_TEMPLATE位于 create.ts该模板预置了 agent 声明、工具/工作流目录结构等最小可运行的骨架。项目名校验规则项目名并非随便传什么都能用。validateProjectName见 command.ts会校验长度在 1214 个字符之间不能是绝对路径不能包含/或\不能是.或..匹配^[a-z0-9][a-z0-9._-]*$小写字母/数字开头仅允许小写字母、数字、点、下划线、连字符不能是con、prn、aux、nul、com1~com9、lpt1~lpt9等 Windows 保留名。内部工作流程与源码原理create-mastra本身是薄封装它的入口 index.ts 只做三件事——读取自身版本、初始化 PostHog 分析上报、把 commander 命令与 runCreateCommand 对接真正的脚手架逻辑位于packages/cli包的 create 命令中。原子化生成先暂存后发布create.ts采用「暂存目录」机制保证生成过程的原子性先在当前目录下创建临时 staging 目录克隆模板/写入脚手架、适配 provider 配置、安装依赖全部在 staging 内完成最后通过publishStagedProject一次性移动到目标目录并在finally中清理暂存目录见 create.ts。因此即使中途失败也不会在项目目录留下残缺文件。版本标签解析managed 模式下生成的项目需要引用对应版本的 Mastra 依赖。create-mastra通过 getCreateVersionTag 解析要写入的版本标签先执行npm dist-tag ls create-mastra查询 registry 上的所有 dist-tag找到与本包版本精确匹配的 tag若本包是预发布版本如1.2.3-beta.4则优先匹配对应的预发布渠道beta、snapshot等匹配不到时按latestbeta 字典序兜底必要时回退到latest并打印警告。这一逻辑在 utils.test.ts 中有 9 组用例覆盖包括预发布渠道匹配、快照版本0.0.0-create-mastra-e2e-test-...、registry 不可用时的回退等边界场景行为可完全由测试佐证。创建后的收尾工作脚手架就位后runPostCreateSetup见 create.ts还会依次完成Skills 安装检测本机可用的 Coding Agent如 Claude Code、Cursor 等为其安装对应的 Mastra Skills可用--no-skills跳过Git 初始化在项目内执行git init可用--no-git跳过若当前已在 Git worktree 中会采取兼容策略可观测性配置若交互阶段选择了启用 Mastra platform observability会静默执行登录、创建平台项目并把MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID写入.env失败时则写入占位符并提示前往平台手动创建。分析上报生成过程会上报匿名的命令执行指标命令、模式、skills/git 选项、provider 选择等用于官方统计 CLI 使用情况数据通过 PostHog 发送见 index.ts。失败与取消场景也都会被记录便于官方改进引导流程。生成后的项目结构成功创建后你会得到如下结构以 managed 默认模板为例my-mastra-app/ ├── src/ │ ├── agents/ # Agent 定义默认示例 agent │ ├── tools/ # 自定义工具 │ ├── workflows/ # 工作流定义 │ └── mastra/ ├── .env / .env.example # 模型 API Key、平台凭证MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID ├── package.json └── .git/随后即可按模板 README 的指引填充.env、运行npm run dev启动你的第一个 Mastra 应用。若选择了--empty生成的是可自行从零组织目录的精简骨架若使用-t slug则得到对应示例模板如浏览器 Agent、PDF 问答等的完整实现。版本与更新create-mastra的版本历史与发布说明记录在 CHANGELOG.md。由于它始终从 registry 拉取最新版本无需手动升级在 CI 场景中建议固定create-mastra版本号以保证脚手架结果可复现。小结create-mastra把「新建 Mastra 项目」压缩为一条命令交互模式适合日常开发非交互选项--empty、--llm、--template、--timeout等适合脚本与 CI底层则通过暂存目录、模板克隆、provider 适配、版本标签解析与收尾配置保证生成结果一致、干净、开箱即用。想要继续深入可以从 create 命令实现 与 命令参数定义 读起仓库中的测试用例utils.test.ts也为理解版本解析行为提供了极佳的参考。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考