Claude Code｜macOS CLI 安裝教學

在 macOS 安裝 Claude Code，重點是選定一種安裝方式，知道它如何更新，並確認你從正確專案資料夾啟動。本篇以官方原生安裝為主要路線，也說明已使用 Homebrew 的讀者如何選擇，最後用待辦專案做一次可驗證的只讀任務。

開始前確認 macOS 符合官方系統需求，準備可用的網路與Claude Code 帳號。本篇不要求先學會所有終端機指令；看不懂路徑時，先讀終端機與 Git 基礎，再回來完成安裝。

開啟終端機並確認環境

閱讀完整文字說明

macOS CLI 安裝教學，以流程和文件圖形呈現教學重點。

在應用程式的工具程式中開啟「終端機」，或用系統搜尋尋找 Terminal。macOS 常見的 shell 是 Zsh，以下基本指令也能在 Bash 使用。先查看目前資料夾與處理器架構，保留結果供安裝遇到問題時核對。

pwd
uname -m
sw_vers

pwd 顯示工作目錄，uname 的 arm64 通常代表 Apple Silicon，x86_64 表示目前程序的架構環境。sw_vers 顯示 macOS 版本。這些資訊能幫你分辨是系統版本、架構，還是單純指令路徑問題；不用把它們貼進 Claude 的對話框執行。

選擇原生安裝或 Homebrew

如果你沒有既有的套件管理習慣，使用官方原生安裝即可。下列命令會下載並執行官方安裝程式；先從來源頁核對網址，再貼到終端機。不要在同一時間又執行另一種安裝方式，否則之後看到不同版本時會難以判斷來源。

curl -fsSL https://claude.ai/install.sh | bash

若你平常已用 Homebrew 管理開發工具，可以使用以下選項。目前官方區分穩定版與最新通道的 cask，選一個符合自己維護習慣的即可。對初學者，穩定通道通常比較容易跟同一組練習環境保持一致；這不代表另一通道不能使用。

brew install --cask claude-code

安裝 Claude Code 本身與安裝 Node.js 是不同工作。原生 CLI 不需要先透過 npm 安裝；本系列的 Todo 開發伺服器才需要 Node.js。當某篇練習要求執行 npm test，應先確認那是專案的工具需求，避免把應用程式依賴誤認成登入條件。

確認終端機找到正確指令

安裝完成後開啟新的終端機分頁，再執行檢查。新分頁能重新取得登入環境；舊分頁的 PATH 不一定已更新。如果安裝程式提示加入某個路徑，先閱讀提示並確認目錄存在，再依照你的 shell 設定處理。

command -v claude
claude --version
claude doctor

第一行應顯示可執行檔位置，第二行應列出版本，doctor 則提供安裝與設定診斷。若 command -v 沒有結果，先確認安裝最後是否成功；如果它找得到位置卻無法執行，再記錄實際錯誤。不要把兩種症狀混在一起，也不要先以 sudo 重裝所有工具。

你可能在網路教學看到要求使用系統管理員權限修正 npm 資料夾。那通常與其他安裝方式或舊環境有關，不必套用到原生安裝。若電腦同時存在舊的 npm 版本與新的原生版本，先查明目前 shell 解析的位置，再依官方移轉或解除安裝說明處理。

從練習資料夾啟動

下載共用練習專案並解壓縮，找出包含 package.json 的那一層。你可以在 Finder 複製資料夾路徑，或把資料夾拖到終端機補上路徑；執行前仍要看清楚組成的命令。下例假設資料夾放在 Projects 中。

cd "$HOME/Projects/claude-todo"
pwd
ls
claude

第一次啟動會引導登入。瀏覽器完成授權後回到終端機，確認是預期帳號與工作目錄。若你使用組織提供的帳號，功能可能受管理設定限制；看到不同選單時先對照資格與版本，不要直接判斷自己的安裝損壞。

請閱讀目前資料夾的 README.md、package.json 和 tests。
列出啟動網站與執行測試的方法，指出測試涵蓋哪些資料操作。
先不要修改檔案，也不要執行安裝或更新。

預期它能指出 npm start、npm test 與新增、切換完成、刪除等操作。你可以自己打開 README 核對，不必因為回覆很流暢就視為正確。這個小任務同時確認 CLI 能啟動、帳號能工作、資料夾也選對了。

更新與日常排錯

Homebrew 使用者可在工作前執行 brew upgrade claude-code，完成後重新檢查版本；原生安裝則依自己的更新通道維護。若團隊要重現特定問題，先記錄當時版本與日期，再比較更新前後行為。教學中的版本數字只是查證背景，不應把未來每個結果鎖死在同一個號碼。

常見的第二個問題是埠號占用：網站不能啟動時，檢查是否已有同一專案的伺服器在跑。第三個問題是登入來源不同：桌面 App 登入的帳號不一定能代表目前 CLI 的實際來源。把安裝、登入、專案執行分開檢查，通常能更快縮小原因。

小練習是關閉對話、重新開啟終端機，再從相同專案啟動一次。完成判準包含找得到 claude、知道更新方式、回覆能對上專案，而且沒有意外修改檔案。接著可用桌面與 CLI 比較決定日常主要使用的介面。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code