上週二，為了給寫作提供測試環境，我決定在 MacBook 上創建新用戶安裝 Homebrew。聽說這是 Mac 開發者的「必備工具」，安裝過程看起來很簡單——複製一行指令、貼到終端機、等幾分鐘就好。簡單吧？
三十分鐘後，我盯著 brew: command not found 錯誤訊息發呆。一小時後，我不小心用 sudo 把整個設定搞壞，正拼命在 Google「如何修復 Homebrew 權限」。到第二小時，我開始質疑人生，懷疑自己為什麼要走上這條不歸路。
最令人沮喪的是什麼？我遇到的每個問題都完全可以避免。這些都是成千上萬初學者每天會犯的錯誤，而且只要你知道該注意什麼，都有簡單的解決方法。
如果你剛裝完 Homebrew 但它不能用，或者你現在正深陷排錯地獄，這篇文章會幫你省下好幾個小時。我要分享我犯過的 5 個關鍵錯誤，讓你不必重蹈覆轍。
錯誤 #1：沒有把 Homebrew 加入 PATH
症狀：你成功安裝 Homebrew，但輸入 brew install git 卻出現 brew: command not found。
這是初學者最常遇到的問題，特別是如果你用的是 Apple Silicon Mac（M1、M2、M3 或 M4）。
為什麼會發生：
在 Intel Mac 上，Homebrew 會安裝到 /usr/local/bin，這個位置已經在系統的 PATH 裡。你的終端機知道要去那裡找指令，所以一切自動運作。
在 Apple Silicon Mac 上，Homebrew 會安裝到 /opt/homebrew/bin。這個位置預設不在 PATH 裡。當你輸入 brew 時，你的終端機根本不知道要去哪裡找。
安裝過程中，Homebrew 會顯示訊息告訴你要把它加入 PATH。但這訊息埋在一大堆安裝文字裡，大部分人（包括我）都會略過。
兩分鐘內的解決方法：
把這兩行複製到終端機，每行輸入後按 Enter：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
這會做什麼：第一行把 Homebrew 永久加入你的 shell 設定檔。第二行立即啟用它，不用重啟終端機。
驗證是否成功：
brew --version
如果看到 Homebrew 4.x.x，就成功了。如果沒有，完全關閉終端機（Command + Q）再重新打開。
專業建議：這只有 Apple Silicon Mac 需要。如果你用的是較舊的 Intel Mac 但 brew 還是不能用，問題在別的地方——跳到錯誤 #2。
錯誤 #2：對 Homebrew 使用 sudo（致命錯誤）
症狀：你看到「Permission denied」錯誤訊息，決定在指令前加上 sudo。看起來有用⋯⋯直到一切崩壞。
這是我最後悔的錯誤。花了我一個小時才修好。
初學者為什麼會這樣做：
在 Linux 上，當你看到權限錯誤，通常會加上 sudo 以管理員身分執行指令。對有點 Unix 經驗的人來說，這是肌肉記憶。
所以當 Homebrew 顯示權限錯誤，你的本能反應是：「啊，我需要管理員權限。來試試 sudo brew install git。」
為什麼這是災難性的：
Homebrew 是設計成不需要 sudo 就能運作。當你使用 sudo，你會建立由 root（超級使用者）擁有的檔案和目錄，而不是你的使用者帳號。
現在你的 Homebrew 安裝一部分屬於你，一部分屬於 root。未來的 Homebrew 指令會失敗，因為它們無法修改 root 擁有的檔案。錯誤就像雪球一樣越滾越大。
我花了 45 分鐘修復權限問題，都是因為一個 sudo brew 指令。
鐵律：
# ❌ 永遠不要這樣做：
sudo brew install gitsudo brew updatesudo 任何-brew-指令# ✅ 永遠這樣做：
brew install gitbrew update
如果你已經用了 sudo，這樣修復：
sudo chown -R $(whoami) /opt/homebrew/*
這會把所有 Homebrew 檔案的擁有權重設回你的使用者帳號。然後執行 brew doctor（詳見錯誤 #3）來驗證一切都修好了。
我希望有人早告訴我：Homebrew 能優雅地管理自己的權限。如果你看到權限錯誤，代表你的設定已經出問題了——不是說你需要 sudo。正確的第一步永遠是 brew doctor，不是 sudo。
錯誤 #3：忽略 brew doctor 警告
症狀：Homebrew 有時能用但會出現奇怪的錯誤。軟體安裝了但執行不正常。你不確定是真的壞了還是只是怪怪的。
為什麼會發生：
大部分初學者不知道 Homebrew 內建診斷工具。他們通常是 Google 錯誤訊息 30 分鐘後才發現 brew doctor。
就算執行了看到警告，如果東西看起來還能用，很容易就忽略它們。我就這樣做過。那些警告感覺像建議，不像必須遵守的規則。
它們不是建議。
預防性的解決方法：
brew doctor這單一指令能診斷 90% 的 Homebrew 問題。它會檢查你的安裝、找出問題，並確切告訴你如何修復。
你可能會看到什麼：
警告：「You have unlinked kegs in your Cellar」
- 意思：套件已安裝但在 PATH 中無法存取
- 修復：
brew link <套件名稱>
警告：「You have not agreed to the Xcode license」
- 意思：需要接受 Apple 的命令列工具授權
- 修復：
sudo xcodebuild -license然後輸入「agree」
警告：「Config scripts exist outside your system」
- 意思：你有來自其他套件管理器的衝突安裝
- 修復：遵循 Homebrew 提供的特定指示
何時執行 brew doctor：
- 安裝 Homebrew 後立即執行
- 安裝任何複雜套件後（如 Python 或 Node.js）
- 任何時候有東西運作不如預期
- 每月作為維護例行工作的一部分
如果 brew doctor 說「Your system is ready to brew」，就沒問題。如果沒有，請閱讀每個警告並依序修復。不要跳過任何一個。
我希望早知道：在我嘗試各種 Stack Overflow 解法之前先執行 brew doctor，就能直接指出 PATH 問題，省下我兩小時。
錯誤 #4：不了解 Formulae 和 Casks 的差異
症狀：Error: No available formula with the name "visual-studio-code"，即使你知道 VSCode 可以透過 Homebrew 安裝。
或者你安裝了某個東西但找不到它在哪裡或如何啟動。
為什麼會發生：
Homebrew 有兩種套件類型：
Formulae 是會被編譯和安裝的命令列工具。例如：git、python、wget、node。
Casks 是下載為預先建置的應用程式的 GUI 應用程式。例如：visual-studio-code、firefox、slack、zoom。
指令語法不同，初學者經常忘記 --cask 標記。
解決方法：
命令列工具（formulae）：
brew install git
brew install pythonbrew install wget
GUI 應用程式（casks）：
brew install --cask visual-studio-code
brew install --cask firefoxbrew install --cask slack
如何檢查你需要哪一種：
brew search visual-studio-code
輸出會顯示它在「Formulae」還是「Casks」下。如果顯示 Casks，你需要 --cask 標記。
經驗法則：如果你想要有圖形介面、通常放在「應用程式」資料夾裡的東西，幾乎都需要 --cask。命令列工具永遠不需要。
我希望早知道：我浪費了 15 分鐘試著不用 --cask 安裝 VSCode，一直以為套件名稱錯了。一個簡單的 brew search 就能告訴我需要什麼。
錯誤 #5：跳過 Caveats（注意事項）
症狀：軟體成功安裝，但當你試著使用它，什麼都沒發生。或者它能用但不如預期。
為什麼會發生：
安裝套件後，Homebrew 會顯示「Caveats」——重要的安裝後指示。這些通常包括：
- 把工具加入 PATH 的指令
- 如何啟動服務（如資料庫）
- 使用前需要的設定步驟
- 版本特定的警告
初學者看到一大堆文字，以為是選擇性的，就關掉終端機。或者他們不會往上捲回去讀 50 行前印出的內容。
如果忽略就會出問題的 caveat 範例：
==> Caveats
To start mysql now and restart at login: brew services start mysqlOr, if you don't want to run it as a service:
mysql.server start
如果你不執行其中一個指令，MySQL 已安裝但沒有執行。你會得到「connection refused」錯誤，以為安裝失敗了。
解決方法：
每次安裝後，往上捲並閱讀 caveats。真的逐字閱讀。如果它叫你執行指令，就執行它。
事後查看 caveats：
brew info <套件名稱>
這會顯示套件資訊，包括所有 caveats，即使你幾小時前就關掉終端機了。
我希望早知道：那些 caveats 不是建議或參考資訊。它們是必要步驟，才能讓軟體真正運作。把它們當作安裝說明，不是選讀內容。
額外錯誤：忘記更新
症狀：你知道存在的套件顯示「formula not found」錯誤。或者你安裝了有已知安全問題的過時版本。
為什麼會發生：
Homebrew 的套件定義存在 Git 儲存庫中。隨時間過去，你本機上的會變得過時。新套件看不到，版本資訊也過期了。
解決方法：
brew update安裝任何新東西之前執行這個。需要 5-30 秒，會更新 Homebrew 本身加上所有套件定義。
養成習慣：每週更新作為維護例行工作的一部分：
brew update && brew upgrade && brew cleanup
這會更新定義、升級所有已安裝的套件，並移除舊版本以釋放磁碟空間。
五分鐘排錯檢查清單
當 Homebrew 不能用時，依序執行這些指令：
# 1. Homebrew 在你的 PATH 裡嗎？
which brew
# 2. 有什麼問題？
brew doctor# 3. 套件定義是最新的嗎？
brew update# 4. 這個套件可用嗎？
brew search <套件名稱># 5. 檢查擁有權（Apple Silicon）
ls -la /opt/homebrew | head
90% 的時候，brew doctor 會找出確切的問題並告訴你如何修復。
關鍵重點
兩小時的排錯教會我，五分鐘的準備就能避免的事：
- 把 Homebrew 加入 PATH（Apple Silicon Mac 需要手動設定）
- 永遠不要對 Homebrew 指令使用 sudo（會永久破壞權限）
- 先執行
brew doctor，再 Google（診斷優於絕望） - **GUI 應用程式要用
--cask**（VSCode、Firefox、Slack 都需要這個標記） - 每次都要讀 caveats（它們是必要步驟，不是選項）
模式總是一樣的：跳過設定說明 → 忽略警告 → 花好幾小時排錯本來幾分鐘就能預防的問題。
下一步：
- 現在就執行
brew doctor（即使東西看起來能用） - 把這篇文章加入書籤，遇到問題時用
- 閱讀官方 Homebrew 文件以更深入理解
你犯過最大的 Homebrew 錯誤是什麼？我很想知道你是否遇過這些問題，或發現我遺漏的其他陷阱。在下方留言吧。
