第 1 课
用 create-mastra CLI 脚手架项目并打开 Studio
非交互或交互方式创建 Mastra 工程，安装依赖，启动 Studio，在浏览器里与首个 Agent 对话。
课程目录第 1 / 2 课
学习位置仅保存在当前浏览器，有效期 180 天。
图文讲义
Mastra 官方推荐的最快起步方式是 create-mastra CLI：它会生成带 workspace tools、memory、task tracking、web access、schedules、storage 与 observability 的 Agent harness，并为已安装的编码助手安装 Mastra skills。
本课目标：脚手架出可运行工程 → 配置 API Key → 启动 Studio → 与首个 Agent 对话。
官方来源
步骤 1：确认 Node.js 与包管理器
目标：确认本机可执行 node / npm，再决定后续是脚手架还是直接跑 TS。
操作
node -v
npm -v
预期结果
- 终端打印版本号，例如
v22.x.x与10.x.x - CLI 脚手架本身不强制 Node 22；若下一课要用 Node 直接跑 TypeScript 文件，官方要求 Node.js 22.18.0+
排错
- 命令未找到：先安装 Node（建议 LTS 或 22+），再开新终端重试
- 版本过旧：用 nvm / fnm / 官网安装包升级后再继续
步骤 2：准备模型供应商 API Key
目标：让 Mastra 能按 provider/model 字符串自动读取环境变量。
操作
- 选定一个供应商（本课示例常用 OpenAI）。
- 按官方约定设置环境变量（当前会话）：
export OPENAI_API_KEY=你的密钥
其他常见变量：
- Anthropic →
ANTHROPIC_API_KEY - Google →
GOOGLE_API_KEY
完整对照见 Models 环境变量。
本课示例模型 ID 使用官方文档当前示例：openai/gpt-5.6-sol（不要改成过时别名）。
预期结果
echo "$OPENAI_API_KEY" | head -c 8
能看到密钥前缀（勿把完整密钥贴到聊天或截图）。
排错
- Studio / generate 报鉴权失败：确认变量名与
provider/前缀一致，且已在启动 Studio 的同一终端会话中 export
步骤 3：交互式创建项目
目标：用官方 CLI 生成可立即打开 Studio 的工程。
操作
在空目录外执行（官方 npm 示例）：
npm create mastra@latest
按提示填写：
- 项目名称（例如
weather-agent-demo） - 模型供应商（如 OpenAI）
- 可选粘贴 API Key
CLI 会安装依赖；若不在 Git 仓库中，还会创建初始 commit。
等价包管理器（官方并列提供）：
pnpm create mastra@latest
yarn create mastra
bunx create-mastra
预期结果
- 终端无安装错误，提示进入项目目录
- 目录中出现
package.json，以及src/mastra（或 CLI 生成的等价结构）
排错
- 网络超时：换镜像源或重试；确认能访问 npm registry
- 权限错误：不要用
sudo npm；改用用户目录或修复 npm 前缀权限
步骤 4：非交互创建（可选，适合自动化）
目标：一条命令指定 LLM 供应商，跳过交互问答。
操作
npm create mastra@latest -- --llm openai
把 openai 换成 anthropic、google 或 xai。
只要空壳、不要预置 Agent / 模型供应商：
npm create mastra@latest -- --empty
预期结果
与步骤 3 相同：工程目录生成且依赖安装完成。
排错
- 参数被 npm 吃掉：务必保留
--分隔符（create mastra@latest -- --llm …）
步骤 5：进入项目并启动 Studio
目标：打开 Mastra 项目的交互 UI（Studio），验证首个 Agent 可对话。
操作
cd weather-agent-demo
npm run dev
（若 CLI 输出的脚本名不同，以终端提示为准；官方 Quickstart 写明可以立刻打开 Studio。）
浏览器打开日志打印的本地地址（常见为 http://localhost:4111 一类端口——以你本机输出为准）。
在 Studio 中选择默认 Agent，发送一句简短中文或英文测试消息。
预期结果
- 终端显示 Studio / dev server 已监听
- 浏览器可打开交互界面
- Agent 返回文本回复（需步骤 2 的 API Key 有效）
排错
- 页面空白或连不上：看终端是否仍在跑；端口是否被占用；换日志里打印的实际 URL
- 有界面无回复：回到步骤 2 检查环境变量；确认模型 ID 与供应商匹配
步骤 6：本课验收清单
对照以下项打勾后再进入下一课：
-
npm create mastra@latest（或非交互等价命令）成功结束 - 已设置对应供应商环境变量（如
OPENAI_API_KEY） - Studio 可打开，并能收到 Agent 回复
- 项目中可见
@mastra/core/mastra等依赖
下一课：不依赖脚手架，手工用 createTool + Agent + generate 跑通最小可调用工具 Agent。
截图说明：课程封面使用 Mastra 官网官方 OG 图；Studio 界面以你本机 CLI 输出为准。来源 mastra.ai
