企业官网建设流程全解析

刚拿到新Mac或者重装系统之后，第一件事往往是装Homebrew。这个包管理器之于macOS开发者，就像apt之于Ubuntu、Chocolatey之于Windows，没有它，装个nginx、python、git都得手动编译或者拖dmg，效率低得让人抓狂。我前前后后在三四台Mac上装过Homebrew，有Intel芯片的旧款，也有M1、M2的ARM机型，可以说把能踩的坑基本都踩了一遍。从最初的raw.githubusercontent.com连接失败，到后来curl报错、git克隆超时，再到权限问题、目录残留，每一步都让人想摔键盘。这篇就把我这几次完整折腾下来的经验做个总结，把安装流程、镜像方案、报错排查一次讲透。

1. 为什么Homebrew装起来这么麻烦

很多刚接触macOS的朋友不理解，装个包管理器而已，为什么别人一条命令搞定，自己执行就各种报错。这里面的水比想象中深，得从Homebrew的工作原理说起。

1.1 Homebrew到底是什么

Homebrew是一个基于Git和Ruby的开源包管理器，核心逻辑就是通过脚本把软件源码下载到本地，编译安装，再把可执行文件软链到系统目录。它跟App Store最大的区别是，里面几乎全是开源工具和命令行程序，覆盖了开发场景的方方面面。brew install wget、brew install nginx、brew install node，这些都是日常操作。

它安装软件时主要依赖两个东西：一是Git仓库，用来拉取软件包的描述信息（就是各类Formula）；二是二进制包或源码包，这些文件大多托管在GitHub上。问题就出在这里，国内网络环境访问GitHub经常不稳定，尤其是大文件下载，动不动就超时或断流。很多人安装报错，十有八九是卡在从GitHub拉取资源这一步。

1.2 Intel Mac和Apple Silicon的安装差异

另一个容易让人迷惑的点是芯片架构。Intel Mac和M系列芯片的Mac，Homebrew的安装路径完全不同。Intel版默认装在/usr/local，而Apple Silicon版装在/opt/homebrew。这个差异不仅仅是路径不同，还牵扯到环境变量配置、软件编译参数，甚至有些Formula对ARM架构支持得不够好，装的时候会多编译几步。

我在Intel Mac上第一次装Homebrew时根本不知道还有ARM版这回事，后来换了M1芯片的机器，用默认命令装完，发现brew命令找不到，检查一圈才发现是因为shell环境变量里还写着/usr/local/bin，而实际上Homebrew装在了/opt/homebrew/bin。所以动手之前，先搞清楚自己的芯片型号，能让后面省掉很多麻烦。

系统版本也有影响。Homebrew官方虽然支持macOS 12及以上版本，但有些旧系统的依赖库太老，Ruby版本也跟不上，导致brew安装后运行时报错。我有一台2015年的Intel MacBook Pro，停留在macOS Catalina，装Homebrew时能装上，但一执行brew update就各种Ruby语法报错，最后只能手动指定老版本的Homebrew才勉强跑起来。

2. 动手前的准备工作

很多人喜欢拿到命令就复制粘贴到终端里，说实话我也这样干过，结果就是反复踩坑。准备工作和安装本身一样重要，尤其是网络环境这个隐藏变量。

2.1 确认芯片架构和系统版本

先执行下面这些命令，搞清楚自己的机器是什么情况：

uname -m sw_vers

uname -m输出x86_64就是Intel芯片，输出arm64就是Apple Silicon。sw_vers能看系统版本。注意，Intel Mac上也可能跑到x86_64，但M系列上也有可能因为Rosetta转译而显示x86_64，为了避免误判，再看一下sysctl -n machdep.cpu.brand_string，里面写着Apple M1或M2就一目了然。

这一步很关键，因为它直接决定你后面要用哪个安装脚本、环境变量配到哪里。我在M1 Mac上曾经因为在终端里开了Rosetta模式，结果uname显示x86_64，差点用Intel的方式装了Homebrew。所以建议在原生终端（复制一份终端App，勾选“使用Rosetta打开”的就是转译终端）里操作。

2.2 安装Command Line Tools

Homebrew编译软件时依赖苹果的Command Line Tools，这个工具包里包含了git、clang、make等一整套开发工具。检查是否已安装：

xcode-select -p

如果输出/Library/Developer/CommandLineTools，说明已经有了。如果提示未安装，就执行：

xcode-select --install

系统会弹窗提示安装，这个过程可能持续好几分钟，依赖网络和苹果服务器的速度。很多人在这一步就直接卡住了，弹窗一直转圈没反应。碰上这种情况，可以去苹果开发者官网手动下载对应版本的Command Line Tools的dmg包，安装完再继续。

2.3 网络准备和镜像源选择

这一步是重中之重，也是绝大多数安装失败的根源。官方安装脚本需要从以下地址拉东西：

• raw.githubusercontent.com：拉取安装脚本本身
• github.com：克隆Homebrew核心仓库
• ghcr.io：拉取预编译的二进制包

这三个域名在国内的连通质量都不稳定，尤其是raw.githubusercontent.com，有时连IP都解析不出来。备好一个稳定的网络环境是最省心的方案，如果你不方便，那就老老实实走国内的镜像源。

目前比较成熟的中科大镜像和清华镜像都提供了Homebrew的完整镜像服务。以中科大为例子，安装时直接把官方脚本的中科大镜像版拉下来执行就行。这样安装脚本本身、核心仓库、二进制包全都走国内服务器，速度和稳定性会好很多。后面我会把具体的命令步骤写出来。

3. 完整安装过程实录

下面这一段是我反复验证过的安装流程，按步骤来，大多数机器上都能顺利跑通。用中科大镜像方案作为主路径，官方脚本方案作为备用，两个我都实测过。

3.1 用官方脚本安装（网络环境较好的情况）

如果你的网络环境访问GitHub基本无压力，直接执行官方命令是最省事的：

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

执行后会出现两个交互提示，第一个询问是否确认安装，第二个询问Homebrew的安装目录。如果不想交互，可以这样：

NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

NONINTERACTIVE=1会让脚本跳过所有交互，使用默认配置。默认配置下，Intel Mac装到/usr/local，Apple Silicon装到/opt/homebrew，非常省心。

3.2 用中科大镜像安装（国内网络的首选）

先把安装脚本下载到本地：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles" export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"

然后执行安装脚本：

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

注意，这里脚本本身还是从GitHub拉取，但脚本拉完之后，里面的brew仓库和core仓库都会走中科大镜像，极大降低失败概率。如果连脚本都拉不下来，可以先把脚本下载到本地再执行：

curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o install.sh

或者直接用下面这个已经改好镜像的安装脚本：

/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"

安装脚本执行后，它自己会往~/.zprofile里写环境变量。但中科大的脚本还会额外配置HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE这些变量，这样后续的brew update、brew install都会自动走镜像，不需要每次手动设置。

这里有一个细节值得说一下。Homebrew从2021年左右开始，核心仓库从homebrew-core迁移到了homebrew/core这种API模式下，HOMEBREW_CORE_GIT_REMOTE这个变量在较新的版本里会逐渐失效，取而代之的是HOMEBREW_API_DOMAIN。所以如果你装的Homebrew版本很新，可能看不到clone homebrew-core的过程了，改走API拉取软件包描述。这也是很多老教程失效的原因，因为它们还停留在clone homebrew-core的时代。中科大的HOMEBREW_API_DOMAIN配置就是为了适配这个新机制。

3.3 安装后的环境变量配置

装完之后，终端里直接敲brew -v大概率提示找不到命令，需要手动加环境变量。

Apple Silicon芯片：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"

Intel芯片：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile eval "$(/usr/local/bin/brew shellenv)"

这两句的作用是把brew的路径加进PATH环境变量。注意~/.zprofile只对zsh生效，如果你用的是bash，就改成~/.bash_profile。默认macOS从Catalina开始基本都是zsh了，但保险起见可以先echo $SHELL确认一下。

确认环境变量生效后，跑一下：

brew -v

能输出版本号，就说明安装成功了。

4. 实战踩坑记录与排查思路

这一节是我最想写的，因为每个坑都对应一个真实的报错场景，也都是新手最容易卡住的地方。

4.1 常见报错速查表

这张表里的前几条基本涵盖了90%的安装失败场景，核心思想就是：连不上的资源，要么翻过去，要么绕道走镜像。

4.2 Intel Mac安装不了Homebrew的深层原因

“Intel mac 安装不了homebrew了”这个话题的热度一直很高，很多老用户发现以前明明一条命令就能装，怎么现在就装不上。这里面的原因我认为有三层。

第一层是网络因素，这个前面说过，GitHub访问不稳定是最大的变量。第二层是Homebrew官方做了一些调整，比如对macOS版本的要求越来越严格，新版本brew源码在macOS Catalina这种老系统上直接跑不起来，因为用到了更新的Ruby特性和系统API。第三层是二进制包（bottles）对Intel Mac的覆盖率，很多软件新版本不再提供x86_64的预编译包了，brew只能尝试源码编译，编译过程更容易失败。

我有一台Intel的MacBook Air，之前重装系统后想装Homebrew，连续报了三次错，一次是raw.githubusercontent.com连接失败，一次是ghcr.io拉取bottles超时，还有一次是系统版本太旧导致的Ruby错误。最后是用中科大镜像+指定Homebrew版本才解决。所以如果你的老Intel Mac装不上，别灰心，多半不是机器的问题，是路径没走对。

4.3 安装中途卡住怎么办

安装脚本执行到一半卡住，最常见的是卡在Updating Homebrew...或Cloning into '/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core'这一步。这个过程实际上是在从GitHub拉取仓库，网络差时长达十几分钟都不奇怪，看起来就像死了一样。

一种处理方式是，耐心等待。第一次clone homebrew-core确实需要很长时间，一般5到15分钟不等，网络稳定的话会看到进度百分比在慢慢跳动。另一种方式，直接按Ctrl+C中断，然后把git remote换成镜像源再继续：

cd /usr/local/Homebrew git remote set-url origin https://mirrors.ustc.edu.cn/brew.git cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core git remote set-url origin https://mirrors.ustc.edu.cn/homebrew-core.git

换完镜像后再跑一次brew update，速度会明显改善。这一步的原理很简单，git remote就是仓库地址，换成国内镜像后，拉取数据不再走国际链路，自然就快了。

4.4 卸载残留导致的权限问题

如果你之前卸载过Homebrew，但没有清理干净，再次安装时很可能碰到权限困扰。典型的报错是：

Error: /usr/local/Homebrew is not writable.

这是因为之前安装时用的是sudo，某些目录的所有者是root，而不是当前用户。解决方案是把这部分目录的所有权拿回来：

sudo chown -R $(whoami) /usr/local/Homebrew

如果提示/usr/local/Homebrew不存在，说明卸载时主目录已经被删了，但/usr/local/bin或者/usr/local/etc里还有残留的符号链接。可以用ls -l /usr/local/bin/brew看一下，如果能看到指向已删除路径的链接，手动删掉就行：

rm -f /usr/local/bin/brew

还有一种情况，之前的Homebrew装在/opt/homebrew，现在换到了/usr/local，或者反过来，旧路径的符号链接会影响新安装。检查并清理这些残留链接很重要。我记得有一次用户说“Homebrew卸载残留”导致新装后brew命令一直指向旧路径，搞得整个系统里有两个brew，命令执行结果时对时错。所以安装前一定要确认旧目录清理干净，再用which -a brew看看有没有多个brew路径。

4.5 Command Line Tools安装失败的处理

我遇到过xcode-select --install弹窗后一直卡在“正在下载”的情况，等了半小时都没反应。这种时候可以试试清空下载缓存：

sudo rm -rf /Library/Developer/CommandLineTools sudo xcode-select --reset xcode-select --install

如果还是不行，就去苹果官方开发者网站手动下载Command Line Tools for Xcode的dmg，选择对应macOS版本下载安装。这个方法有效，因为很多问题是软件更新服务连接慢导致的。

5. 安装成功后的基本操作与优化

装好Homebrew不是终点，接下来要把它调教得顺手一些。新手最容易忽略的是换源和清理这两件事。

5.1 把默认源换成国内镜像

如果你是用官方脚本装的，建议立刻换成国内镜像，否则后续brew install大概率会碰到下载卡顿。在~/.zprofile或~/.bash_profile里追加以下内容：

export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles" export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"

清华大学也有对应的镜像，地址是mirrors.tuna.tsinghua.edu.cn。我个人习惯用中科大，因为它的更新频率和稳定性表现都不错。清华的源也响应快，两个选一个即可，别两个都混着用，容易出奇怪的版本错位。

改完环境变量后，执行source ~/.zprofile让配置生效，然后跑：

brew update

如果输出没有报错，说明镜像切换成功。

5.2 常用命令速查

brew install <软件名> # 安装软件 brew uninstall <软件名> # 卸载软件 brew search <关键词> # 搜索可安装的软件 brew info <软件名> # 查看软件详情 brew list # 列出已安装的软件 brew update # 更新Homebrew自身和仓库信息 brew upgrade # 升级所有已安装软件 brew cleanup # 清理旧版本和缓存 brew doctor # 检查Homebrew环境是否健康

brew doctor这个命令值得多说一句，它就像Homebrew的体检工具，能检测出环境变量配置错误、目录权限问题、残留文件等一大堆隐患。每次碰到疑难杂症，先跑一遍这个，往往能直接给出解决提示。

5.3 提升安装成功率的细节

安装软件时如果碰到Download failed或者SHA256 mismatch，多半是下载的压缩包不完整。这种时候建议先清缓存再重试：

brew cleanup rm -rf "$(brew --cache)"

清空缓存后重新执行安装命令，会重新下载完整的包。另外，brew install默认会先尝试下载bottle（预编译包），如果平台没有对应的bottle，才会走源码编译。编译过程可能耗时很长，碰到这种情况，可以用brew install --build-from-source强制编译，也可以直接用brew install -s。

还有一个经验是，装软件时尽量一次只装一个，别一条命令后跟一堆包名。有些软件依赖关系复杂，混装时输出信息又多又乱，出了问题不好定位。试过几次你就会发现，逐条安装看着慢，实际是少走弯路。

6. 几条关于安装与使用的个人体会

装Homebrew这事，说实话不是技术难度有多大，而是环境变量太多导致的不确定性太高。不同的芯片、不同的系统版本、不同的网络环境，组合出来的问题千奇百怪。我自己踩过一堆坑之后，总结出三条比较实用的心得。

第一条，安装前一定要先确认芯片架构和系统版本，再决定用什么方案。别拿到命令就一股脑执行，这看起来有点啰嗦，实际上能避免大半的无效操作。第二条，遇到网络报错先冷静判断瓶颈在哪，raw连不上就换镜像脚本，git clone慢就换git remote，bottle拉不下来就换HOMEBREW_BOTTLE_DOMAIN，对症下药比反复重试高效得多。第三条，实在不行就从头再来，先把旧环境彻底卸载干净再重装。Homebrew卸载是个技术活，建议参考官方提供的uninstall脚本，真正清干净了再装，能少浪费很多时间。

另外还有一个小技巧，如果你需要在新机器上快速搭好环境，可以把常用软件的安装命令写成一个shell脚本，比如brew install git、node、python、nginx这些，一次性执行完，省去一条条敲命令的麻烦。我刚换新Mac时就是这么干的，上午拿到机器，下午开发环境就齐活了。