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://docs.brew.sh.cn/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 命令行工具，然后 brew upgrade 所有已安装的公式

xcode-select --install
brew upgrade

无意中双重安装 Homebrew

在使用 Apple 的迁移助理 (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 的配方和木桶列表 以替换已弃用、已禁用或已删除的配方。

一旦您对新的 /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 本身已过时。它需要更改为新的。

通过 提交修复 来帮助我们。如果你遇到困难，打开一个问题，说明你迄今为止的步骤以及你遇到问题的所在。

如果下载不起作用

该问题与 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 - 来源不存在

首先，您需要确定哪个工件不再被正确处理。错误消息中明确指出：如果它显示 It seems the App source…'，则问题出在 app 节上。此模式在 所有工件 中都是相同的。

修复此错误通常很容易，只需要您花费一点时间。首先下载 cask 的软件包：brew fetch <cask_name>。输出的最后一行将告知您下载的位置。导航到那里并手动解压它。例如，假设存档内的结构如下

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

现在，如果我们在查看 cask 时发现这一点，使用 brew cat <cask_name>

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

cask 预期 SomeApp.app 在存档的顶级目录中（请注意，它简单地表示 SomeApp.app），但开发人员已将其移至 Files 目录中。我们所要做的就是更新 cask 的那一行以遵循新结构：app "Files/SomeApp.app"。

请注意，有时应用程序的名称会完全更改（例如，从 SomeApp.app 更改为 OtherApp.app）。在这些情况下，cask 本身的文件名及其令牌也必须更改。查阅 令牌参考 以获得有关新名称的完整说明。

通过 提交修复 来帮助我们。如果你遇到困难，打开一个问题，说明你迄今为止的步骤以及你遇到问题的所在。

Cask - 参数数量错误

确保问题确实出在您的 macOS 版本上。要做到这一点，请尝试手动安装软件。如果它与您的 macOS 版本不兼容，它会告诉您。在这种情况下，我们无法帮助您安装软件，但我们可以添加一个 depends_on macos: 节以防止在不兼容的 macOS 版本上安装 cask。

通过 提交修复 来帮助我们。如果你遇到困难，打开一个问题，说明你迄今为止的步骤以及你遇到问题的所在。

其他本地问题

如果您的 Homebrew 安装搞乱了（并且修复 brew doctor 发现的问题无法解决问题），重新安装 Homebrew 可能有助于重置为正常状态。要轻松重新安装 Homebrew，请使用 Homebrew Bundle 自动恢复您已安装的公式和 cask。要做到这一点，运行 brew bundle dump、卸载、重新安装 并运行 brew bundle install。