如果你用的是 Apple Silicon 芯片的 MacM1、M2、M3包括刚出的 M4又希望把 Homebrew 装到自己指定的~/Develop/Tools/Homebrew目录那“环境变量怎么配”就是绕不开的第一道坎。我自己在 M 系列机器上把默认路径和自定义路径两套方案都完整跑过也陪同事处理过各种安装报错。这篇文章把 Apple Silicon 下 Homebrew 的路径逻辑、自定义安装、环境变量配置、常见报错修复一次讲完。不管你正打算从零安装还是已经装完但终端里一输brew就报 command not found都可以直接翻到对应章节照抄。1. Apple Silicon 上 Homebrew 路径的来龙去脉1.1 Intel 时代 /usr/local 的约定在 Intel 芯片的时代Homebrew 的安装位置几乎永远是/usr/local。这个路径并不是随便选的从 Unix 时代开始/usr/local就约定俗成地用来放本机管理员自行编译和安装的软件系统自带的工具在/usr/bin、/bin而额外装的软件统一进/usr/local/bin。Homebrew 只是沿用了这个老规矩把 brew 本体、formula软件包以及软链接全部挂在/usr/local下面。这个设计在 Intel Mac 上挺好用但也有个隐患/usr/local默认对普通用户不可写所以安装时必须用sudo而一旦权限搞乱后面各种Permission denied和文件归属问题就都来了。我在给同事排查问题的时候见过不少把/usr/local的 owner 改成 root 然后所有 brew 操作都要加 sudo 的案例实际体验非常糟糕。1.2 Apple Silicon 为什么默认 /opt/homebrewApple 转向 Apple Silicon 之后Homebrew 官方把默认安装目录改成了/opt/homebrew。原因主要有两个。第一Apple Silicon 是 ARM 架构和 Intel 的 x86_64 指令集不兼容。如果把 ARM 版 brew 和 Intel 版 brew 混在同一个/usr/local里bin 目录下的软链接互相覆盖整个环境会变得无法收拾。默认路径拆到/opt/homebrew相当于把 ARM 和 Intel 两条软件链彻底隔离开。第二新系统对系统卷做了只读保护系统自己占用的目录不允许第三方随便写。/opt是一个相对中立的应用目录给 Homebrew 用正合适。所以你在 Apple Silicon 机器上跑brew --prefix得到/opt/homebrew就是官方默认值如果你看到/usr/local那说明当前环境的 shell 很可能是通过 Rosetta 转译运行的或者你手动改了配置这点在后面的报错章节还会再提到。1.3 为什么有人要把 Homebrew 放到 ~/Develop/Tools/Homebrew既然官方默认路径是/opt/homebrew为什么还有人比如我非要放到~/Develop/Tools/Homebrew这种自定义目录最直接的理由是不用sudo。用户目录下面的文件归你本人所有装软件、更新、清理全都不需要临时提权也从根上避免了权限错乱。第二个理由是迁移方便整个 Homebrew 就是一个大目录Time Machine 备份或者手动拷贝都能整体带走macOS 重装之后恢复环境特别省事。第三有些公司电脑对系统盘外的目录有管控或者同事之间需要共用同一套工具链放在/opt这种系统级目录里反而碍事。当然自定义路径不是没有代价。Homebrew 官方虽然允许“把 brew 仓库 clone 到任意位置使用”但少数老 formula 在编译时会把前缀写死成/usr/local或/opt/homebrew出现概率不高真遇到了单独处理就行。我实际体验下来日常brew install、brew services这些操作在自定义路径下都能正常跑。2. 自定义路径安装从 0 到 1 的完整命令2.1 安装前的环境检查动手之前先把三件事确认好能少踩一半的坑。第一确认当前的 shell 是 zsh 还是 bashecho $SHELLCatalina 之后 macOS 默认 shell 已经换成 zsh正常情况下输出/bin/zsh。如果你的结果还是/bin/bash说明你之前手动切过后面配置环境变量的文件就不一样了。第二确认命令开发者工具Command Line Tools装没装xcode-select -p如果输出/Library/Developer/CommandLineTools说明已经装好。如果提示error: unable to find utility xcode-select先运行xcode-select --installHomebrew 编译软件依赖这组工具不装后面必报xcrun: error: invalid active developer path之类的错误。第三确认当前是 ARM 原生终端uname -m输出arm64是正常的。如果输出x86_64说明终端跑在 Rosetta 转译模式下建议先关闭终端的 Rosetta 设置再继续不然装完的 brew 也是 Intel 版绕了一大圈。2.2 克隆 brew 到目标目录官方一键安装脚本默认只会装到/opt/homebrew不支持自定义目录所以自定义路径要走 clone 方案。直接执行mkdir -p ~/Develop/Tools git clone --depth1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git ~/Develop/Tools/Homebrew这里我直接用了清华镜像源而不是 GitHub 官方地址。原因很实际brew 仓库本身包含不少历史记录直接从 GitHub clone 在国内网络下经常超时甚至卡在git clone的进度条上不动。镜像源和官方源是同步的后续brew update也可以继续指向它。--depth1的意思是只拉最新一次提交速度最快。代价是git log里没有完整历史一般使用完全够后面想补全历史再执行git fetch --unshallow就可以。2.3 初始化 git 仓库和 tap 目录brew 本体 clone 完成之后还需要准备 homebrew-core 这个核心 formula 仓库。Homebrew 4.x 之后formula 元数据默认通过 API 获取不一定要求本地有 homebrew-core但为了brew update和离线场景更稳我还是建议把核心 tap 一起克隆下来mkdir -p ~/Develop/Tools/Homebrew/Library/Taps/homebrew git clone --depth1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git ~/Develop/Tools/Homebrew/Library/Taps/homebrew/homebrew-core如果你经常安装图形化软件比如 Chrome 这类 cask 包再把 homebrew-cask 也放进来git clone --depth1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-cask.git ~/Develop/Tools/Homebrew/Library/Taps/homebrew/homebrew-casktap 的目录结构必须严格控制在Library/Taps/homebrew/下名字也别改Homebrew 是按固定路径去识别仓库的。有一次我把目录名homebrew-core写成了core结果brew install一直报找不到 formula后来才发现是路径问题。2.4 验证基础命令环境变量还没配所以先直接用全路径验证 brew 能不能跑~/Develop/Tools/Homebrew/bin/brew --version ~/Develop/Tools/Homebrew/bin/brew config如果版本号正常打印出来说明安装基本成功。第一次执行 brew 时它会自动创建Caskroom、Cellar、Frameworks这些子目录顺便跑一些初始化耐心等它几秒钟就行。这一步出问题的话多半是上一个步骤 clone 不完整回头检查网络重来一遍。3. 环境变量配置让 brew 在任何终端都能被找到3.1 先搞清 shell 的加载顺序.zprofile vs .zshrc环境变量配不生效九成问题出在“不知道该把配置写进哪个文件”。zsh 的启动文件主要有四个加载顺序是.zshenv→.zprofile→.zshrc→.zlogin。~/.zprofile在登录 shell 启动时加载适合放环境变量级别的配置~/.zshrc在交互式 shell 启动时加载适合放别名、提示符这类会话配置。macOS 自带的终端Terminal.app默认把新窗口当成登录 shell 启动所以~/.zprofile里的配置会生效。但 VS Code 的集成终端、IDE 里弹出的终端有些不会走登录流程结果就是你在.zprofile里配好了打开 IDE 还是找不到brew。我自己的习惯是核心环境变量放在~/.zprofile同时在~/.zshrc里加一行source ~/.zprofile。这样无论终端从哪个入口启动环境变量都不会丢。代价是登录时会多读一次文件这点开销可以忽略。3.2 推荐的环境变量清单直接给一份我实测可用的~/.zprofile完整配置按自己的镜像喜好调整即可# Homebrew 自定义安装前缀 export HOMEBREW_PREFIX$HOME/Develop/Tools/Homebrew # 镜像源设置清华大学 TUNA export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_API_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles # 行为开关 export HOMEBREW_NO_ANALYTICS1 export HOMEBREW_NO_AUTO_UPDATE1 export HOMEBREW_NO_INSTALL_CLEANUP1 # 重要加载 brew shellenv eval $($HOME/Develop/Tools/Homebrew/bin/brew shellenv)逐条解释几个关键变量的作用。HOMEBREW_BREW_GIT_REMOTE和HOMEBREW_CORE_GIT_REMOTE控制 brew 本体和核心仓库的 git 远程地址。不设置的话brew update默认去访问 GitHub速度慢是老问题。HOMEBREW_API_DOMAIN是 Homebrew 4.x 新增的配置用来指定 formula 元数据 API 的镜像地址。HOMEBREW_BOTTLE_DOMAIN对应预编译二进制安装包bottle的下载地址。这两个不配安装大软件时会看到 brew 在下载环节长时间没动静。HOMEBREW_NO_AUTO_UPDATE1表示关掉每次安装前的自动更新。这个开关能显著提升安装响应速度但我的建议是别永久关闭最多开一段时间然后手动brew update保持仓库和 formula 列表是新的。如果你长期不管更新后面装软件时容易碰到“formula 版本和依赖对不上”的怪问题。HOMEBREW_NO_ANALYTICS1是关闭匿名统计上报属于隐私相关的开关顺手就开了。3.3 使用 brew shellenv 而不是手写 PATH你可能注意到上面的配置里没有直接写export PATH.../bin:$PATH而是用了eval $($HOME/Develop/Tools/Homebrew/bin/brew shellenv)。brew shellenv是 Homebrew 官方提供的环境变量导出命令执行后会输出一段形如HOMEBREW_PREFIX$HOME/Develop/Tools/Homebrew HOMEBREW_CELLAR$HOME/Develop/Tools/Homebrew/Cellar HOMEBREW_REPOSITORY$HOME/Develop/Tools/Homebrew PATH$HOME/Develop/Tools/Homebrew/bin:$HOME/Develop/Tools/Homebrew/sbin:$PATH也就是说它一次性就把HOMEBREW_PREFIX、HOMEBREW_CELLAR、HOMEBREW_REPOSITORY、PATH、MANPATH、INFOPATH全都设置好了。我推荐这种方式而不是手写export PATH原因有两点一是eval会自动判断 brew 的实际安装位置以后目录移动了只需重新跑一遍二是不会像反复追加export PATH那样产生一堆重复路径。3.4 配置生效与常规检查写完配置文件后先source让当前终端立即生效验证一下source ~/.zprofile which brew brew --prefix echo $PATHwhich brew输出应该是~/Develop/Tools/Homebrew/bin/brew。brew --prefix输出对应自定义前缀。到这里环境变量就算配好了新开的终端窗口也会自动生效。这部分的思路其实和配JAVA_HOME、配 Python 环境变量是一模一样的先找到软件的安装根目录再把bin目录挂进PATH。你如果之前配过 Java 或 Python 的环境变量照葫芦画瓢就能理解 Homebrew 的配置逻辑。4. 常见报错修复实录4.1 brew: command not found报错特征zsh: command not found: brew排查思路这是环境变量没生效时最典型的报错。先把顺序理清楚先执行brew --version的全路径版本如果全路径能用说明 brew 本身装好了问题出在 PATH 没指过去如果全路径也报 command not found说明安装目录有问题得回到第 2 章重新 clone。PATH 没指过去时按三条线索检查确认~/.zprofile里那行eval $($HOME/Develop/Tools/Homebrew/bin/brew shellenv)确实存在且没被注释掉。确认当前终端已经执行过source ~/.zprofile新配置不会主动追加上已经开着的终端。确认没有同时开了 bash 模式或者别的 shell导致读的是~/.bash_profile。我见过一个很隐蔽的情况同事在.zprofile里写了配置但文件前面有一行return导致后面的配置根本没执行到。所以检查配置文件时别只看有没有那行还要看看它是不是被提前跳过了。4.2 安装或运行时报 Rosetta 2 相关错误报错特征Error: Cannot install under Rosetta 2 in ARM default prefix (/opt/homebrew)!原因分析这个报错的意思是当前 shell 是 x86_64 模式被 Rosetta 2 转译但 brew 检测到它运行在 ARM 默认前缀/opt/homebrew下二者不匹配于是直接拒绝执行。常见触发场景是在老项目的指引下开了“使用 Rosetta 打开终端”或者从 x86_64 版 iTerm/终端里启动了 brew。修复方法先确认当前架构uname -m如果输出x86_64说明确实跑在转译模式。切回 ARM 原生终端即可或者用命令强制拉一个新的原生 shellarch -arm64 /bin/zsh在原生 shell 下再跑uname -m确认输出arm64然后重新执行brew命令。这里提醒一句不要试图给 brew 设置什么“兼容模式”ARM 的 Homebrew 就该用 ARM 终端跑转译模式下装出来的二进制混在同一个 Cellar 里后面排查问题会非常痛苦。4.3 安装和下载时卡住、curl 连接失败报错特征curl: (7) Failed to connect to raw.githubusercontent.com port 443 after 1000 ms: Couldnt connect to server或者curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443原因分析这属于网络层面的失败。raw.githubusercontent.com是 Homebrew 官方安装脚本拉取文件用的域名直连超时非常常见。如果你直接用官方一键脚本安装很容易卡在这一步这不是你操作有误而是下载源本身不稳定。修复方法首选方案是全程走镜像第 2 章的git clone命令直接使用清华镜像源安装时下载 bottle 就用HOMEBREW_BOTTLE_DOMAIN指向镜像。如果你已经按官方地址 clone 了一半就把远程仓库地址改成镜像再继续cd ~/Develop/Tools/Homebrew git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git git remote set-url origin --add https://github.com/Homebrew/brew.git值得提醒的是不要因为一次超时就反复重试官方源换个镜像源通常比死磕官方地址省时间得多。中科大的镜像mirrors.ustc.edu.cn也是备选项清华源如果偶尔抽风可以整组切换过去。4.4 权限类报错Permission denied报错特征Permission denied dir_s_mkdir - /opt/homebrew或者Error: The following directories are not writable by your user: /opt/homebrew原因分析这是用官方脚本安装默认路径时最常见的问题。/opt/homebrew这个目录如果是由之前的sudo创建的或者系统里已经残留了旧的所有者记录当前用户就没有写入权限。修复方法如果你决定用默认路径把目录所属权交给当前用户sudo mkdir -p /opt/homebrew sudo chown -R $(whoami):admin /opt/homebrew之后运行brew就不需要加sudo。如果你要走自定义目录方案那根本不会有这个问题因为~/Develop/Tools/Homebrew本来就在你的用户目录下。这里有个原则必须强调Homebrew 官方明确不支持sudo brew这种用法任何时候都不要用管理员权限跑 brew 命令否则会出现文件归属混乱后续卸载都难。4.5 brew update 失败报错特征Error: Could not update Homebrew itself fatal: unable to access https://github.com/Homebrew/brew/: Failed to connect to github.com port 443原因分析brew 本体是一个 git 仓库brew update本质上就是对这个仓库做git fetch。GitHub 连不上自然更新失败。另外还有一种情况之前 clone 时用了--depth1仓库处于浅克隆状态某些旧版本的 brew 更新逻辑会报错。修复方法先检查并修改 brew 仓库远程地址cd $(brew --repo) git remote -v git remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git brew update如果.git目录本身已经损坏干脆重建rm -rf $(brew --repo)/.git cd $(brew --repo) git init git remote add origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git git fetch --depth 1 origin git reset --hard origin/master做完之后再跑brew update验证。注意最后一步的git reset --hard会把本地对 brew 仓库的改动全部覆盖如果你曾经手动改过 brew 源码先备份。4.6 旧版 macOS 系统兼容性报错报错特征Error: Your macOS version is older than 10.15或者安装某个 formula 时提示系统版本过旧。原因分析Homebrew 官方会定期结束对旧版 macOS 的支持。先是 High Sierra、Mojave 被淘汰然后 Catalina10.15也进入了不支持列表。新版 brew 在运行时检测到系统版本过低就会直接拒绝工作。修复方法最省心的方式当然是升级 macOS。如果机器暂时不能升级就只能安装旧版本的 Homebrew比如根据官网 release 记录切到还支持你当前系统的最后一个版本 tagcd $(brew --repo) git fetch --tags git checkout 某个支持你系统的历史tag这个方法能应急但我不推荐长期停留。旧版 brew 拿不到新的 formula 更新安全补丁和依赖解析都会跟不上属于“能用但别指望它稳定”的状态。4.7 卸载残留与重装报错特征It seems Homebrew is already installed或者重装官方脚本时提示目录已存在安装进程退出。原因分析之前有一次失败的安装或者在默认路径/opt/homebrew下装了一半留下了残缺目录。新的安装脚本检测到目录存在就直接跳过导致你既没装成功也找不到完整的 brew 命令。修复方法先用全路径确认 brew 是否可用如果不可用就按“残留”处理。Homebrew 提供了官方卸载脚本/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)卸载完成后再手动清理缓存目录rm -rf ~/Library/Caches/Homebrew rm -rf ~/Library/Logs/Homebrew rm -rf ~/.cache/Homebrew最后删掉默认残留目录rm -rf /opt/homebrew然后再重新安装。卸载脚本会问你“是否确认删除每一个文件”如果心里没底先只删缓存和脚本列出的主目录别把~/Develop/Tools里的其他开发工具误删了。下面是一个压缩版的报错速查表方便你以后快速定位报错特征主要原因快速解法command not found: brew环境变量未生效检查 .zprofile 并 sourceRosetta 2 prefix 报错终端运行在 x86_64 模式恢复 arm64 终端curl 连 raw.githubusercontent.com 失败网络无法直连官方源改用清华/中科大镜像Permission denied 目录不可写目录所有权不对chown 给当前用户brew update 失败git remote 指向 GitHub换成镜像 remotemacOS version older 报错系统版本被官方放弃升级系统或锁旧版本It seems Homebrew is already installed残留的残缺安装卸载脚本清理后重装5. 配好之后安装 redis 等工具的正确姿势5.1 安装 redis 示例环境变量配好之后安装软件就真正变成一行命令的事了。这里用 redis 举例因为这是很多后端开发者装 Homebrew 的第一个需求brew install redis安装成功的标志是输出里出现/usr/local/Cellar/redis/7.x.x或~/Develop/Tools/Homebrew/Cellar/redis/7.x.x这种路径具体前缀取决于你的安装方案。验证一下redis-server --version redis-cli pingredis-cli ping在没有启动服务时连接本地会失败并提示连接被拒绝这是正常现象先启动服务再看结果。5.2 brew services 管理后台服务redis 这类服务型软件最省心的管理方式是 Homebrew 自带的 services 命令brew services start redis brew services list brew services info redisbrew services start redis会把 redis 注册成后台服务并立即启动重启电脑后也会自动拉起。如果你只是临时试用不想让它常驻可以用brew services run redis它只运行一次不注册开机自启。这里要分清两个概念brew install装的是 formula命令行工具、库、服务而图形界面应用属于 cask要用brew install --cask来装。一开始见到brew install google-chrome报错很可能就是忘了加--cask。5.3 日常维护命令配好环境之后维护性的命令也要顺手记下来。我每两周固定跑一次brew doctorbrew doctor会检查目录权限、git 远程地址、过时的依赖等有异常会给出提示。发现问题后执行brew update brew upgrade brew cleanupbrew update更新 brew 本体和 formula 列表brew upgrade升级已安装的软件brew cleanup清理旧版本和缓存。这几个命令按顺序跑一遍环境一般就能保持健康。不要跳过brew doctor很多诡异问题它都能提前指出来。6. 实操心得与避坑总结6.1 环境变量到底放哪个文件最稳我踩过几次坑之后的结论是不要只放一个文件。.zprofile管登录 shell.zshrc管交互式 shell两者覆盖的场景不同。稳妥做法是把环境变量写在.zprofile然后在.zshrc里加一行source ~/.zprofile。这样一来终端、IDE、自动化脚本都能拿到同一份配置。如果你写脚本时用zsh -l这种 login shell 方式.zprofile会被读如果脚本用zsh不带-l.zshenv才会被读。所以对于要跑定期任务、CI 本地模拟这种场景把核心变量放一份进.zshenv也是一种补充方案。不过.zshenv在每个 zsh 进程启动时都会加载别在里面放太重的东西。另一个经验是追加配置前先检查文件里有没有写重复。我见过有人echo export PATH... .zprofile连续执行了三次结果 PATH 里塞了三遍同样的路径。改用brew shellenv之后这个问题基本就没了。6.2 值得长期开启的 HOMEBREW_ 变量长期使用的机器我建议保留这几项HOMEBREW_API_DOMAIN、HOMEBREW_BOTTLE_DOMAIN、HOMEBREW_BREW_GIT_REMOTE、HOMEBREW_CORE_GIT_REMOTE、HOMEBREW_NO_ANALYTICS。镜像相关的变量常驻没问题换来的是下载速度稳定。对HOMEBREW_NO_AUTO_UPDATE我的态度是“按需开别当常态”。如果你受够了每次 install 前都等更新可以临时在命令行这样用HOMEBREW_NO_AUTO_UPDATE1 brew install some-package而不是写死在配置文件里。频繁跳过自动更新时间久了公式列表会变旧某些新包的依赖解析就会失败。6.3 几个我踩过坑后的习惯第一绝对不用sudo跑 brew。哪怕安装时报权限错误也优先chown而不是sudo brew不然整个前缀目录的归属都会乱后面卸载都找不到干净的状态。第二macOS 重装之后恢复 Homebrew 的顺序我建议固定为先装 CommandLine Tools再确认自定义目录是否还在Time Machine 恢复了就直接复用然后重建环境变量文件最后brew doctor。凡是重新 clone 的记得把 tap 目录的 homebrew-core 也补齐不然会出现“brew 能跑但装什么都说找不到 formula”的情况。第三安装前先看一眼brew config里的输出。它能明确显示当前HOMEBREW_PREFIX、HOMEBREW_BOTTLE_DOMAIN是不是你期望的值。排查问题时先看 prefix再看架构最后看网络八成的问题都在这三层里。这套自定义目录方案我实际用下来最舒服的一点是不用 sudo 也能在自己的用户目录里把整个工具链管得明明白白备份迁移都顺带覆盖了。这篇文章里所有命令我都至少在两台 M 系列机器上验证过你照着顺序走环境变量这一关应该不会再卡住你。