PI BLUEBOOK

繁體中文

简体中文

繁體中文

简体中文

外觀模式

MODULE 01 · STEP 02

安裝 Pi，並第一次開啟它 ​

上一課準備好了終端機、空白練習目錄、Node.js 和 npm。現在只做一件事，讓 pi 命令能在這臺電腦上正常開啟和退出。模型登入和第一次任務仍放在後面的獨立驗收階段。

Windows 使用者

本頁的快捷鍵和目錄按 macOS 編寫。Windows 使用者請改走 Windows 中文安裝路徑，不要在命令提示符或 PowerShell 中直接照抄本頁；獨立路徑完成安裝和第一次啟動後，會接回第 3 課。

Linux 使用者使用相同的安裝與驗證命令，但複製、貼上請按當前終端機的快捷鍵操作；如果上一課建立的是 ~/pi-practice，本頁的練習目錄也統一改為它。頁面截圖記錄的是 Mac 環境，Linux 以實際命令輸出和 Pi 狀態列為準。

先開啟終端機。如果你不確定自己現在在哪，先輸入 pwd 看一眼。下面第一條安裝命令安裝的是電腦可呼叫的 Pi 命令；後面“啟動 Pi”時所在的目錄，才決定 Pi 會看到哪些檔案。

1. 選擇一條官方安裝路線 ​

Pi 官方目前為 macOS 和 Linux 提供兩條安裝路線。兩條都安裝同一個 Pi Coding Agent；只選一條，不要連續執行兩種方法。

路線適合誰安裝命令以後怎樣移除
官方安裝器希望由官方指令碼完成環境預檢、安裝和 PATH 處理的初學者curl -fsSL https://pi.dev/install.sh | sh重新執行安裝器並選擇解除安裝
npm 全域安裝已經管理 Node.js/npm，希望明確使用包管理器的讀者npm install -g --ignore-scripts @earendil-works/pi-coding-agent用 npm 全域解除安裝

Pi 1.1.0 的官方安裝器固定全部依賴；從 1.0.1 起，npm 釋出包不再固定間接依賴。npm 路線更新成功後，可能出現遷移到官方安裝器的建議，處理方法見生命週期管理。

本書推薦第一次安裝優先使用官方安裝器。它會檢查 Node.js 22.19.0 或更高版本和 npm；缺少環境時會先詢問是否幫助安裝。上一課已經讓你提前完成這些檢查，所以正常情況下它應直接進入 Pi 安裝流程。

用滑鼠選中下面整行，按 Command + C；點回終端機的閃爍游標，按 Command + V，確認網域是 pi.dev、沒有多出其他文字後按輸入鍵。

bash
curl -fsSL https://pi.dev/install.sh | sh

這條命令會下載並立即執行 Pi 官方安裝指令碼。不要把網域換成搜尋結果、網盤或別人轉發的指令碼地址。安裝器顯示環境檢查和安裝動作時，先讀清提示再繼續；如果它準備安裝你沒有計劃使用的系統元件，取消並保留提示文字。

如果你明確選擇 npm 路線，則執行下面這條，不再執行上面的安裝器：

bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

這兩條路線安裝的都是後面用 pi 命令開啟的完整終端機應用。Pi 使用 Pi Agent Core 等底層元件，但不需要你單獨安裝核心包，再手動拼接一組外掛程式。技能（Skill）和擴充功能（Extension）是以後按任務增加的能力。名稱與層次見Pi 與 Pi Coding Agent 的區別，安裝入口見官方 Quickstart。

npm 路線中的 -g 表示把 Pi 安裝成這臺電腦可以直接呼叫的命令；--ignore-scripts 會禁止依賴包在安裝時執行生命週期指令碼。Pi 的正常 npm 安裝不需要這些指令碼。

安裝開始後，終端機會陸續顯示檢查、下載和安裝資訊。這是正常的等待過程，不需要繼續輸入。無論選擇哪條路線，只有同時滿足下面三點，安裝才算透過：

  1. 終端機重新出現可以輸入的游標；
  2. 最後沒有出現安裝失敗或 npm ERR! 錯誤；
  3. 緊接著執行 pi --version 能返回版本號。

如果安裝超過一會兒仍在滾動文字，繼續等待；如果文字停止但游標沒有回來，也先不要輸入下一條命令。網路慢時下載會比普通命令花更久。

安裝過程結束後，檢查它是否真的可用。

bash
pi --version

這裡輸入的是 pi --version，隨後出現的一串版本號才是輸出。看到版本號、並且游標重新出現，而不是 command not found，就算透過。本書不把某個具體 Pi 版本當成永久要求。官方安裝器路線仍保留 2026-09-23 的核驗記錄；2026-10-12 在獨立 npm 字首中安裝了固定版本 Pi 1.1.0，實際確認版本輸出、啟動、/quit 和再次啟動。沒有重新執行官方安裝器，後續以 Pi 官方 Quickstart 為準。

在真實終端機中檢查 Node.js、npm 與 Pi 版本

這張圖記錄的是 2026-09-09 的本機教學環境。你的版本號可以更新，判斷方法保持不變：三條檢查都有輸出，命令執行結束後終端機游標重新出現。它只能證明當前環境已經裝好，不能當成首次安裝過程的截圖。

小檢查 ​

  • [ ] 安裝命令已結束，終端機沒有顯示失敗或 npm ERR!。
  • [ ] pi --version 顯示了版本號。
  • [ ] 我沒有為安裝輸入 sudo，也沒有輸入電腦帳戶密碼來繞過報錯。
  • [ ] 我記得自己使用的是官方安裝器還是 npm，後續解除安裝時不會混用來源。

2. 第一次啟動 ​

先確認仍然在練習目錄，再啟動 Pi。

bash
cd ~/Downloads/pi-practice
pwd
pi

這三行依次執行。pwd 的輸出必須以 /Downloads/pi-practice 結尾；如果你在上一課用了 pi-practice-2，這裡也要把命令中的目錄名換成自己的名字。確認路徑後，才輸入最後一行 pi。

第一次開啟時，Pi 可能要載入一會兒。Pi 1.1.0 預設使用全屏介面。完成後，你會看到可以輸入訊息的編輯區，下方狀態列會顯示當前目錄和模型。這時你已從普通終端機進入 Pi 互動介面；不要把 Pi 介面中的狀態列文字當作終端機命令輸入。

如果它提示登入，這不代表安裝失敗。認證放在下一課處理。

如果底部顯示的目錄不是剛才 pwd 看到的練習目錄，不要傳送任何任務：在 Pi 中輸入 /quit，回到終端機後重新執行本節的三行命令。

小檢查 ​

  • [ ] 啟動前的 pwd 顯示練習目錄。
  • [ ] Pi 介面已經出現輸入區和底部狀態列。
  • [ ] 我尚未在 Pi 中要求它讀取、建立、修改檔案或執行命令。

3. 學會回到終端機 ​

現在注意：下面的 /quit 是Pi 介面裡的命令，不是在普通終端機裡輸入。先點選 Pi 的輸入區，輸入它並按輸入鍵。

text
/quit

Pi 關閉後會回到原來的終端機提示符。此時再輸入一次 pi 並按輸入鍵；能再次看到 Pi 介面，說明你已經分清了“終端機命令”和“Pi 內命令”兩個狀態。第二次開啟後可再次輸入 /quit，為下一課做準備。

遇到常見失敗時

  • 官方安裝器的環境檢查失敗時，先儲存它顯示的 Node.js、npm 和 PATH 提示；不要緊接著改用 npm 反覆覆蓋安裝。
  • npm 路線出現 npm ERR! 或 EACCES，不要直接加 sudo。先等命令結束；然後拖選“安裝命令”到最後一行報錯，按 Command + C 儲存完整文字，再確認 Node.js 來自官方 LTS 安裝。
  • 安裝成功後仍提示 pi: command not found，完全退出終端機並重新開啟，再執行 pi --version。不要自行修改 PATH。
  • 網路下載失敗，確認網路後用剛才選擇的同一條官方路線重試一次，先別混用安裝器和多個包管理器。
  • 安裝過程中突然出現要求輸入密碼的提示，不要為了繼續而輸入密碼。先按 Control + C 停止，保留螢幕上的文字，再檢查自己是否誤加了其他命令。

本課驗收 ​

  • pi --version 能返回版本號。
  • 我能從自己新增的練習目錄啟動 Pi。
  • 我能用 /quit 退出，再重新啟動。
  • 我知道：終端機游標回來才表示命令已結束；不明白的報錯先完整保留，不靠 sudo 或隨機命令處理。

下一課，登入使用者帳戶並選擇模型 →

已經安裝完成、現在需要升級或解除安裝？檢視 安裝後生命週期管理。