PI BLUEBOOK

简体中文

繁體中文

简体中文

繁體中文

外观模式

MODULE 01 · 安装与基础设置

安装前，先把终端和环境准备好 ​

安装说明里经常只有一行命令，初学者却容易卡在更早的地方。命令应该输入在哪里？现在站在哪个目录？电脑里有没有 Pi 需要的运行环境？

这一课只处理这三件事。先不安装 Extension、Skill 或第三方 Package，也不把真实文件放进练习区。

本课环境

主线按 macOS 编写。Linux 可以使用同样的检查命令；如果没有 ~/Downloads 目录，就把本课和后续安装、登录步骤中的 ~/Downloads/pi-practice 统一换成 ~/pi-practice。Windows 用户不要直接改写本页命令，请改走完整的 Windows 中文安装路径：它会从 Git Bash、Node.js 和练习目录开始，一直带你完成第一次启动。

先认识这个窗口：输入和输出不是一回事 ​

终端是一个用键盘和电脑对话的窗口。你在带光标的那一行输入的是命令；按下回车后，电脑显示出来的文字是输出。输出结束时，会重新出现一条可以输入的行和闪烁光标。

  • Return（回车）会执行当前这一行；本页每个代码框里的内容都要输完再按一次回车。
  • 代码框外的 /Users/...、版本号和报错文字是“你应该看见什么”，不要把它们再输入一遍。
  • 用鼠标拖选代码框中的整行，按 Command + C 复制；点回终端的闪烁光标处，再按 Command + V 粘贴。粘贴后先看一眼：必须与代码框完全相同，再按回车。
  • Linux 的复制、粘贴快捷键随终端而变；可以使用终端菜单或右键菜单，确认粘贴内容完整后再按回车。
  • 命令执行时，先等待。看到新的可输入行，才表示这一条已经结束；不要在等待中连续按回车，也不要把下一条命令粘进去。

如果你复制错了文字，先在终端里按 Control + C 清空当前未执行的输入，再重新粘贴。这里的 Control + C 只用于取消尚未按回车的文字；不要在已经运行的安装命令中随意使用它。

1. 打开正确的输入位置 ​

在 Mac 上，我最推荐使用 iTerm2；如果还没安装，系统自带的“终端”也可以完成本书全部入门步骤。按 Command + Space，输入“iTerm”或“终端”，再按回车。看到带有光标的窗口后，输入下面这行并按回车。Linux 读者打开自己发行版中的终端，执行相同的检查命令。

bash
pwd

pwd 的意思是“我现在在哪里”。例如，你可能会看到：

text
/Users/你的用户名

这一行是输出，不需要输入。它下方重新出现光标，就说明终端已经可以接收下一条命令。

小检查 ​

  • [ ] 我只输入了 pwd，没有输入示例路径。
  • [ ] 我看见了一条以 /Users/ 开头的路径，且光标已回到下一行。

2. 新建一个专用练习目录 ​

不要在下载目录根目录、Obsidian 知识库或正在工作的代码仓库里启动 Pi。先给它准备一个空白练习区。

bash
mkdir ~/Downloads/pi-practice
cd ~/Downloads/pi-practice
pwd
ls -A

这四行要按顺序执行：先执行 mkdir，等光标回来；再执行 cd；然后执行 pwd 和 ls -A。前两行成功时通常不会显示任何文字，直接回到可输入行是正常的。pwd 应当以 /Downloads/pi-practice 结尾，最后的 ls -A 不显示任何文件名才说明目录为空。

如果第一条命令提示 File exists，先不要进入那个目录。它可能保留着旧练习内容。换一个新名字，例如 pi-practice-2，重新执行上面的三个动作。后续课程里出现 pi-practice 时，也要换成你实际使用的名字。

小检查 ​

  • [ ] mkdir 没有显示 File exists 或其他报错。
  • [ ] pwd 最后一段是 Downloads/pi-practice；如果我用了新名字，最后一段就是那个新名字。
  • [ ] ls -A 没有列出文件名。
  • [ ] 这个目录是专门练习用的，里面还没有我的笔记、照片、代码或工作文件。

3. 检查 Node.js 和 npm ​

Pi 的 npm 安装方式需要 Node.js 和 npm。在练习目录运行：

bash
node --version
npm --version

两行都返回版本号，而且 Node.js 不低于 22.19.0，就可以进入下一课。最低版本要求于 2026-10-12 对照 Pi 1.1.0 固定文档核对；本机实际执行了空目录与 Node.js、npm 检查，输出为 v24.14.1 和 11.11.0。安装 Node.js 的流程未重新实测，后续请以 Pi 官方 Quickstart 为准。

例如，第一行可能显示 v22.19.0 或更高版本，第二行会显示另一串版本号。版本号的具体数字可以不同；关键是两条命令都有版本号输出，而且每次输出后光标都会回来。

如果看到 command not found，或 Node.js 版本太低，请先从 Node.js 官方下载页 安装当前 LTS 版。完成官方安装向导后，关闭所有终端窗口，重新打开终端，再回到练习目录执行这两条检查命令。

如果出现你看不懂的错误，不要接着尝试别的命令。用鼠标从“你输入的命令”开始拖选到最后一行错误，按 Command + C 复制，粘贴到一个临时笔记中。保留命令、完整输出和截图；其中如果意外包含账号、密钥或私人路径，先遮住这些内容再发给他人。

先别这样做

不要为了跳过权限错误随意在 npm 命令前加 sudo，也不要随机执行网上的 PATH 修复命令。保留完整报错，后面才能准确判断问题。

小检查 ​

  • [ ] node --version 输出的版本不低于 v22.19.0。
  • [ ] npm --version 也输出了版本号。
  • [ ] 如果失败，我已保留原始报错，而不是用未知命令继续试错。

本课验收 ​

  • 我能打开终端，并用 pwd 查看当前位置。
  • 我新建了一个空白的 pi-practice 目录。
  • ls -A 没列出文件，说明练习目录开始时为空。
  • node --version 不低于本页要求，npm --version 返回版本号，两条命令结束后光标都重新出现。

下一课，安装并启动 Pi →