升级到 Sonoma 以后一头撞在 CocoaPods 安装的墙上，这种事我今年见了太多。群里隔三差五就有人甩过来一段报错截图，紧跟一句“我明明什么都装了，为什么 pod 还是用不了”。说实话，Sonoma 下装 CocoaPods 之所以劝退这么多人，不是 CocoaPods 本身变难了，而是 macOS 的 Ruby 环境结构变得比很多人以为的复杂得多。系统自带 Ruby、Homebrew Ruby、rbenv 管理下的 Ruby 混在一起，再加一个 SIP 权限限制，混乱程度直接拉满。
这篇文章我把 Sonoma 下安装 CocoaPods 的完整路径捋一遍，重点解决“Ruby 版本冲突”这个让人血压升高的核心问题。内容覆盖环境预检、两套可落地的安装方案、报错排查思路，以及从旧版本系统升级上来的存量环境怎么自救。无论你是刚拿到新 Mac 准备配环境，还是升级完系统发现 pod 全线崩盘，这篇都能直接拿来照着操作。
1. 先搞明白 Sonoma 上的 Ruby 为什么这么难缠：三个根因
很多人一上来就复制安装命令，失败了就换个命令再试，结果越试越乱。这种思路在 Sonoma 上行不通。你必须先意识到一个事实：你的 Mac 上可能存在三套 Ruby，而它们彼此之间互不认识。
1.1 系统 Ruby、Homebrew Ruby、rbenv Ruby 各占一方
macOS 从远古时代就内置了 Ruby，Sonoma 也不意外，系统自带的版本停留在 2.6.10。这个版本号很关键——它已经好几年没升级过了，因为苹果的系统组件依赖它，Apple 出于稳定性考虑不会贸然更新。
系统 Ruby 住在/usr/bin/ruby，它的 gem 安装目录在/Library/Ruby/Gems/2.6.0。这个目录有一个致命限制：受到 SIP 系统完整性保护，即使是管理员也不能随意写入，需要处理权限的绕行方案，而绕行的每一步都可能带来新的坑。
Homebrew 安装的 Ruby 则是另一个世界。它住在/opt/homebrew/opt/ruby（Apple Silicon 芯片）或/usr/local/opt/ruby（Intel 芯片），版本通常是 3.x，不会受到 SIP 限制，装 gem 也不需要sudo。问题是它默认不在你的 PATH 里，如果你不知道去配置路径，系统还是会去用老掉牙的/usr/bin/ruby。
rbenv 则是一个 Ruby 版本管理器，它让你可以在用户目录下安装任意版本的 Ruby，并按项目或者全局切换。它的核心价值在于：让普通用户拥有完整、独立的 Ruby 环境，并且切换到哪个版本完全由你说了算。
三套 Ruby 共存导致的直接后果是：你可能在 Homebrew 的 Ruby 下成功安装了 CocoaPods，但终端执行pod时，系统在 PATH 里先找到了系统 Ruby 的环境，报错找不到命令；或者反过来，你用系统 Ruby 的 gem 装到一半，遇到权限报错，然后你加上sudo强行装完，结果 CocoaPods 依赖的某些 gem 版本和 Homebrew Ruby 里的 gem 版本冲突，启动直接崩溃。
这就是“版本冲突”最常见的真实面目——不是某个具体版本装不了，而是多个 Ruby 环境在打架。
1.2 权限问题背后的真实机制
SIP 是 macOS 的安全防线，它限制了系统目录的写入。/usr/bin/ruby正是受保护区域。当你执行gem install cocoapods而没有加sudo时，系统会以写权限不足为由拒绝把文件写进/Library/Ruby/Gems/2.6.0。
常见的报错长这样：
ERROR: While executing gem ... (Gem::FilePermissionError) You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.大部分教程给出的“解法”是让你加sudo强行安装。我强烈不建议这么做。原因有两点：第一，sudo 之后你的终端具备了对 SIP 保护区域内写入的能力，这本身就是在松动系统安全边界；第二，即便安装成功，当你后续再用 Homebrew 或 rbenv 的 Ruby 时，两套 gem 目录同时存在，依赖版本很容易互相干扰。
1.3 冲突的根源不在版本号本身，而在 PATH
Ruby 版本冲突的精髓在于 PATH 的优先级。终端执行命令时，会依次查找 PATH 环境变量里列出的目录，谁排在前面谁说了算。
如果你同时装了 Homebrew 的 Ruby 和 rbenv 的 Ruby，而你的 shell 配置里没有正确设置顺序，那么ruby -v显示的是旧版本，gem install装的 gem 跑到了另一个目录，pod命令干脆找不到——这三大症状几乎解释了 90% 的安装疑难杂症。
所以，安装 CocoaPods 的第一步不是“安装”，而是“理清环境”。这是很多教程没有告知读者的隐藏前提。
2. 动手前的环境预检：十五分钟摸清你的 Ruby 现状
我建议在安装任何东西之前，先花一点时间做环境检查。这一步能让你后续少走很多弯路。下面这些命令我在每次配环境时都会跑一遍，已经形成肌肉记忆了。
2.1 确认 Xcode 命令行工具与 Homebrew
CocoaPods 本身依赖 Xcode 的命令行工具链，因为它在解析和编译依赖时需要一个可用的编译器环境。
xcode-select -p如果输出/Library/Developer/CommandLineTools或/Applications/Xcode.app/Contents/Developer，说明已经安装。如果提示找不到路径，先执行xcode-select --install完成安装。
还需要确认 Homebrew 是否就绪：
brew --version如果提示没有 Homebrew，先安装它。这一步是后续所有方案的基础。装的时候注意 Apple Silicon 芯片会使用/opt/homebrew目录，Intel 芯片则使用/usr/local，这会影响后续的路径配置。
2.2 查看当前 Shell 里生效的 Ruby 和 Gem
执行下面这条命令，看清楚你的终端当前指向的是哪套 Ruby：
which ruby ruby -v再看 gem：
which gem gem -v gem env home把输出结果对照一下：如果ruby -v显示 2.6.10，并且路径在/usr/bin/ruby，说明你的系统还在用内置 Ruby——这就是潜在的问题源头。
再检查 pod 是否存在：
which pod如果输出为空，说明 CocoaPods 还没有被装进当前 PATH 环境下，或者装到了其他 Ruby 的 bin 目录下。
2.3 镜像源：国内环境下避免卡死的关键
如果你身处网络受限环境，直接走官方源拉取 gem 可能会非常慢甚至超时。在开始安装之前，先把 gem 源切换成国内镜像。我用的是 Ruby China 的镜像，一直挺稳定。
gem sources --remove https://rubygems.org/ gem sources --add https://gems.ruby-china.com/ gem sources -l最后一条命令输出里如果只有https://gems.ruby-china.com/，说明切换成功。注意镜像源只影响 gem 包的下载，不影响 CocoaPods 的其他行为。
做完以上预检，你已经知道自己的环境大概处于什么状态。接下来进入正题：两条安装路线，任选其一。
3. 推荐路线：用 rbenv 管好 Ruby 版本，再装 CocoaPods
我个人的倾向非常明确：如果是新环境，或者准备长期做 iOS 开发，优先使用 rbenv。这和“权威与否”无关，纯粹是因为它最好用、最不容易出幺蛾子。
3.1 为什么是 rbenv 而不是 RVM 或者直接 Homebrew 装 Ruby？
RVM 也是个老牌工具，但它会在 shell 里注入很多环境函数，有时会和 macOS 的某些配置产生冲突。rbenv 的设计哲学是“轻量、只做版本切换这一件事”，它不接管 gem 的管理，不设置代理环境变量，只是在 PATH 最前面放一个 shim 层，让ruby、gem、pod这些命令自动路由到当前选定的 Ruby 版本上。
这套机制的好处是：你可以在多个 Ruby 版本之间来回切换，gem 包完全隔离。不会出现 A 项目需要用 Ruby 2.7、B 项目需要 3.3，两边的 gem 互相打架的情况。
3.2 安装 rbenv 并初始化
用 Homebrew 安装 rbenv 和 ruby-build 插件。ruby-build 负责从源码编译 Ruby，算是一个必备组件。
brew install rbenv ruby-build然后把 rbenv 的初始化配置写入你的 shell 配置文件。Sonoma 默认使用 zsh，所以配置文件是~/.zshrc。如果你以前改成了 bash，就是~/.bash_profile。
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc echo 'eval "$(rbenv init -)"' >> ~/.zshrc source ~/.zshrc验证是否生效：
rbenv -v3.3 安装一个较新的 Ruby 版本
先看有哪些版本可以装：
rbenv install --list选一个最新的稳定版，比如 3.3.x 系列。我这个阶段一般会选 3.3.5 或更新的版本。执行安装：
rbenv install 3.3.5这一步会从源码编译 Ruby，时间取决于你机器的性能，大概五到十几分钟不等。期间你会看到大量编译日志，不要紧张，这是正常现象。
装完以后设置全局默认版本：
rbenv global 3.3.5紧接着验证：
ruby -v看到输出ruby 3.3.5并且which ruby指向/Users/你的用户名/.rbenv/shims/ruby，说明你已经成功切换到了 rbenv 管理的 Ruby 环境。
此时用gem -v确认 gem 可用，再运行一次gem sources -l确认镜像源设置没有丢，然后就可以进入安装 CocoaPods 的环节了。
3.4 安装 CocoaPods 并验证
在 rbenv 环境下安装 gem 是不需要 sudo 的，因为你拥有这个 Ruby 环境的完全控制权：
gem install --no-document cocoapods加--no-document是为了跳过 RDoc 和 RI 文档生成，能省不少时间。安装完成后执行：
rbenv rehash pod --version如果输出一个版本号，比如1.16.2，恭喜你，核心安装已经完成。接下来还有一步可选但推荐的操作：初始化 CocoaPods 的 Spec 仓库。
pod setuppod setup会下载 CocoaPods 的索引仓库。这一步在网络环境下可能需要较长时间，国内网络尤其考验耐心。如果你使用了 CDN 版本，默认的pod repo update会以增量方式运行，体验会好很多。
3.5 在项目里使用 rbenv Ruby 时的注意点
如果你用 rbenv，在项目里运行pod install时，要确保你已经在项目目录下并且当前全局/局部 Ruby 是预期版本。可以在项目根目录放一个.ruby-version文件，写入你想要的版本号，rbenv 会自动切换到这个版本，这个机制比手动反复切换要省心太多。
我经历过的坑是：rbenv 只对当前用户生效。如果你从终端之外的工具（比如某些 CI 脚本、GUI 工具）执行 pod，它不一定走 rbenv 的 shim。真遇到这种场景，最简单的方式是在执行 pod 之前用rbenv which pod查出 pod 的完整路径，然后直接指定绝对路径调用。
4. 备用路线：直接用 Homebrew 装 Ruby 和 CocoaPods
如果你不想再多装一个 rbenv，或者只是临时需要跑一下项目，那 Homebrew 直装也是可行的。它的维护成本略高于 rbenv，但比系统 Ruby 强得多。
4.1 安装 Homebrew 版 Ruby
直接执行：
brew install ruby装完以后，Homebrew 会提示你它没有被符号链接到标准路径，需要手动把路径加进 PATH。以 Apple Silicon 芯片为例，正确的路径是/opt/homebrew/opt/ruby/bin。Intel 芯片则是/usr/local/opt/ruby/bin。
执行：
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc source ~/.zshrc然后验证：
which ruby ruby -v看到输出为 Homebrew 的 Ruby 路径且版本为 3.x，就说明 PATH 生效了。
4.2 在 Homebrew Ruby 下安装 CocoaPods
同样无需 sudo：
gem install --no-document cocoapods执行pod --version验证。
有一个容易被人忽略的点：Homebrew 的 Ruby 安装 gem 时，可执行文件会被放进/opt/homebrew/lib/ruby/gems/3.x.x/bin，这个目录不一定在你的 PATH 里。如果pod --version提示找不到命令，你需要把 gem 的 bin 目录也加进 PATH。先用gem env home查看 gem 目录，再把对应的 bin 路径追加到~/.zshrc。
4.3 两条路线的对比
我自己两种方式都用过，各有优劣。整理一个对比表格方便你做决定：
| 对比项 | rbenv 方案 | Homebrew 方案 |
|---|---|---|
| 环境隔离度 | 高，多版本共存互不干扰 | 中，全局只有一套 3.x |
| 安装复杂度 | 需要编译 Ruby，耗时稍长 | 直接下载二进制，快 |
| 命令路径管理 | rbenv shim 自动处理 | 需手动配置 PATH 和 gem bin 目录 |
| 多项目版本需求 | 完美支持 | 难以切换，只能迁就最高版本 |
| 与系统 Ruby 冲突几率 | 低 | 中等，如果不配置 PATH 会迷路 |
| 长期维护成本 | 低 | 中等，需要自己注意路径一致性 |
如果你只是偶尔用一次 CocoaPods，Homebrew 方案足够。如果你预期未来会频繁处理多个 iOS 项目，rbenv 方案的长期收益明显更高。
5. Ruby 版本冲突的完整排查链路：从一条报错回溯到源头
就算你按照上面的步骤走，也不能保证一次成功。这一节是我个人认为本篇最有价值的部分——当遇到版本冲突时，我们应该怎么一步步排查，而不是病急乱投医。
5.1 四种最常见的报错长相
我把 Sonoma 下安装 CocoaPods 的出问题场景归纳成四种。
场景一：Gem::FilePermissionError
You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory.这就是最典型的系统 Ruby 权限报错，常见于直接用系统内置 Ruby 执行gem install。网上搜到的很多建议是让你加sudo，我前面说过不建议这么做。正确做法是切换到一个用户可控的 Ruby 环境（rbenv 或 Homebrew）。
场景二：command not found: pod
你明明执行了gem install cocoapods且没有报错，但新的 shell 里pod却找不到。原因是 pod 可执行文件的安装路径不在 PATH 环境变量里。如果你用了 rbenv，多半是忘了rbenv rehash；如果用了 Homebrew，就是 gem bin 目录没加入 PATH。
场景三：activesupport requires Ruby version >= 3.0之类的 gem 依赖版本错误
安装在系统 Ruby 2.6.10 上时容易遇到。某些 gem 的新版本已经放弃了对 Ruby 2.6 的支持，当你尝试安装或更新 CocoaPods 依赖时就会报错。这正契合了“Ruby 版本冲突”的标题——旧版本 Ruby 无法承载新版本依赖。
场景四：LoadError - cannot load such file -- cocoapods
这种往往出现在你安装了多个 Ruby，gem 的加载路径串了的情况下。可能你当前使用的是 rbenv 的 Ruby，但全局环境变量GEM_HOME或GEM_PATH还被设置成 Homebrew 的路径，导致 Ruby 找不到对应的 gem。
5.2 一次真实的定位过程
假设你刚执行完gem install cocoapods成功，但随后运行pod --version报错，错误信息指向 Ruby 版本太低。我们按链路排查。
第一步，确认你自己想用的是哪套 Ruby：
which ruby which gem如果 which 显示的路径不一致，比如ruby指向/usr/bin/ruby，而gem指向/opt/homebrew/bin/gem，那你这套环境从根上就是分裂的。你需要做的是：通过修改 PATH 让which ruby和which gem指向同一套 Ruby，然后再继续。
第二步，查看 gem 的安装目录：
gem env home确认这个路径和ruby -e 'puts Gem.user_dir'输出的用户目录是否有冲突。有些开发者会在~/.zshrc里手动设置GEM_HOME环境变量，这会强制 gem 安装到指定目录。如果这个目录和你当前的 Ruby 不匹配，就会出现装了但加载不到的问题。处理方式很简单：把~/.zshrc里手动设置的GEM_HOME、GEM_PATH注释掉，让 gem 跟着 Ruby 走。
第三步，查看当前 Ruby 的全局 gem 列表：
gem list cocoapods如果你能看到 cocoapods 的相关条目，说明 gem 确实装了，问题只出在路径或加载逻辑上；如果看不到，那说明你装到的 Ruby 和当前用的不是同一个，属于环境分裂问题。
第四步，清理所有可能干扰的环境变量：
env | grep -i ruby env | grep -i gem把输出贴到编辑器里研究一下，凡是与 rbenv、gem 路径相关的配置，都要和你的实际环境对应上。
5.3 关键诊断命令速查表
为了让你排查时不用翻聊天记录，我把最常用的几条命令整理成表：
| 目的 | 命令 |
|---|---|
| 查看 Ruby 路径 | which ruby |
| 查看 Ruby 版本 | ruby -v |
| 查看 gem 路径 | which gem |
| 查看 gem 环境目录 | gem env home |
| 查看 gem 全局列表 | gem list |
| 查看已装 pod 路径 | which pod |
| 查找 pod 实际路径 | rbenv which pod |
| 查看 PATH 中的 Ruby 活动路径 | echo $PATH |
| 查看 Ruby/Gem 相关环境变量 | env | grep -i ruby或env | grep -i gem |
排查逻辑的核心只有一个：确保 ruby、gem、pod 三者的路径指向同一套环境。只要这一点成立，80% 的版本冲突问题都不复存在。
6. 从旧版本系统升级到 Sonoma 后，存量 CocoaPods 怎么抢救
如果你不是新 Mac，而是从 Ventura 或更早版本升级上来的，恭喜你进入了一个更刺激的场景：曾经好用的 pod 命令，升级之后突然“消失”了。
6.1 为什么升级完 pod 就没了
最根本的原因在于，旧版本 macOS 下很多人是用sudo gem install cocoapods把 CocoaPods 装进了系统 Ruby 的 gem 目录/Library/Ruby/Gems/2.6.0。升级到 Sonoma 之后，系统文件的完整性和权限可能发生变化，曾经安装的 gem 文件会丢失，或者因为 SIP 的严格限制导致相关目录不再可写，gem 命令也找不到原有的安装记录。
另一个次常见的原因是，升级过程中你的~/.zshrc配置受到了影响。比如某些 PATH 导出语句因为兼容性问题被注释或丢失，导致 Homebrew 的 Ruby 或 rbenv 不再被正确加载，pod 自然也就不见了。
6.2 存量项目迁移的行动步骤
第一步，重新按本文第二章节做一次环境预检，确定当前系统里哪个 Ruby 是可用的。
第二步，建议直接安装 rbenv 并管理 Ruby 版本，不要试图组织救援旧环境。因为旧环境的 gem 依赖大概率已经脆弱到无法维护，重建一个干净环境成本反而更低。
第三步，在新 Ruby 环境下执行：
gem install --no-document cocoapods rbenv rehash第四步，把全局 Ruby 版本固定下来，并确认pod --version能正常输出版本号。
第五步，进到你的项目目录，执行：
pod install注意：你应该运行pod install，而不是pod update。前者会按照 Podfile.lock 里锁定的版本恢复依赖，不会引发大规模版本升级；后者会把所有依赖更新到新版本，很可能带来兼容性问题。迁移期间求稳是第一原则。
6.3 迁移后的验证要点
pod install成功后，会有几件事值得确认：
- 项目目录下生成了
Pods文件夹和Podfile.lock文件，且锁文件的格式正常。 - 打开
xcworkspace而不是.xcodeproj进行开发，CocoaPods 管理下的项目必须用 workspace 文件。 - 如果你用了自定义的 pod 源（比如某些公司内部私有源），在
~/.cocoapods/repos下的索引可能也需要重新拉取。执行pod repo list查看当前存在哪些仓库源，必要时重新添加。
迁移环境的本质是重新建立一个可靠的基础，然后把项目拉起来。很多人因为想保住旧的 gem 环境而不断打补丁，结果越打越乱。沉没成本不值得留念，推倒重来往往是最快的路。
从 Sonoma 的 Ruby 生态现状来看，CocoaPods 安装的难点早就不是 CocoaPods 自身，而是你对 Ruby 环境的掌控程度。如果你能把 “系统 Ruby 不可信、不要用 sudo 装 gem、rbenv 或 Homebrew 二选一” 这三条原则记在心里，那么无论 macOS 怎么更新，CocoaPods 的安装对你来说都只是几分钟的事情。
