裝完沒反應：五個檢查，照順序做完再重裝

你照著安裝教學做完了，然後打那個指令，得到 command not found。或者圖示點了沒反應。或者視窗閃一下就消失。

第一個念頭通常是「我裝壞了，重裝一次」。

重裝幾乎從來不是解法。 因為「裝完沒反應」有五種原因，其中只有一種跟安裝本身有關，而那一種通常也不是重裝能修的。重裝只是讓你多花十分鐘，並且錯過真正的原因。

這篇按檢查成本從低到高排序。照順序做，大多數情況在前兩步就會找到答案。

前置：這篇會用到終端機。如果還不熟，先讀 終端機與 CLI 保命指南。指令貼進去失敗先看 把指令從網頁貼進終端機。

步驟

步驟一：它其實裝好了，只是找不到

這是最常見的原因，佔了一半以上。

command not found 的意思不是「沒裝」，而是「我在 PATH 列出的那些資料夾裡找不到這個程式」。程式可能好好躺在某個地方，只是那個地方不在 PATH 裡。

確認方法：

which 工具名

如果印出一個路徑，代表找得到 —— 那你的問題在別處（往下看檢查二）。如果什麼都沒印、或說 not found，那就是 PATH 問題。

再確認一次它是否真的存在（把下面的路徑換成你係統上常見的安裝位置）：

ls ~/.local/bin/
ls /usr/local/bin/

如果你看到那個程式在裡面，但 which 找不到，問題確定是 PATH。

怎麼修：

安裝程式通常會告訴你「請把 XXX 加進 PATH」。那句話不是建議，是必要步驟，漏了就會出現這個症狀。做法是把那一行加進你的 shell 設定檔：

# 先確認你用的是哪個 shell
echo $0

印出 -zsh 就編輯 ~/.zshrc，印出 -bash 就編輯 ~/.bashrc 或 ~/.bash_profile。加進去的那一行長這樣（路徑換成你的實際位置）：

export PATH="$HOME/.local/bin:$PATH"

然後關鍵的一步：改完設定檔不會自動生效。要麼重開一個終端機視窗，要麼執行：

source ~/.zshrc

（用 bash 就換成 ~/.bashrc。）

九成「重裝也沒用」的案例到這裡就解決了。 因為重裝不會幫你改設定檔。

步驟二：權限不夠

症狀是 Permission denied，或者圖示點了完全沒反應、沒有錯誤訊息。

確認方法：看錯誤訊息裡有沒有 Permission denied。有的話就是這個。

怎麼修：分兩種情況，搞錯一種會讓事情更糟：

• 執行某個檔案時被擋 → 那個檔案缺執行權限。這是可以用 chmod +x 修的，但先確認你為什麼需要執行它 —— 正常安裝流程不該要求你手動 chmod 一個剛下載的檔案。
• 寫入某個系統目錄時被擋 → 你需要管理者權限。macOS/Linux 是在指令前加 sudo，Windows 是「以系統管理員身分執行」。

不要用 sudo 重跑整個安裝腳本，除非官方文件明確這麼說。 用管理者權限跑安裝腳本，等於讓那個腳本對你整台電腦做任何事。如果腳本有問題（或你複製到的不是官方版本），損害也是管理者層級的。

Windows 上另一種「點了沒反應」是 SmartScreen 擋住了未簽章的安裝程式。它通常會顯示一個藍色視窗說「已保護你的電腦」，裡面有一個不明顯的「仍要執行」。這不是故障，是設計。

步驟三：網路被擋

症狀：安裝到一半停住、timed out、Could not resolve host、certificate verify failed、或進度卡在 0%。

確認方法：

curl -I https://example.com

如果這個也失敗，問題在你的網路，不在那個工具。

常見原因，按發生頻率：

1. 你在公司或學校的網路裡，有 proxy 或防火牆。這非常常見，而且不是你能自己修的 —— 需要問 IT。很多安裝腳本不會自動使用係統的 proxy 設定。
2. 需要 VPN 或不需要 VPN。有些服務在某個地區需要 VPN 才連得到，有些則相反 —— 開著 VPN 反而連不上。兩個方向都試一次。
3. DNS 問題。Could not resolve host 通常代表 DNS 解析失敗，換一個 DNS（例如係統設定裡改成公共 DNS）常常就解決了。

注意：如果你在某個工具的文件裡看到 trust_env 或 proxy 相關的設定項，那通常就是為這個情況準備的。

步驟四：版本不符

症狀：安裝成功了，但一執行就報錯，錯誤訊息裡有 unsupported、requires、minimum version、或一堆你看不懂的 Python/Node 錯誤。

確認方法：把你有的版本與要求對比。

node --version
python3 --version

然後回去看官方文件的「需求」章節。很多工具的要求比你以為的高，而且係統內建的那個版本通常太舊。

一個特別常見的陷阱：你機器上有多個版本，終端機用的是不是你以為的那個。

which node
which python3

印出的路徑會告訴你實際用的是哪一個。如果路徑看起來很奇怪（例如指向某個你很久以前裝的東西），那就是版本衝突。

macOS 上 Python 還有一個特有的坑：係統內建的 Python 受保護，用它安裝套件會失敗並提到 externally-managed-environment。這不是故障，是要你用虛擬環境。

步驟五：磁碟空間

最少見，但最容易確認，所以放最後。

df -h

看你所在那一個掛載點的 Avail（可用空間）。如果只剩幾百 MB，很多安裝會失敗，而且錯誤訊息常常不會說是空間問題 —— 它可能在寫到一半時以各種奇怪的方式失敗。

模型類的工具特別吃空間：一個本機模型動輒幾個 GB，加上快取與暫存，實際需要的是檔案大小的兩到三倍。

五個都檢查過了還是失敗

到這裡才開始做下面兩件事，按這個順序：

1. 找到並讀完整的錯誤訊息。 不是終端機上滾過去的最後一行，是完整的輸出。很多工具會把詳細錯誤寫進 log 檔案。如果安裝輸出裡提到一個 log 路徑，去讀它。

2. 拿完整錯誤訊息去搜。 把最後三到五行原封不動複製進搜尋引擎。不要自己改寫成「XX 裝不上去怎麼辦」—— 別人遇到同樣問題時貼的是原始錯誤訊息，所以搜原始訊息才搜得到。

搜的時候注意日期。一個 2023 年的解答可能已經不適用於現在的版本。優先看最近一年的。

3. 這時才考慮重裝。 但要先確認你移除乾淨了：很多工具的設定檔與快取不會隨著解除安裝被刪掉，所以「重裝」實際上是「用舊設定檔配新程式」，症狀會一模一樣。檢查你的家目錄下有沒有以那個工具命名的隱藏資料夾（.something），有的話先備份再刪。

為什麼這個順序是這樣排的

按**「最可能且最容易確認」**排序，不是按技術複雜度：

五個檢查加起來不超過五分鐘。而重裝一次通常就要五到十分鐘，而且修不好其中四個。

初學者最常犯的錯是直接跳到重裝，因為「重裝」感覺像是在做什麼，而檢查感覺像是在拖延。實際上相反：檢查是在定位問題，重裝是在賭。

下一步

• 把指令從網頁貼進終端機 —— 如果指令本身貼進去就報錯，問題在那裡而不是安裝
• 終端機與 CLI 保命指南 —— 這篇用到的指令都在那裡有解釋
• 開始之前：先認識 20 個詞 —— PATH、shell、環境變數 這些詞的定義
• 具體工具的安裝：安裝 Cursor、安裝 Claude Code、安裝 WorkBuddy
• PATH 與路徑 / 環境變數與 .env / Shell（殼層） / CLI（命令列介面）