在iOS开发中，CocoaPods几乎是第三方库管理的事实标准。然而很多开发者在执行pod install时，常常会碰到类似activesupport requires Ruby version >= 2.2.2或者You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory的报错。这类问题表面上是依赖版本冲突，归根结底是Ruby运行环境和gem安装路径没有正确配置。下面就从版本检查、环境隔离、权限修复几个角度，把这一套问题彻底理清。
定位Ruby版本冲突：系统Ruby与CocoaPods的兼容性
macOS系统自带Ruby，但系统Ruby的版本通常比较老，而且Apple不鼓励在系统Ruby上安装gem包。从Mojave开始，macOS自带的Ruby版本是2.6.x，而较新的CocoaPods以及其依赖的activesupport、concurrent-ruby等gem会要求更高版本的Ruby（比如2.7或3.x）。这就是为什么运行pod install时经常出现ERROR: Error installing cocoapods: The last version of activesupport (>= 5.0) to support your Ruby & RubyGems was 6.1.7.8. Try installing it with `gem install activesupport -v 6.1.7.8` and then running the current command again这样的提示。此时需要先确认当前生效的Ruby版本：
ruby -v # 输出类似 ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.x86_64-darwin21] which ruby # 如果输出 /usr/bin/ruby，说明使用的是系统Ruby gem env # 查看gem的安装路径、版本、配置
如果which ruby的结果是/usr/bin/ruby，而你又没有安装其他版本管理器，那么几乎所有在系统Ruby上安装CocoaPods的尝试都会遇到权限或版本问题。解决思路是改用独立的Ruby版本管理工具，将Ruby安装到用户目录下，既避免权限问题，也能自由切换版本。
常见的Ruby版本管理工具有rbenv和RVM。以rbenv为例，先安装Homebrew，然后通过Homebrew安装rbenv和ruby-build。安装完成后需要配置shell环境变量，确保登录时自动加载rbenv。接下来安装一个较新的Ruby版本（比如3.2.2），并设置为全局默认：
# 安装rbenv brew install rbenv ruby-build # 初始化rbenv（将以下行加入 ~/.zshrc 或 ~/.bash_profile） echo 'eval "$(rbenv init -)"' >> ~/.zshrc source ~/.zshrc # 安装Ruby 3.2.2 rbenv install 3.2.2 rbenv global 3.2.2 # 验证 ruby -v # 应该显示 rbenv 管理的版本，路径类似 /Users/你的用户名/.rbenv/versions/3.2.2/bin/ruby
这样一来，gem的安装目录也会随之变为用户目录下的~/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0，不再需要sudo。许多版本冲突问题在切换到用户级Ruby后就会消失。
解决gem环境配置错误：权限、源与镜像
即便使用了rbenv或RVM，仍可能遇到gem安装失败的情况。最常见的是权限错误：You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory。这种情况通常是因为shell环境变量没有正确加载，导致gem命令仍然指向系统Ruby的gem。可以用which gem确认，如果路径不是~/.rbenv/shims/gem或类似的用户路径，就需要检查shell配置文件（比如.zshrc）中rbenv的初始化行是否在PATH设置之前。
另一个常见错误是gem源连接问题。默认的RubyGems源https://rubygems.org/在国内访问不稳定，容易导致安装超时或失败。可以切换到国内镜像源，例如https://gems.ruby-china.com：
# 移除默认源 gem sources --remove https://rubygems.org/ # 添加国内镜像 gem sources --add https://gems.ruby-china.com/ # 查看当前源 gem sources -l
如果切换源后仍然报证书错误或SSL问题，可能需要更新RubyGems版本。执行gem update --system可以升级RubyGems本身。不过要注意，更新系统RubyGems时尽量不要使用sudo，否则又会陷入权限泥潭。对于rbenv管理的Ruby，直接在用户目录下更新即可。
还有一种情况是gem缓存损坏导致安装失败。可以尝试清理gem缓存：gem cleanup，或者手动删除~/.gem目录下的缓存文件。如果某个具体gem安装失败，比如ffi、nokogiri等需要编译的扩展，需要检查Xcode命令行工具是否完整：xcode-select --install。
使用Bundler固定依赖版本，一劳永逸地避免冲突
即使解决了Ruby版本和gem权限问题，有时候CocoaPods本身的依赖升级仍可能引入新的不兼容。例如某个版本的CocoaPods依赖的json或nap在特定Ruby版本下无法编译。此时Bundler就是一个非常有效的工具：它能在项目范围内锁定gem版本，避免全局gem环境污染带来的意外冲突。
首先在系统上安装Bundler：gem install bundler。然后在你的iOS项目根目录（通常与Podfile同级）创建一个名为Gemfile的文件，内容指定CocoaPods的版本：
source "https://gems.ruby-china.com" gem "cocoapods", "1.12.1" gem "activesupport", "7.0.4"
接着在项目目录运行bundle install，它会根据Gemfile安装对应的gem版本，并生成Gemfile.lock锁文件。之后执行bundle exec pod install，Bundler会确保使用Gemfile中指定的CocoaPods版本，而不是全局安装的版本。这样做的好处是：即使全局升级了CocoaPods或RubyGems，项目内的依赖始终稳定，不会因为新版本引入破坏性变更。
Bundler还可以用来隔离不同项目对Ruby版本的要求。如果你在同一个机器上维护多个iOS项目，有的项目需要Ruby 2.7，有的需要3.0，配合rbenv的rbenv local指令可以在项目目录内指定Ruby版本，再配合Bundler的Gemfile，就能实现完全隔离的依赖环境。
需要注意的是，使用Bundler后，所有pod相关命令都应加上bundle exec前缀，例如bundle exec pod update。有些开发者会忘记这一点，导致明明Gemfile中指定了版本，但运行时仍然调用全局CocoaPods。可以创建一个shell别名（在.zshrc中加入alias pod="bundle exec pod"）来省去每次输入的前缀。
持久化配置与常见错误速查
为了避免以后每次打开终端都要重新设置环境变量，务必确认rbenv或RVM的初始化代码已经写入对应的shell配置文件。对于使用zsh的macOS用户，这通常是~/.zshrc；对于使用bash的用户，则是~/.bash_profile。修改后执行source ~/.zshrc使其立即生效。同时检查~/.gemrc文件，如果之前手动指定过gem安装路径，可能会与版本管理器冲突，建议删除或清空该文件。
下面列出一组常见的错误和快速排查方向：
- 报错：
ERROR: While executing gem ... (Gem::FilePermissionError)
原因：gem命令仍指向系统Ruby。
解决：运行which gem，确认路径在/Users/用户名/.rbenv/shims/下。 - 报错：
activesupport requires Ruby version >= 2.7.0
原因：Ruby版本过旧。
解决：用rbenv安装新版Ruby并设为全局默认。 - 报错：
Failed to connect to rubygems.org
原因：网络或gem源问题。
解决：切换到国内镜像源，如https://gems.ruby-china.com。 - 报错：
You don't have write permissions for the /usr/bin directory
原因：尝试用sudo安装但环境变量丢失。
解决：不要使用sudo，改用用户级Ruby管理工具。
通过以上几个步骤，绝大多数由Ruby版本冲突和gem环境配置错误导致的pod install失败都能得到解决。如果问题依旧，建议检查Xcode Command Line Tools是否与Ruby扩展编译兼容，或者尝试完全卸载CocoaPods及其依赖后重新安装。记住关键一点：永远优先使用用户目录下的Ruby和gem环境，避免使用系统Ruby安装任何开发工具。