Homebrew 文件

常見問題

這是一份常見問題、已知問題及其解決方案的清單。

• 執行 brew
  • brew 抱怨沒有「命令列工具」
  • Ruby: 錯誤的直譯器：/usr/bin/ruby^M：沒有這個檔案或目錄
  • Ruby: 錯誤的直譯器：/usr/bin/ruby
  • brew update 抱怨未追蹤的工作樹檔案
  • launchctl 拒絕載入 launchd plist 檔案
  • brew upgrade 發生錯誤
  • Python: easy-install.pth 無法連結
• 安裝失敗，並顯示「未知版本或路徑不在工作樹中」
• 升級 macOS
• 意外的雙重 Homebrew 安裝
• Homebrew Cask 問題
  • Cask - cURL 錯誤
  • Cask - 校驗碼不符
  • Cask - 拒絕存取權限
  • Cask - 來源不存在
  • Cask - 錯誤的引數數量
• 其他本機問題

執行 brew

brew 抱怨沒有「命令列工具」

您需要安裝（並更新）Xcode 命令列工具：在終端機中執行 xcode-select --install。

Ruby: 錯誤的直譯器：/usr/bin/ruby^M：沒有這個檔案或目錄

您使用 git 複製，而您的 Git 設定使用 Windows 行尾。請參閱此頁面，了解 如何設定 Git 處理行尾。

Ruby: 錯誤的直譯器：/usr/bin/ruby

您沒有 /usr/bin/ruby 或它不可執行。不建議讓此問題持續下去；您會驚訝於有多少 .app、工具和指令碼預期您的 macOS 提供的檔案和目錄在 macOS 安裝後保持未修改狀態。

brew update 抱怨未追蹤的工作樹檔案

在執行 brew update 之後，您收到 Git 錯誤警告，指出未追蹤的檔案或本機變更將被結帳或合併覆寫，後接 Homebrew 安裝內檔案的清單。

這是 update 程式碼中一個舊錯誤造成的，此錯誤早已修正。然而，錯誤的性質要求您執行下列動作

cd "$(brew --repository)"
git reset --hard FETCH_HEAD

如果 brew doctor 仍抱怨未提交的修改，請也執行此指令

cd "$(brew --repository)/Library"
git clean -fd

launchctl 拒絕載入 launchd plist 檔案

當嘗試使用 launchctl 載入 plist 檔案時，您收到類似下列其中一個的錯誤

Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...]
launch_msg(): Socket is not connected

或

Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied
launch_msg(): Socket is not connected

這些問題可能是由四個問題之一所造成

1. 您正在使用 iTerm。與 launchctl 互動時，解決方案是使用 Terminal.app。
2. 您正在使用終端多工器，例如 tmux 或 screen。您應該從一個獨立的 Terminal.app shell 與 launchctl 互動。
3. 您正在嘗試在遠端登入時執行 launchctl。您應該在遠端機器上啟用螢幕分享，並使用在該機器上執行的 Terminal.app 發出指令。
4. 您已使用 su 登入為不同的使用者。

brew upgrade 發生錯誤

在執行 brew upgrade 時，您會看到類似以下的內容

Error: undefined method `include?' for nil:NilClass
Please report this bug:
    https://homebrew.dev.org.tw/Troubleshooting
/usr/local/Library/Homebrew/formula.rb:393:in `canonical_name'
/usr/local/Library/Homebrew/formula.rb:425:in `factory'
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7:in `map'
/usr/local/Library/Contributions/examples/brew-upgrade.rb:7
/usr/local/bin/brew:46:in `require'
/usr/local/bin/brew:46:in `require?'
/usr/local/bin/brew:79

這會發生是因為升級指令的舊版本因某種原因而停留在系統中。修正方式

cd "$(brew --repository)/Library/Contributions/examples"
git clean -n # if this doesn't list anything that you want to keep, then
git clean -f # this will remove untracked files

Python: easy-install.pth 無法連結

Warning: Could not link <formula>. Unlinking...
Error: The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
You can try again using `brew link <formula>'

Possible conflicting files are:
/usr/local/lib/python2.7/site-packages/site.py
/usr/local/lib/python2.7/site-packages/easy-install.pth
==> Could not symlink file: /homebrew/Cellar/<formula>/<version>/lib/python2.7/site-packages/site.py
Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it.
To force the link and overwrite all other conflicting files, do:
  brew link --overwrite formula_name

To list all files that would be deleted:
  brew link --overwrite --dry-run formula_name

不要遵循此處的建議，而是按照 Python for Formula Authors 中所述，在公式中使用 Language::Python.setup_install_args 來修正。

安裝失敗，並顯示「未知版本或路徑不在工作樹中」

在安裝 Homebrew 時，如果初始下載失敗，並出現類似以下的內容

error: Not a valid ref: refs/remotes/origin/master
fatal: ambiguous argument 'refs/remotes/origin/master': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

或

fatal: the remote end hung up unexpectedly
fatal: early EOF
fatal: index-pack failed

這是您的機器與 GitHub 之間的連線問題，而不是 Homebrew 本身的錯誤。請參閱此 討論主題，了解其他人找到的許多解決方案，例如使用有線連線或 VPN，或停用網路監控工具。

升級 macOS

升級 macOS 可能會導致以下類型的錯誤

• dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib
• configure: error: Cannot find libz

在 macOS 升級後，可能需要重新安裝 Xcode Command Line Tools，然後對所有已安裝的公式執行 brew upgrade

xcode-select --install
brew upgrade

意外的雙重 Homebrew 安裝

在使用 Apple 的 Migration Assistant (MA) 等工具時，可能會意外地安裝兩個 Homebrew。這最常導致 MA 將 /usr/local 和 /Applications 從基於 Intel 的 Mac 複製到 Apple Silicon 基於 Mac 上的相同路徑。這是有問題的，因為 /Applications 可能包含僅限 x86_64 的應用程式。使用 x86_64 終端模擬器將導致 shell 使用 /usr/local 安裝的 Homebrew，而不是 /opt/homebrew 中的新安裝，這是 macOS 上 arm64 Homebrew 安裝的正確路徑。

繼續使用此設定最終可能會造成問題，因此最好移轉您的 Homebrew 安裝。請遵循下列步驟執行此操作。

1. 執行 arch -x86_64 /usr/local/bin/brew bundle dump --global 將您目前已安裝的配方清單傾印至 ~/.Brewfile。
2. 檢閱 ~/.Brewfile 的內容以移除您不再想要安裝的項目。

3. 透過確認 arch 的輸出為 arm64，驗證您的終端機模擬器是否在 arm64 模式中執行。

   如果不是，請使用其他終端機模擬器，例如 Apple 的 Terminal.app，它將在 arm64 模式中執行。

4. 在正確的前置詞 (/opt/homebrew) 下安裝 Homebrew，當終端機在 arm64 模式中執行時，這會在預設情況下發生。

   遵循安裝程序結束時列出的後續步驟說明；如果沒有相應調整您的 shell 設定，可能會損壞您的 Homebrew 安裝。

5. 執行 /opt/homebrew/bin/brew bundle install --global 以使用您在 /opt/homebrew 中的新 Homebrew 安裝，複製您最初的配方安裝。

預計會花一些時間搜尋 Homebrew 的配方和 cask 清單，以尋找已棄用、已停用或已移除配方的替換品。

一旦您對新的 /opt/homebrew Homebrew 安裝狀態感到滿意，您就可以解除安裝舊的 /usr/local 安裝。下載並執行解除安裝程式腳本

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)" -- --path=/usr/local

如需更多資訊，請參閱此討論。

Homebrew Cask 問題

Cask - cURL 錯誤

首先，讓我們解決一個常見的問題：您有 .curlrc 檔案嗎？使用 ls -A ~ | grep .curlrc 檢查（如果您取得結果，表示檔案存在）。這些檔案通常會造成此類問題。在執行任何其他操作之前，請移除該檔案並重試。如果現在可以正常運作，請勿開啟問題。不兼容的 .curlrc 設定必須由您自行修正。

但是，如果您沒有 .curlrc 或移除它沒有用，讓我們看看問題是否出在上游

1. 前往供應商網站（brew home <cask_name>）。
2. 找到應用程式的下載連結並按一下。

如果下載正常

Cask 已過時。我們來修復它

1. 瀏覽應用程式網站並找出最新版本。它可能顯示在用於下載的 URL 中。
2. 查看 Cask 的版本（brew info <cask_name>）並驗證它確實已過時。如果應用程式的版本是 :latest，表示 url 本身已過時。需要將它變更為新的 URL。

透過 提交修正 來協助我們。如果您遇到困難，開啟問題說明您到目前為止的步驟以及您遇到問題的地方。

如果下載不正常

問題與 Homebrew Cask 無關，而是與供應商或您的連線有關。

首先診斷您的連線（嘗試下載其他 Cask 或瀏覽網路）。如果問題出在您的連線，請嘗試使用 Ask Different 等網站尋求建議。

如果您確定問題不出在您的連線，請聯絡應用程式的供應商並告知他們連結已中斷，以便他們修復。

請勿開啟問題。

Cask - 校驗碼不符

首先，檢查問題是否出在您的下載。刪除已下載的檔案（錯誤訊息中會指出其位置）並重試。

如果問題仍然存在，表示 Cask 已過時。它可能需要新版本，但也有可能版本保持不變（當供應商就地更新應用程式時，偶爾會發生這種情況）。

1. 前往供應商網站（brew home <cask_name>）。
2. 找出最新版本。它可能顯示在用於下載的 URL 中。
3. 查看 Cask 的版本（brew info <cask_name>）並驗證它確實已過時。如果是，則需要更新它。

透過 提交修正 來協助我們。如果您遇到困難，開啟問題說明您到目前為止的步驟以及您遇到問題的地方。

Cask - 拒絕存取權限

在這種情況下，您的使用者帳戶可能沒有管理員權限，因此沒有寫入 /Applications 的權限，而這是預設的安裝位置。您可以使用 --appdir 來選擇安裝應用程式的路徑。

如果 --appdir 無法解決問題，或者您確實有寫入 /Applications 的權限，請透過執行 ls -dl "$(brew --prefix)/Caskroom" 並檢查第三個欄位，驗證您是否為 Caskroom 目錄的所有者。如果您不是所有者，請使用 sudo chown -R "$(whoami)" "$(brew --prefix)/Caskroom" 修復。如果您是所有者，問題可能出在應用程式套件本身。

某些應用程式套件沒有某些權限，而這些權限對於我們將它們移至適當位置是必要的。您可以使用 ls -ls '/path/to/application.app' 檢查這些權限。如果您在輸出的開頭看到類似 dr-xr-xr-x 的內容，那可能是原因。要修復它，我們需要變更應用程式套件的權限以允許我們移動它，然後再將它設定回原來的權限（如果開發人員故意設定這些權限）。請參閱 litecoin.rb 以取得此類 cask 的範例。

透過 提交修正 來協助我們。如果您遇到困難，開啟問題說明您到目前為止的步驟以及您遇到問題的地方。

Cask - 來源不存在

首先，您需要找出哪個成品不再被正確處理。錯誤訊息中會明確指出：如果它說 It seems the App source…'，則問題出在 app 節。此模式在 所有成品 中都是相同的。

修復此錯誤通常很簡單，而且只需要您花一點時間。首先下載 cask 的套件： brew fetch <cask_name>。輸出的最後一行會通知您下載的位置。導航到那裡並手動解壓縮它。舉例來說，假設檔案中的結構如下

.
├─ Files/SomeApp.app
├─ Files/script.sh
└─ README.md

現在，如果我們在使用 brew cat <cask_name> 查看 cask 時發現以下內容

(…)
app "SomeApp.app"
(…)

此 cask 預期 SomeApp.app 會在封存檔的最上層目錄（請看它只寫 SomeApp.app），但開發人員後來已將它移至 Files 目錄內。我們只要更新 cask 的那一行，以遵循新的結構即可：app "Files/SomeApp.app"。

請注意，偶爾 app 的名稱會完全變更（例如從 SomeApp.app 變更為 OtherApp.app）。在這些情況下，cask 本身的檔名及其 token 也必須變更。請參閱 token 參考，以取得新名稱的完整說明。

透過 提交修正 來協助我們。如果您遇到困難，開啟問題說明您到目前為止的步驟以及您遇到問題的地方。

Cask - 錯誤的引數數量

請確定問題確實出在您的 macOS 版本。為此，請嘗試手動安裝軟體。如果它與您的 macOS 版本不相容，它會告訴您。在這種情況下，我們無法協助您安裝軟體，但我們可以新增一個 depends_on macos: 節，以防止 cask 安裝在不相容的 macOS 版本上。

透過 提交修正 來協助我們。如果您遇到困難，開啟問題說明您到目前為止的步驟以及您遇到問題的地方。

其他本機問題

如果您的 Homebrew 安裝搞砸了（而且修復 brew doctor 找到的問題無法解決問題），重新安裝 Homebrew 可能有助於重設為正常狀態。若要輕鬆重新安裝 Homebrew，請使用 Homebrew Bundle 自動還原您已安裝的公式和 cask。為此，請執行 brew bundle dump、解除安裝、重新安裝，然後執行 brew bundle install。