Mac开发环境基石：Homebrew与RVM实战配置全解析

刚拿到一台新Mac，装开发环境最先要动的就是包管理器和语言版本管理器。Homebrew负责解决“软件从哪来、依赖怎么管”，RVM负责解决“Ruby版本怎么切、项目环境怎么隔离”。这两个工具虽然装起来都是一行命令，但背后涉及的目录权限、路径顺序、编译依赖、shell配置，坑不少。这篇就从原理讲到实操，把我这几年配置Mac开发环境踩过的坑和总结出的流程完整过一遍，适合刚入手Mac的新手，也适合一直用但没理顺环境逻辑的老朋友。

1. Mac开发环境为什么要从这两个装起

1.1 没有包管理器的Mac开发体验

很多人第一次在Mac上装软件，是去官网下载.dmg双击拖进Applications。这个流程对付日常App没问题，但轮到开发工具就难受了。你装一个需要编译的库，下载源码后发现还依赖另外三个库，三个库又依赖更多库，而且系统自带的版本往往偏旧，或者干脆缺了编译需要的头文件。手动处理这些依赖关系，本质上是在跟系统底层搏斗，折腾一晚上可能只是装了个不到一兆的工具。

后来macOS也内置了安装工具，但系统自带的那个不能装第三方软件，而且版本更新慢。社区里大家最常用的方案就是Homebrew。它把软件装到一个独立目录里，维护一份完整的依赖关系表，你要装A，它自动把A依赖的B、C、D一起拉下来装好，升级和卸载也一条命令。对开发者来说，这是Mac环境的地基，什么node、git、nginx、redis、openssl，全都可以通过它管理。

1.2 Homebrew和RVM的分工

Homebrew是“包管理器”，负责通用软件的安装和依赖处理。RVM是“Ruby版本管理器”，专门管Ruby环境。两者经常被放在一起提，是因为很多Mac开发者的主力语言就是Ruby，或者需要运行Ruby生态里的工具链，比如打包脚本、自动构建脚本。问题在于，macOS系统自带一个Ruby，版本固定、升级麻烦，而且你用系统的Ruby装全局gem，一不小心就把系统环境搞乱了。你手头如果有两个项目，一个要求Ruby 2.7，另一个要求3.2，单靠系统自带的那个版本根本没法定制。

RVM的定位就是“版本仓库”。你可以在它里面同时装多个Ruby版本，通过一条命令切换当前终端用哪个，还能为每个项目创建独立的gemset，相当于给每个项目的依赖包建了独立小房间。Homebrew管软件安装，RVM管Ruby版本和Gem依赖，两者并行不冲突，配合起来就是一套完整的Mac开发底座。

1.3 动手安装前先确认三件事

第一个是芯片架构。Apple Silicon的Mac和Intel的Mac，Homebrew的安装路径不一样。前者装到/opt/homebrew，后者装到/usr/local。很多教程里只写了一种路径，照着抄容易出问题。你可以在终端里执行uname -m，看到arm64就是Apple Silicon，看到x86_64就是Intel。

第二个是系统自带的编译工具链。Homebrew和RVM在安装某些软件时要本地编译，依赖Xcode Command Line Tools。安装方法是在终端执行xcode-select --install，如果系统提示已经安装或让你同意许可，跟着提示操作就行。这个工具集不装好，后面Homebrew装软件和RVM编译Ruby时报的错会让人一头雾水。

第三个是网络环境。两个安装脚本都要从远程拉取文件和Git仓库，网络不通畅的时候容易在中途失败。这不是你的操作问题，是环境问题，解决思路是换用你所在网络环境下可访问的公共镜像地址，这个后面会专门说。

2. 安装Homebrew：一条命令背后有哪些门道

2.1 官方安装脚本的运行原理

Homebrew官方推荐的安装命令长这样：

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

意思是先通过curl下载一段安装脚本，再用bash执行。这种“curl管道给bash”的做法在社区里讨论很多，风险在于脚本内容你不一定逐行看过。Homebrew的官方脚本算是比较透明公开的，装之前你可以先用curl把脚本下载到本地，花几分钟通读一遍，看看它做了哪些操作，确认没问题再执行：

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

脚本核心逻辑就几步：检查系统架构、检测Xcode Command Line Tools是否安装、确定目标安装目录、创建目录结构、克隆主仓库和核心仓库、设置权限和所有权、写入shell配置。读懂这些再装，比盲敲命令强得多。

2.2 脚本执行后目录里多了什么

装完之后，Homebrew会把自己的可执行文件放在/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel），然后在你的zsh或bash配置里写一行，让它进入PATH环境变量。它的软件包本体放在/opt/homebrew/Cellar，每个软件一个独立目录，通过/opt/homebrew/opt里的软链把当前激活的版本指过去，最后在/opt/homebrew/bin再放一层软链。这种三层结构的好处是，你可以同时保留多个软件的多个版本，切换版本只需改软链方向。

这里面有个关键点：Homebrew不希望用户用sudo安装或操作。因为一旦用root权限创建的文件，普通用户后续升级、卸载都可能遇到权限错误。它安装时尽量把目标目录的所有权交给当前用户，所以你要确保用于安装的账户就是平时开发使用的账户。如果安装时报目录无法写入，多半是之前用管理员权限动过目录所有权，sudo chown -R $(whoami) /opt/homebrew可以修正，但这属于救火操作，正常情况下不该走到这一步。

2.3 安装失败的高频原因和对应处理

安装失败最常见的症状是脚本跑一会就卡住或报error: RPC failed，原因是拉取Git仓库时网络连接中断。解决思路不是反复重试原脚本，而是先配置好公共镜像地址再装。Homebrew支持通过环境变量把仓库地址指向镜像，常见做法是在安装脚本执行前设置：

export HOMEBREW_API_DOMAIN="https://镜像地址" export HOMEBREW_BOTTLE_DOMAIN="https://镜像地址" export HOMEBREW_BREW_GIT_REMOTE="https://镜像地址/git/homebrew/brew.git" export HOMEBREW_CORE_GIT_REMOTE="https://镜像地址/git/homebrew/homebrew-core.git"

注意，镜像地址要以你当时网络环境下实际可用为准，不同区域、不同运营商访问速度差异很大，具体域名可以查一下当前主流公共仓库提供的服务地址，把上面的占位符替换成实际的。配置完之后再重新跑官方安装脚本，脚本检测到环境变量已设置，就会从镜像仓库下载。

还有一种失败是卡在Updating Homebrew...或Downloading Command Line Tools。后者是系统要下载编译工具集，体积大、耗时久，耐心等即可，不要中断。如果你想跳过自动安装工具集，可以提前装好xcode-select --install，装完再跑Homebrew脚本。

2.4 装完后的校验和日常维护

安装完成后第一件事，在终端输入：

brew --version brew doctor

brew doctor会检查环境有没有异常，比如目录权限不对、有重复的路径配置、系统里有没被管理的残留文件。它会给出警告和建议，逐条看完处理掉，环境基本就干净了。初次安装后建议执行一次brew update，把仓库信息和软件目录更新到最新。日常工作里，brew install装新软件，brew upgrade升级所有软件，brew services start管理后台服务，brew cleanup清理旧版本残留。这套命令记住前三个就够用了。

我个人的习惯是装完先跑brew install wget这种轻量工具测试一下链路是否正常。如果下载过程和依赖解析都顺畅，说明Homebrew工作正常，下一步可以放心装RVM。

3. 安装RVM：Ruby版本不再打架

3.1 为什么RVM不推荐用Homebrew装

你用brew install rvm也能装上，但我强烈不建议这么做。原因有三层。第一，RVM的核心机制是修改当前登录shell的PATH和函数定义，它需要一个“登录后加载”的过程。Homebrew安装的版本在二进制分发上没问题，但它不会自动帮你配置shell加载逻辑，装完还要手动处理，操作步骤反而比官方脚本更多。第二，RVM官网明确建议用官方安装脚本，社区里针对官方脚本的排错资料也最全，出问题时查资料方便。第三，RVM会自己管理一套Ruby依赖库，和Homebrew管理的依赖在目录上是隔离的，用Homebrew装会让两者边界变得模糊，以后排查问题不知道看哪边。

所以，老老实实用RVM官方推荐的安装方式：下载它的安装脚本，用bash执行。

3.2 RVM安装实操

安装命令是：

curl -sSL https://get.rvm.io | bash -s stable

脚本会clone RVM仓库到用户目录下的.rvm文件夹，然后修改shell配置文件。装完后要重新加载shell配置，或者新开一个终端窗口：

source ~/.rvm/scripts/rvm rvm -v

这一步容易踩坑的是：你明明装好了，输入rvm却提示command not found。原因是RVM对shell的版本有要求，如果还在用bash，它默认只改~/.bash_profile，而现在macOS默认shell是zsh，需要确保~/.zshrc或~/.zprofile里有RVM的加载语句。有些教程会让你执行source ~/.profile之类，不对症，大概率是shell配置文件搞混了。

官方脚本装的RVM会要求在配置里加载这段代码：

[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"

检查一下你当前的shell是哪个，然后在对应配置文件里确认这段话存在。如果不在，手动加上，再执行source ~/.zshrc即可。

3.3 RVM的三个核心概念：默认版本、wrapper与gemset

RVM装好之后要先理解三个概念，不然你会在“到底用的哪个ruby”“gem装哪去了”这些问题上反复晕。

第一个是默认版本。rvm list可以列出当前RVM管理的所有Ruby版本，前面带=>的是当前终端会话使用的版本，带*的是默认版本。每次新开终端，RVM会加载默认版本。用rvm use 3.2.2 --default可以切换并设置默认。

第二个是wrapper（包装器）。RVM会生成一些可执行脚本，把当前选中的Ruby和gem环境包起来。这意味着你输入ruby、gem、bundle、rake等命令时，RVM已经替你把PATH调整到对应版本的目录了。你可以执行which ruby，看看路径是不是指向用户目录的.rvm/rubies，而不是系统的/usr/bin/ruby。如果指向系统路径，说明RVM没有正确加载。

第三个是gemset。它相当于Ruby世界的虚拟环境，但比Python的虚拟环境更底层。你可以为每个项目创建一个独立的gemset：

rvm use 3.2.2@myproject --create

之后在这个目录里用gem install装的包，都会进入这个gemset，不会污染全局环境。切换项目时切回对应的gemset，依赖就不会互相打架了。

3.4 用RVM装一个指定版本的Ruby

先看RVM支持哪些版本：

rvm list known

列表很长，包含MRI、JRuby、TruffleRuby等。对绝大多数项目来说，选择当前主流的MRI版本就好。安装：

rvm install 3.2.2

这一步耗时长短取决于你是否已经有编译依赖。RVM会自动尝试安装必要的依赖，但它在系统里的依赖检测能力有限，经常提示缺少openssl、readline、libffi等。解决方法是先用Homebrew把这些依赖装好：

brew install openssl readline libffi

然后让RVM编译Ruby时找到它们。新版RVM会自动识别Homebrew安装的依赖，如果遇到找不到的问题，可以设置编译参数，或者先执行rvm requirements查看它还缺什么。rvm requirements这个命令很有用，它会分析当前系统缺少的编译依赖，并给出对应的安装建议。

安装过程是源码编译，屏幕会滚动大量输出，看到Install of ruby-3.2.2 - #complete就表示装好了。接着：

rvm use 3.2.2 --default ruby -v gem -v

ruby -v显示ruby 3.2.2就说明RVM工作正常。执行which ruby，确认路径在.rvm/rubies下面，这代表你用的是RVM管理的Ruby，而不是系统自带Ruby。

4. 把两兄弟接上线：日常开发环境的整合

4.1 PATH优先级决定“用哪个ruby”

Homebrew和RVM各自都想往PATH里加东西，那到底谁排前面？执行echo $PATH看一下。正常情况下，.rvm目录相关的路径应该排在前面，因为你看which ruby时，优先命中的才起作用。如果发现which ruby指向了/usr/bin/ruby，说明系统的默认路径占了优先位置，RVM的加载没有生效。

RVM在shell配置里的加载位置有讲究，它应该放在Homebrew初始化之后。原因是RVM在加载时会自动寻找可用的ruby，如果Homebrew的路径在前面，RVM可能选择不到自己编译的版本。我的实践经验是：在~/.zshrc里，先让Homebrew的初始化语句出现，紧接着放RVM的加载语句，保持这个顺序，基本不会出现路径错乱。

还有一种情况，你装了ruby-install或者手动编译过Ruby到/usr/local/bin，会和RVM抢路径。排查方法就是在which ruby不理想时，逐段注释配置，找到是哪一行在干涉。

4.2 让RVM利用Homebrew的依赖

RVM编译Ruby最烦的问题是系统库不齐全。macOS自带了一部分开源库，但版本老、头文件不全。Homebrew安装的库在/opt/homebrew/opt下，RVM不一定默认能找到。你需要让RVM在编译时知道这些库的位置。

较新版本的RVM会在安装ruby前自动读取Homebrew环境，但保险起见，我习惯在安装前先确认依赖在Homebrew里存在：

brew list --versions openssl readline libffi

如果没装，就先brew install。如果RVM编译时仍然报找不到openssl，可以用rvm install 3.2.2 --with-openssl-dir=$(brew --prefix openssl)的方式指定目录。brew --prefix openssl会输出当前Homebrew里openssl的实际安装路径，这种方式比写死路径更优雅，不同芯片架构也能通用。

日常使用中，Homebrew和RVM的边界要分清。需要系统级的编译工具、数据库，走Homebrew；需要管理Ruby版本、项目级gem，走RVM。有些人会习惯用gem install装全局工具，这不推荐，除非你明确知道这个工具不会和项目依赖冲突。否则把它放进项目自己的gemset更安全。

4.3 一个模拟项目的完整环境搭建流程

假设你接手一个叫“模拟项目X”的旧项目，仓库里的.ruby-version写着3.0.6，Gemfile锁定依赖。我的操作流程是这样的：

第一，确认RVM里有没有这个版本：

rvm list

没有就装：

rvm install 3.0.6

第二，进入项目目录，让RVM自动读取.ruby-version并切换版本：

cd ~/work/模拟项目X rvm use 3.0.6

第三，创建独立的gemset并绑定：

rvm gemset create proj_x rvm use 3.0.6@proj_x echo "3.0.6@proj_x" > .ruby-gemset

第四，安装Bundler并安装项目依赖：

gem install bundler bundle install

之后在项目里执行的所有ruby命令和gem命令，都运行在3.0.6@proj_x这个独立环境里，不会影响系统的Ruby，也不会被其他项目干扰。这个流程跑通后，整个团队只要都装好Homebrew和RVM，拉下代码执行同样的步骤，环境就一致了，这是开发协作里最省心的一件事。

5. 常见问题与排查技巧实录

5.1 高频错误速查表

上面这几类是我见到频率最高的。其中“目录不能写”和“找不到命令”占了日常问题的一大半，而且多发生在安装顺序混乱、shell配置被多次修改的机器上。通常解决这两类问题，就够让环境正常运转了。

5.2 我的几个排查小习惯

第一个习惯是，遇到“命令找不到”先查which。不管brew还是rvm，先问一句它到底装在哪、当前终端知不知道它在哪。很多人的问题不是没装上，而是装了但路径没进当前会话。which输出为空，就要怀疑PATH配置；输出到系统目录，就怀疑RVM加载顺序。

第二个习惯是，改完配置后新开终端而不是只执行source。source只能让当前会话生效，新开终端走的是全新加载流程，才能模拟真实使用场景。我见过有人source之后一切正常，一关终端就回到解放前，就是因为配置根本写在错误的文件里，source只是临时救了那个会话。

第三个习惯是，尽量保持依赖来源单一。你自己从源码编译一个软件装到/usr/local/bin，和Homebrew管理的同一个软件冲突时，优先级和版本很容易打架。能用Homebrew就都用Homebrew，能用RVM就都用RVM，不要两条路并行装同一个东西。有一次我排查一个诡异问题发现，curl命令居然有三个来源同时存在，版本还各不相同，这种环境想查清问题非常浪费时间。

第四个习惯是，在项目里用.ruby-version和.ruby-gemset把环境约定固化，而不是靠手输命令。只要团队都装了RVM，进入项目目录时它自动切换版本，用bundle exec执行命令时也严格基于项目环境，能避免一大堆“我本地没问题”的灵异事件。

最后分享一个小技巧。每次装完Homebrew和RVM，我会立刻把两个版本号和一个测试项目的运行结果记录下来。别小看这个动作，几个月后你再回头排查环境问题时，这份记录能直接告诉你环境从哪个节点开始变的，比对着系统目录瞎猜高效得多。新Mac环境搭建，这套流程走完，基座就算稳了，后面装什么语言、什么框架都是在它上面叠砖，地基打得干净，后面省心很多。