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 →