做 Ruby 开发的人十有八九都撞上过这么个场景新项目拉下来bundle install直接报错提示当前 Ruby 版本过低或者gem install某个包时一路编译到一半卡在某个原生扩展上报出一堆看不懂的错。而这一切的根源往往是 MacOS 系统自带的 Ruby 版本太老压根跟不上现在 gem 的更新节奏。把这句“MacOS升级ruby版本”变成现实就成了不少开发者开工前的第一件事。这篇文章主要围绕“升级 Ruby”这件事讲清楚三块内容一是为什么不能用系统自带的 Ruby二是主流的几套升级方案之间怎么选、各自适用什么场景三是把我实测过的完整升级流程和踩过的坑全部写出来。适合刚接触 Ruby 生态的新人也适合被版本问题折磨过但一直没系统性梳理过的老手。看完之后你可以直接照着操作顺利把 Ruby 切到一个干净、可控、不污染系统的版本。1. 为什么非要折腾 Ruby 版本——系统自带 Ruby 的坑看了就懂很多人在 MacOS 上升级 Ruby 之前都有一个困惑系统里明明有 Rubyruby -v也能输出版本号为什么非要去动它这个问题的答案得从 MacOS 预装 Ruby 的特殊身份说起。1.1 系统自带 Ruby 到底有多老MacOS 自带的 Ruby 版本常年停留在 2.6.x。注意这个版本是系统预装给底层脚本用的不是给你做开发用的。苹果自己在系统组件里依赖了它比如一些系统配置工具、CocoaPods 的底层依赖逻辑都可能跟这个 Ruby 有关系。问题在于2023 年之后 Ruby 官方已经停止了对 2.6 的安全维护到了 2024 年 3.0 也进入了维护尾期。现在的 gem 生态里Rails 7.1 要求 Ruby 2.7Rails 8 更是直接要求 Ruby 3.2。也就是说你只要拉一个稍微新一点的项目系统自带的 2.6 连bundle install都跑不过去。更麻烦的是系统自带 Ruby 的 gem 目录在系统级目录下普通用户没有直接写入权限。你执行gem install rails大概率会看到类似ERROR: While executing gem ... (Errno::EACCES) Permission denied的报错。这时候很多人第一反应是加sudo但这恰恰是后面一系列混乱的开始。1.2 不升级 Ruby 的连锁反应不升级 Ruby最直接的后果就是新项目全部跑不起来。除了版本号不满足之外还有两个非常隐蔽的坑。第一个坑是 OpenSSL 链接问题。系统自带 Ruby 编译时链接的是系统自带的 OpenSSL 库而 MacOS 官方一直在升级系统组件系统的 OpenSSL 版本和 Ruby 编译时期望的版本很容易对不上。表现就是你在执行gem install某些依赖加密相关的 gem 时报出来类似openssl/ssl.h not found的编译错误或者运行时直接提示openssl加载失败。第二个坑是原生扩展编译问题。很多 gem 带有 C 扩展比如nokogiri、pg、ffi它们在新版本里往往要求较新的编译器和较新的 Ruby API。老版本 Ruby 上编译这些 gem经常会因为 API 不兼容导致编译失败。这类报错信息长、杂、不统一对新手极不友好排查起来特别费时间。1.3 升级前必须搞清楚的三个问题在动手之前先别急着执行命令有三件事需要提前确认清楚否则很容易白折腾。第一件搞清楚你现在用的 Ruby 究竟是哪来的。很多人以为系统里只有一个 Ruby其实 MacOS 上有多个入口。可以用这三条命令一次性查清楚which ruby which gem echo $PATH如果which ruby输出的是/usr/bin/ruby说明你还在用系统自带的旧版本。如果是/usr/local/bin/ruby或者/opt/homebrew/bin/ruby说明你之前可能已经用 Homebrew 装过新版了。如果输出了~/.rbenv/shims/ruby之类路径说明你已经装了 rbenv只是可能还没把版本切过去。第二件搞清楚你的项目要求什么版本。每个项目目录下要么有.ruby-version文件要么在Gemfile里写了ruby 3.x.x。在项目目录下执行cat .ruby-version 2/dev/null grep ^ruby Gemfile 2/dev/null这两条命令能很快告诉你目标版本。如果没有输出任何内容说明项目没锁定版本那就直接选当前稳定版本即可。第三件搞清楚你要不要保留旧版本。如果你只是为了跑一个新项目完全没必要保留老版本直接全局切到新版本就行。但如果你的老项目里有依赖锁定在旧版本上那就需要用到版本管理工具让不同项目各用各的 Ruby。这也是我后面推荐 rbenv 而不是直接 Homebrew 覆盖安装的核心原因。2. 三条升级路线对比别装完才后悔MacOS 上升级 Ruby方案看起来不少实际主流的归纳下来就是三条路Homebrew 直装、rbenv 版本管理、RVM 版本管理。每一条我都实际用过优缺点非常清楚。2.1 方案一Homebrew 直接装新版最简单粗暴的方式就是直接用 Homebrew 装一个 Rubybrew install ruby3.3装完之后Ruby 本体和 gem 都会放在/opt/homebrew/opt/ruby3.3目录下Apple Silicon 路径。但这里有个非常容易忽略的细节Homebrew 装好的 Ruby 默认不会进 PATH也就是说你执行ruby -v时系统仍然会优先走/usr/bin/ruby。你需要自己手动把路径加进~/.zshrcexport PATH/opt/homebrew/opt/ruby3.3/bin:$PATH这还没完之后gem install出来的可执行命令比如rails、bundler它们的安装目录是/opt/homebrew/lib/ruby/gems/3.3.0/bin这个路径也得加到 PATH 里。很多新手在这一步折腾半天最后发现命令装了但找不到就是因为少了这条路径。这套方案的优点是简单直接适合那种一次装好、长期不换版本、也不需要维护多个项目的场景。缺点是没法在多个 Ruby 版本之间快速切换升级某个版本时容易把环境搞乱。另外如果你之前用sudo gem install往系统 Ruby 里装过东西Homebrew 装的新版本跟你旧的环境完全隔离需要重新装一遍所有 gem。2.2 方案二rbenv 版本管理推荐rbenv 的思路跟 Homebrew 完全不同。它不直接管理 Ruby而是在你的~/.rbenv目录下维护一个 Ruby 版本池。你可以同时安装 3.1、3.2、3.3 等多个版本然后在不同项目目录下分别指定用哪个版本。它的核心机制是 shims垫片。rbenv 会在你的 PATH 最前面插入一个~/.rbenv/shims目录这个目录里有一堆名字跟ruby、gem、bundle一样的转发脚本。你执行ruby时实际先执行的是垫片脚本垫片脚本会根据当前目录下的.ruby-version文件、$RBENV_VERSION环境变量或者全局设置自动把命令转发给对应版本的 Ruby。这个过程对使用者来说是无感的但它带来的体验提升是巨大的切换项目不需要改任何 PATH也不用反复 source 配置文件。2.3 方案三RVM重但有人确实爱用RVM 也是一套老牌的 Ruby 版本管理工具功能非常强大支持 gemsetgem 集合隔离可以在同一个 Ruby 版本下建立多个相互隔离的 gem 环境。这个功能在某些大型项目里确实好用。但 RVM 的问题也明显。它默认会修改 shell 的cd行为每次切目录都要跑一段 RVM 的钩子脚本体感上明显比 rbenv 重不少。而且如果你之前用过rvm implode想彻底卸载你会发现自己要手动清理一堆环境变量和 shell 配置稍不留神就残留很多垃圾。2.4 选型对比速查表方案安装复杂度多版本切换隔离性推荐场景Homebrew 直装最简洁不支持一般一个项目、不想折腾rbenv中等强按目录自动切换每个版本独立日常主力开发、多项目并存RVM偏高强还要 gemset每个版本和 gemset 都独立老用户习惯、复杂环境需求我的建议非常明确绝大多数情况下选 rbenv。它足够轻、足够直观出了问题也最容易排查。下文整套实操我都基于 rbenv。3. 实测 rbenv 完整升级流程照着抄就行这一部分是我实际走通的完整流程。环境是 Apple Silicon 芯片的 MacBook系统为较新版本的 MacOS默认 shell 为 zsh。不同版本系统下命令基本一致差异只在 Homebrew 的安装前缀路径上。3.1 第一步安装 rbenv 和 ruby-buildrbenv 本体负责版本切换ruby-build 负责具体的 Ruby 编译安装。这两个都能通过 Homebrew 直接装brew install rbenv ruby-build安装完之后先别急着关终端验证一下 rbenv 是否可用rbenv -v如果输出类似rbenv 1.2.0说明安装成功。这里有个细节不少教程会额外提到用git clone方式安装 rbenv 和 ruby-build但那主要是为了能拿到每日更新版。对于绝大多数用户来说Homebrew 版本完全够用而且补丁更新跟得也及时。3.2 第二步配置 shell 环境rbenv 有一个初始化命令需要写进~/.zshrc它会在每次打开新终端时自动加载 rbenv 的 shims 和补全逻辑echo eval $(rbenv init -) ~/.zshrc然后重新加载配置source ~/.zshrc这时候在终端里执行rbenv init -一眼就能看到这个命令在做什么它会创建一个~/.rbenv/shims目录并把这个目录插入 PATH 的最前面。这个目录里的垫片脚本是整个 rbenv 自动切换版本的关键。提示source ~/.zshrc只在当前终端窗口生效新开的终端窗口会自动读取。养成改完配置后“新开一个终端”的习惯避免环境不一致的错觉。验证配置是否生效的方法很简单执行which ruby如果路径变成了~/.rbenv/shims/ruby说明 rbenv 已经接管了 Ruby 命令。如果仍然是/usr/bin/ruby说明 rbenv 初始化没有成功优先检查~/.zshrc里那行命令是否真的写进去了。3.3 第三步安装新版 Ruby先查看当前 rbenv 里已经有哪些版本以及有哪些版本可装rbenv versions rbenv install -l以安装 3.3.5 为例这是目前比较稳定的版本实际阅读本文时请以rbenv install -l列出的最新版本为准rbenv install 3.3.5这一步是整个流程中最耗时也最容易出问题的环节。rbenv 默认通过 ruby-build 从源码编译 RubyApple Silicon 上通常需要 5 到 10 分钟不等具体取决于芯片型号和网络状况。为了保证编译顺利建议提前装好编译依赖brew install openssl3 readline libyaml这几个库是 Ruby 编译时最常见的依赖项。openssl不用说很多 gem 靠它做加密readline是 Ruby 的irb和pry交互式命令行底层依赖libyaml是 Psych gem 的底层依赖没有它YAML 解析会有各种诡异问题。如果编译中途失败也别慌先执行rbenv install 3.3.5 -v-v参数会输出完整的编译日志。90% 的情况都能从日志末尾找到真正的报错原因。最常见的两类是依赖缺失和编译器问题前者补齐依赖后重试即可后者通常提示你安装 Xcode Command Line Toolsxcode-select --install如果已经安装过系统会提示command line tools are already installed那就直接用xcode-select -p确认路径存在即可。3.4 第四步切换全局与项目版本安装完成之后执行rbenv versions能看到刚才装的版本已经出现在列表里。此时依然不会自动生效还需要两步操作。先切全局默认版本rbenv global 3.3.5这一步只改了~/.rbenv/version文件里的内容作用是告诉 rbenv“默认情况”下使用 3.3.5。再在某一个项目目录里指定专用版本cd /path/to/your/project echo 3.3.5 .ruby-version.ruby-version文件是 rbenv 按目录自动切换的依据。只要这个文件存在进入该目录后ruby -v就会自动显示文件里指定的版本切出去后又回到全局版本。验证是否切换成功ruby -v which ruby期望的输出是ruby 3.3.5p...和~/.rbenv/shims/ruby。如果版本还是旧的用rbenv rehash重新生成一遍垫片脚本一般就能解决。3.5 第五步重新装 gem 与 bundler这是很多人升级后忽略的一步。每个 Ruby 版本都有自己独立的 gem 安装目录切换到新版 Ruby 后原来的 gem 并不会自动带过来。你在旧版本下装过的rails、puma、sidekiq等在新版本下全都不存在。先装 bundler每个 Ruby 版本都应该有自己的 bundlergem install bundler然后在项目目录下重新安装依赖cd /path/to/your/project bundle install这里有个常见的报错Your Ruby version is 3.3.5, but your Gemfile specified 3.2.0。出现这个报错不是环境问题是项目里Gemfile锁死了版本号。你需要先把Gemfile里的ruby版本声明改成当前版本或者直接删掉这行让 bundler 自适应。具体改法要看项目团队约定但如果项目在.ruby-version里已经锁了版本Gemfile里的声明保持跟它一致即可。4. 项目侧的连锁适配Gemfile、bundler 与 gem 源升级完 Ruby 本体只是万里长征走完了一半。真正让项目跑起来还得处理 gem 层面的连锁问题。这部分最容易踩坑而且很多坑报错信息特别迷惑让人误以为还是 Ruby 没装好。4.1 gem 源优先换掉官方源新版本 Ruby 装好之后gem sources默认指向官方源https://rubygems.org。这个源在国内网络环境下极其不稳定经常出现拉一半超时的情况表现为gem install或bundle install卡在某个包上长时间没有反应。建议直接切到国内镜像源。当前比较常用的镜像源是https://gems.ruby-china.com实际上它是 Ruby China 社区的镜像。操作方式gem sources --remove https://rubygems.org/ gem sources --add https://gems.ruby-china.com/ gem sources --listGemfile里的 source 也要同步改掉。把第一行的source https://rubygems.org改成source https://gems.ruby-china.com。如果不改bundle install仍然会走官方源。注意如果你所在团队有内部私有 gem 源不要把 Gemfile 里的 source 无脑替换。应该优先询问团队维护者使用私有源或者source多源写法。4.2Gemfile.lock与 bundler 版本Gemfile.lock锁定了项目当前所有依赖的精确版本号。升级 Ruby 之后bundle install会先检查Gemfile.lock里记录的BUNDLED WITH是不是跟当前 bundler 版本一致。如果版本不一致会出现类似Bundler could not find compatible versions for gem bundler: ... Current Bundler version: bundler (2.4.22)解决办法有两个方向。一个是用当前 bundler 版本重新生成 lock 文件bundle update --bundler另一个是先把 bundler 切到 lock 文件期望的版本gem install bundler -v 2.3.26 bundle _2.3.26_ install我个人更推荐前一种直接升级 lock 文件里的 bundler 版本就好除非项目对 bundler 版本有硬性要求。4.3 原生扩展 gem 的重新编译升级 Ruby 后最隐蔽的坑就是原生的 C 扩展 gem。这些 gem 在安装时会根据当前 Ruby 版本的头文件和 API 编译出对应的.bundle动态库文件。切换版本后这些二进制库跟新版 Ruby 不兼容轻则运行时报LoadError重则整个require直接崩溃。典型报错长这样LoadError: dlopen(/Users/xxx/.rbenv/versions/3.3.5/lib/ruby/gems/3.3.0/gems/nokogiri-1.16.5/lib/nokogiri/nokogiri.bundle, 0x000A): missing symbol _ruby_xmalloc原因很简单这个.bundle文件是在旧 Ruby 版本下编译的里面的符号表跟新版本对不上。解决办法只有一个重新安装这个 gem。gem uninstall nokogiri gem install nokogiri更稳妥的是在项目目录下强制重新安装所有带原生扩展的 gembundle pristinebundle pristine会按照 lock 文件里的版本重新编译安装所有 gem把当前环境里的二进制包全部跟新版 Ruby 对齐。升级 Ruby 之后先执行bundle pristine是我比较推荐的标准动作能避免掉大量奇葩 LoadError。4.4bundle exec与全局 gem 的边界这次升级时我还发现一个很典型的场景。项目里Gemfile写了rails (8.0.0)但你在全局环境gem list rails会看到另一个版本。如果你直接在项目目录敲rails -v大概率会报错Could not find rake-13.0.6, rake-13.1.0 in locally installed gems这个问题的根源是你调用的rails命令来自全局 gem 目录而不是项目的 bundle 环境。解决方式是养成用bundle exec的习惯bundle exec rails -v bundle exec rspec bundle exec rake db:migrate如果你不想每次都写bundle exec也可以用bundle config set --local path vendor/bundle比如但那个是另一个话题了。升级 Ruby 之后要注意确认全局命令与 bundle 环境命令不是同一个入口遇到诡异问题时先区分好是在跑全局 gem 还是项目 gem。5. 常见报错与排查技巧实录这节是实打实的踩坑记录。我把升级过程中遇到的典型报错和排查思路整理成了速查表后面再补几个容易踩的细节。5.1 常见错误速查表报错现象主要成因解决办法rbenv: version 3.3.5 is not installed执行命令时所在目录要求某个未安装的版本执行rbenv install 3.3.5或检查.ruby-version文件名拼写Your Ruby version is 2.6.10, but your Gemfile specified 3.3.5Gemfile版本声明与当前实际激活版本不一致确认rbenv versionsrbenv global或项目.ruby-version是否已指向 3.3.5gem install xxx编译时报openssl/ssl.h not found编译期缺 OpenSSL 头文件brew install openssl3必要时用--with-openssl-dir指定路径LoadError: dlopen(...) missing symbol _ruby_xmalloc旧版 Ruby 下编译的原生扩展 gem 与新版 ABI 不符执行bundle pristine强制重编译所有原生扩展 gemgem install提示权限拒绝使用了系统自带 Rubygem 目录不可写切到 rbenv 或 Homebrew 管理的 Ruby不要用 sudo 硬装rbenv: command not foundrbenv 初始化命令未加载检查~/.zshrc中的eval $(rbenv init -)重新加载配置文件bundle: command not found新版 Ruby 下还没装 bundlergem install bundlerbundle install长时间卡住不动网络访问官方 gem 源不稳定换镜像源或设置 gem 源超时环境变量5.2 别用 sudo 装 gem这条值得单独拿出来说。刚开始接触 Ruby 的人遇到权限错误第一反应就是sudo gem install xxx。这个动作非常危险。系统自带 Ruby 的 gem 目录归属于root你用 sudo 强行装 gem会往系统目录里写入文件。这些文件一旦跟系统组件依赖的其他 gem 版本冲突轻则该命令失效重则影响依赖系统 Ruby 的工具。更糟的是你后面切到 rbenv 管理的 Ruby这套 sudo 环境又用不上等于白装还白白污染了系统。正确姿势永远是先确认which ruby已经指向 rbenv 或 Homebrew 的 Ruby再执行gem install。5.3rbenv rehash到底有什么用rbenv 的机制是靠shims目录里的一堆垫片脚本。每当你新装一个 gem而这个 gem 提供了可执行命令比如rails、sidekiqrbenv 需要重新扫描所有已安装 gem把新命令的垫片补全到shims目录里这个过程就是rehash。正常情况下rbenv 会在gem install后自动触发 rehash不需要手动干预。但偶尔会遇到自动触发失败表现就是 gem 装好了命令却找不到。这时候手动执行一次rbenv rehash基本就能解决。如果 rehash 后命令还是找不到检查当前 Ruby 版本的 gem bin 目录有没有真的包含该命令ls ~/.rbenv/versions/3.3.5/bin/ | grep rails5.4 修改~/.zshrc后一定要开新终端验证这是非常容易被忽略的操作习惯。执行source ~/.zshrc后当前终端的环境确实更新了但新开的终端所加载的环境变量可能和你预期的并不一致。如果你改了 PATH 或 rbenv 初始化配置每次改完都建议直接新开一个终端然后立即执行echo $PATH | tr : \n | head -5 ruby -v which ruby确认 PATH 里~/.rbenv/shims在最前面且which ruby指向 shims 目录。这个习惯能帮你筛掉一半以上的环境配置问题。5.5 升级后跑一遍项目测试套件所有环境配置完成后别急着提交代码或宣布完成。进到项目目录先把测试套件完整跑一遍比如bundle exec rspec # 或 bundle exec rails test这一步是验证环境是否真正健康的最终标准。如果测试通过说明 Ruby 升级没有破坏项目依赖如果某些用例挂了优先看是不是某个 gem 的版本在编译后行为有差异可以查看官方发布的 changelog。6. 最后分享几个个人经验多次升级 Ruby 之后我慢慢总结出一套自己的标准工作流每次都很省事先在~/.zshrc里确认 rbenv 初始化再用rbenv install装新版本装完立刻rbenv global切过去然后进项目bundle pristinerebuild 一遍原生扩展最后跑测试收尾。这套流程总共不超过十五分钟踩坑率极低。另外再分享一个小细节如果你在 MacOS 上同时维护多个项目强烈建议每个项目都提交一个.ruby-version文件。不要依赖全局默认版本也不要把不同项目的版本要求混在一起。这样团队协作时任何人 clone 项目并用 rbenv 打开终端都能自动切到正确版本省掉大量“在我机器上是好的”这种问题。升级 Ruby 本身不是目的让项目稳定跑起来才是。遇到报错时先冷静判断是版本问题、依赖问题还是编译问题再对症处理基本都能顺利解决。希望这篇实测记录能帮你少走弯路轻松把 Ruby 环境整理得干干净净。