企业官网建设流程全解析

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

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

create-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-mastra@latest # Yarn yarn dlx create-mastra@latest # pnpm pnpm create mastra@latest

三种写法分别利用了npx、yarn dlx和pnpm create的「下载即执行」能力，因此你不需要先在全局或本地安装create-mastra包。每次运行都会拉取 npm 上最新的发布版本。

交互式使用流程

直接运行上述命令后，create-mastra会进入交互式引导。从 create.ts 的提示逻辑可以还原出完整流程：

1. 项目命名：询问What do you want to name your project?（默认占位my-mastra-app）。工具会校验目录名是否合法（非空、不以.或..结尾、不含路径分隔符、不是 Windows 保留名等），并检查当前目录下是否已存在同名文件或目录；
2. 选择默认模型提供商：从 OpenAI、Anthropic、Gemini（Google）、xAI 四个选项中挑选一个作为默认 LLM provider；
3. 填写 API Key（可选）：可以「Skip for now」跳过，也可以当场以密码输入方式填写，API Key 会被写入生成项目的.env；
4. 可观测性接入（可选）：询问是否启用 Mastra platform observability，选择 Yes 会触发登录与组织选择流程；
5. 脚手架生成：克隆默认模板、按所选 provider 适配配置、安装依赖、初始化 Git 仓库，并在检测到编码助手（Coding Agent）时安装对应的 Mastra Skills。

如果中途按下Ctrl+C（SIGINT），CLI 会通过 runCreatePrompt 中的 AbortController 优雅取消操作，而不是留下半成品目录。

非交互式 CLI 选项

交互式引导覆盖了大部分场景；对于 CI 或脚本化初始化，可以传入命令行参数跳过提问。先查看完整帮助：

npx create-mastra@latest --help

以下选项均来自 configureCreateCommand 的真实定义：

需要注意几个隐含约束（由 validateCreateOptionConflicts 强制校验）：

• --empty与--template不能同时使用；
• --llm/--llm-api-key只能配合默认模板使用（即不能与--empty、--template同时出现），否则直接报错。

例如，用 OpenAI 作为默认 provider、跳过交互、命名项目my-agent的全自动命令形如：

npx create-mastra@latest my-agent --llm openai --llm-api-key sk-xxx

三种创建模式

从源码看，create-mastra存在三种明确的创建模式（CreateMode，见 command.ts）：

• managed（默认）：克隆官方默认的 Agent Harness 模板，并按你选择的 provider 自动适配.env、模型配置等，是绝大多数场景的首选；
• template：通过-t/--template从社区/官方模板仓库创建。模板可来自模板 slug（例如template-browser-agent，仓库内模板清单见 templates 目录），也可以直接传一个公开 GitHub URL；
• empty：通过--empty生成一个尽可能精简的空脚手架，不克隆任何模板。

模式判定逻辑getCreateMode非常简单：--empty优先返回empty，否则有--template返回template，都不带则走managed（见 command.ts）。

默认模板：Agent Harness

当处于 managed 模式且未指定模板时，工具克隆的是 template-agent-harness（源码常量DEFAULT_TEMPLATE位于 create.ts），该模板预置了 agent 声明、工具/工作流目录结构等最小可运行的骨架。

项目名校验规则

项目名并非随便传什么都能用。validateProjectName（见 command.ts）会校验：

• 长度在 1～214 个字符之间；
• 不能是绝对路径，不能包含/或\；
• 不能是.或..；
• 匹配^[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 解析要写入的版本标签：

1. 先执行npm dist-tag ls create-mastra查询 registry 上的所有 dist-tag；
2. 找到与本包版本精确匹配的 tag；若本包是预发布版本（如1.2.3-beta.4），则优先匹配对应的预发布渠道（beta、snapshot等）；
3. 匹配不到时按latest>beta> 字典序兜底，必要时回退到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