裝 Claude Code 最折磨人的地方,常常不是裝不起來。指令照著敲、帳號也登進去了,結果第一個真實請求發出去,終端機就那樣停著,半天沒動靜。你開始懷疑是不是哪一步漏了,於是反覆重裝——但問題根本不在安裝。
這篇是我在一台全新機器上會照著走的順序。從核對環境,到挑安裝方式,再到確認連線,中間那個多數教學都跳過的環節,正是讓「裝好卻跑不動」變成「裝好就能用」的關鍵。
先把兩件事分開:裝得起來,跟跑得動
安裝順不順利,只跟本地環境和指令有關;首次執行順不順利,還多了一個變數——你到 API 之間那段網路。這兩件事經常被混為一談。
結果就是:一條慢線路造成的卡頓,被當成安裝失敗來處理。重裝十次也修不好,因為要修的根本不是安裝。先認清這一點,後面排查會省下大把時間。
這份筆記大致寫給兩種人。一種是完全的新手,有了符合條件的帳號,但連終端機都沒怎麼開過,只想要一條最短、最不會出錯的路。另一種是要在團隊內統一環境的人——讓每位工程師筆電上的安裝行為一致,尤其是那些網路較遠、第一次請求最容易出狀況的同事。兩種人要的其實是同一個結果:裝得起來,而且第一次執行不逾時。
動手前,先核對環境
Claude Code 支援 macOS、Linux 和 Windows。如果走 npm 套件,Node.js 要 18 以上;真要我推薦,直接上 Node.js 22 LTS,乾淨,測試也充分。
另外,終端機工具不在免費網頁方案裡,你得有一個符合條件的帳號。這些都備齊了,跑一句 node --version 確認版本。
別小看這一步。絕大多數所謂的安裝失敗,追到底都是 Node 版本不對,而不是什麼疑難雜症。提前對一次,後面少踩一堆坑。
npm 還是原生安裝,看你怎麼管 Node
有兩條官方支援的路。
原生安裝程式不依賴任何套件,背景自動更新,單台工作機用它最省心。npm 這條——npm install -g @anthropic-ai/claude-code——同樣完整支援,適合本來就在管 Node 工具鏈的人。
不論走哪條,記住一條:npm 指令前面別加 sudo。碰到權限錯誤,正確做法是用 Node 版本管理工具去修,而不是用 root 身分硬裝上去。後者當下看起來解決了,後續更新和卸載都會給你添麻煩。
登入、驗證,然後發一條最簡單的請求
打 claude 啟動,跟著提示完成登入。接著別急著用,先做幾個動作確認它真的端到端通了:
claude --version—— 確認執行檔在- 工作階段裡跑
/doctor—— 把潛在設定問題提前抓出來 - 發一條最瑣碎的提示,比如「列出這裡的檔案」,看它回不回
這一條往返要是乾淨走完,安裝這邊就沒問題了。
但如果能登入、第一個真實請求卻卡住——這恰恰說明安裝是好的,問題在連線。下一段就是寫給這種情況的。
多數教學跳過的那一步:把首次連線弄穩
終端機裝得乾乾淨淨、登入也順暢,只要到 API 的路徑又慢又掉包,它照樣表現得像壞了。原因在於,一次 agent 執行背後是一連串往返,中間任何一個環節卡住,整個請求看起來就像凍住。
先測個基準:對 API 主機 ping 一下。如果你離伺服器很遠、延遲明顯偏高,那瓶頸就清楚了——不是機器,是路。
這時候把流量走一條優化過的路徑就能解決。NasaCode 的低延遲節點正是為開發者這類往返場景調校的,目的是讓一次全新安裝,無論你坐在伺服器隔壁還是隔著大半個地球,首次執行的體感都差不多。
三種安裝方式怎麼選
| 方式 | 相依 | 更新 | 適合 |
|---|---|---|---|
| 原生安裝程式 | 無 | 背景自動 | 單台工作機,起步最快,建議當預設 |
| npm 全域安裝 | Node.js 18+ | 手動重裝 latest | 本來就在管 Node 工具鏈的人,別用 sudo |
| 版本管理工具安裝 | nvm 等 | 手動、彼此隔離 | 同機要切多個 Node 版本,修權限問題也最乾淨 |
新手沒特別理由的話,原生安裝程式就好,摩擦最小。除非你明確需要管好幾個 Node 版本,才往 npm 或版本管理工具這邊轉。
幾個常被問到的問題
一定要付費帳號才能用嗎?
是的,需要符合條件的付費方案或主控台存取,免費網頁層不含這個終端機工具。建議裝之前先把帳號確認好,免得卡在登入那關進退兩難。
npm 安裝報權限錯誤,是哪裡出問題?
八成是用了提升權限,或者裝到了系統內建那個 Node 上。用版本管理工具重裝,讓全域套件落在你的使用者空間,錯誤通常就沒了。
裝好了,可是第一個指令就卡住
安裝沒事,連線有事。測一下到 API 主機的延遲,高的話路徑就是瓶頸,換一條優化路徑能讓第一次 agent 執行順利跑完。
完全是新手,該選哪種裝法?
原生安裝程式。等到有了「要管理多個 Node 版本」這種具體需求,再考慮其他方式不遲。
說到底,一次乾淨的 Claude Code 上手是四步,不是一步:核對需求、按你機器的情況選安裝方式、用一條瑣碎提示登入驗證,最後在真正依賴它之前,把到 API 的那段路弄穩。前三步做得再漂亮,漏掉最後一步,一個順利的安裝也可能在你第一個真實任務上掉鏈子。
如果你人在離伺服器較遠的地方,裝 Claude Code 的同時順手把 NasaCode 用戶端也裝上,首次工作階段需要的那條穩定低延遲連線就一併備齊了。