1. Sonoma下安装CocoaPods为什么总是翻车1.1 系统自带Ruby的那个坑2024年把Mac升级到Sonoma之后很多iOS开发者做的第一件事就是打开终端敲下那句看了无数遍的命令gem install cocoapods然后下一秒就被红色报错糊了一脸ERROR: While executing gem ... (Gem::FilePermissionError) You dont have write permissions for the /Library/Ruby/Gems/2.6.0 directory.这不是你操作失误而是Sonoma系统下安装CocoaPods最典型的宿命。原因是macOS Sonoma自带的是Ruby 2.6.10版而系统为了保护核心文件把/usr/bin/ruby、/Library/Ruby/Gems这些目录统统划进了系统保护区域。普通用户没有写权限默认也不建议你硬用sudo去破解——因为一旦你sudo gem install cocoapods就会往系统Ruby目录里塞一堆依赖看起来装上了但下次系统升级可能直接给你重置掉甚至你更新系统后碰到权限冲突整个Gem环境直接坏掉。所以Sonoma下装CocoaPods的根本问题不是你敲错了命令而是你在用系统Ruby做不该由它做的事。1.2 Ruby版本冲突到底冲突在哪社区里常说的Ruby版本冲突本质上有三层意思第一层是系统Ruby版本太老。CocoaPods官方文档写的支持区间是Ruby 2.6但2024年最新版的CocoaPods1.15.x在安装依赖时很多gem的最新版本已经慢慢开始要求Ruby 2.7或更高系统自带的2.6.10虽然旧但未必报错却会经常遇到某些依赖的编译问题——因为新版activesupport等gem在Ruby 2.6下面已经不属于官方重点测试范围了。第二层是PATH路径错乱。很多人之前可能用Homebrew装过Ruby或者装过RVM导致系统里同时存在好几个Ruby环境。当你执行ruby -v时看到的是3.x但gem install装到的却是另一个路径下的gems然后pod命令找不到或者找到了又加载了旧版本的库报一堆dyld: Library not loaded之类的错。第三层是权限与配置互相纠缠。系统Ruby被SIP保护Homebrew的Ruby在/usr/local/opt/ruby或/opt/homebrew/opt/ruby如果你混着用gem的安装路径、环境变量、PATH顺序全都会打架。解决思路很清晰不要碰系统Ruby自己装一个用户级别的Ruby并且让这个Ruby成为当前shell里的唯一默认环境。这件事rbenv做得比RVM干净得多。2. 安装前的环境检查先把家底摸清楚2.1 确认系统版本和芯片类型动手之前先花一分钟看清自己的环境。在终端里依次执行sw_vers uname -m第一条命令会显示系统版本比如14.5之类的确认是Sonoma系列就行。第二条命令输出arm64说明是M1/M2/M3芯片的Apple Silicon机器输出x86_64说明是Intel芯片的老机器。这个信息很重要因为后续Homebrew的安装路径不一样Apple Silicon机器的Homebrew装在/opt/homebrewIntel机器装在/usr/local。很多报错其实都是因为自己手动改PATH时写错路径导致的。2.2 检查Ruby、Homebrew、CommandLineTools三件套接着检查以下几个内容ruby -v which ruby gem -v which gem brew -v xcode-select -p正常情况下你大概率会看到ruby是/usr/bin/ruby版本2.6.10gem是/usr/bin/gemHomebrew可能已经装好也可能提示command not foundxcode-select -p如果输出/Library/Developer/CommandLineTools或者/Applications/Xcode.app/Contents/Developer说明命令行工具没问题。如果没有装Homebrew先装。方法很简单官方一行命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这里多说一句国内网络环境下如果这条命令执行很慢可以把脚本下载后改国内镜像源再跑或者直接先配置Git的代理镜像。整体上Homebrew安装到机器没有坑最辛苦的是后面brew install rbenv时如果遇到网络问题可以在下面第3节里用我给出的镜像方案解决。如果xcode-select -p报错先执行xcode-select --install弹出的窗口点安装装完再检查。这一步不做后面rbenv install编译Ruby时百分之百会失败因为需要一个能用的C编译器clang。2.3 验证一个关键点当前Gem目录归属有时候你之前折腾过机器里已经有多个Ruby了。这时执行gem env home如果输出是/Library/Ruby/Gems/2.6.0说明gem还在系统目录下后面需要彻底切换到新环境。如果输出的是~/.rbenv/versions/xxx/lib/ruby/gems/...说明你可能之前装过rbenv那就直接跳到第3节检查版本即可。这一步建议认真看因为很多报错看起来是CocoaPods的问题实际上是你把gem装到了一个自己都不知道是哪里的目录。3. 用rbenv管理Ruby版本一劳永逸的核心方案3.1 为什么选rbenv而不是RVM很多老教程会推荐RVM但我的建议是新项目一律用rbenv。RVM的机制是替换shell函数会在你cd进目录时自动切换Ruby版本还能管理gemset功能强大但对新手来说太重了而且它会在~/.rvm下维护一大堆逻辑一旦和系统Ruby混用PATH环境变量很容易乱。rbenv的机制则很朴素它只是把~/.rbenv/shims目录放到PATH最前面这个目录里放了一堆代理程序shims当你输入ruby、gem、pod时实际执行的是shims里的软链脚本由rbenv根据你当前设定的版本把真正执行权交给~/.rbenv/versions/version/bin/下的对应程序。一句话总结rbenv做的唯一一件事就是管理PATH干净、透明、好排查。3.2 安装rbenv和ruby-build用Homebrew安装是最省事的方式brew update brew install rbenv ruby-buildruby-build是rbenv的插件负责从源码编译Ruby各版本。安装完成后执行rbenv -v能输出版本号就说明装好了。这里有个国内用户很容易踩的坑后续执行rbenv install 3.2.2时ruby-build会先从GitHub下载Ruby源码包网络差的时候会卡在Downloading ruby-3.2.2.tar.gz...这一步。解决办法是给ruby-build设置一个镜像环境变量export RUBY_BUILD_MIRROR_URLhttps://mirrors.ustc.edu.cn/ruby-build/然后再执行install命令下载速度完全不一样。这个变量只在当前终端有效如果之后要多次安装建议把它写进~/.zshrc。3.3 配置zsh环境变量最容易遗忘的一步如果你是macOS默认的zsh安装完rbenv后需要手动把初始化代码加进~/.zshrc。官方推荐的是这三行echo export PATH$HOME/.rbenv/bin:$PATH ~/.zshrc echo if command -v rbenv /dev/null; then eval $(rbenv init -); fi ~/.zshrc source ~/.zshrc第一行把rbenv的命令路径加进PATH第二行让当前shell初始化rbenv的shims第三行让配置立即生效。很多人装完rbenv后直接rbenv install报command not found或者装完Ruby后gem还是指向系统Ruby百分之九十都是因为这一步没做或者做完了没开新终端。要验证配置是否成功执行which rbenv如果输出~/.rbenv/bin/rbenv或者/opt/homebrew/bin/rbenv就OK了。3.4 安装指定版本的Ruby推荐3.2.x先看一下有哪些版本可以装rbenv install -l列表会很长建议装3.2.2或3.2.3。这个版本经过2024年大量iOS项目的验证和最新版CocoaPods兼容性最好。不建议一上来就追最新3.3.x虽然理论上没问题但有些老项目里的gem原生扩展在3.3上编译容易遇到小毛病犯不着给自己添堵。执行安装rbenv install 3.2.2这条命令会花几分钟因为是从源码编译期间你可能会看到刷屏的编译日志耐心等就行。如果过程中有BUILD FAILED的提示多半是缺少CommandLineTools或者网络问题回到第2.2节检查一下。装完后设置全局默认版本rbenv global 3.2.2这一步会生成一个~/.rbenv/version文件内容就是3.2.2告诉rbenv以后所有shell默认都用这个版本。然后执行ruby -v which ruby正常情况下ruby -v会显示ruby 3.2.2which ruby会指向~/.rbenv/shims/ruby。看到这个结果环境就对了。3.5 性能提效gem源换不换一句话说清Ruby的gem源默认是https://rubygems.org/国内访问速度不稳定。建议换成清华的镜像源gem sources --remove https://rubygems.org/ gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/执行完用gem sources -l确认源列表里只剩一个https://mirrors.tuna.tsinghua.edu.cn/rubygems/就行。这一步不影响后续任何操作只是让gem install从下载到结束快很多。4. 安装CocoaPods从命令行到第一个项目4.1 正式安装不需要sudo现在Ruby环境已经切到rbenv管理的3.2.2了直接执行gem install cocoapods注意这次前面不需要加sudo。因为rbenv把gems装到了~/.rbenv/versions/3.2.2/lib/ruby/gems/用户目录下的写入权限完全没问题。安装过程中会拉取一堆依赖gem包括activesupport、xcodeproj、cocoapods-core、cocoapods-downloader等等如果换过源的话一两分钟就能装完。如果卡在某个原生扩展的编译上八成是CommandLineTools的问题回到第2.2节。装完以后执行验证pod --version能看到版本号比如1.15.2就说明CocoaPods装好了。如果提示command not found:pod别慌执行一下rbenv rehashrehash的作用是让rbenv重新扫描所有已安装gem的可执行文件在shims目录里生成对应的代理命令。每次你通过gem安装或卸载了任何自带命令行的gem都习惯性执行一次就不会错。4.2 多个Ruby版本之间切换的坑有些老项目可能要求Ruby 2.7或3.0如果你用rbenv切到了另一个版本比如rbenv global 3.0.2那这个shell里的pod可能又找不到了。这是正常的因为每个Ruby版本下的gems是独立的你在3.2.2里装的CocoaPods3.0.2里当然没有。处理办法有两种切到对应版本后重新gem install cocoapods或者在项目目录里建一个.ruby-version文件写上3.2.2rbenv会在你进入这个目录时自动切换版本我个人用后者最多因为iOS老项目如果带了.ruby-version文件团队协作时大家本地环境就能一致起来少踩很多奇怪的兼容性问题。4.3 验证并初始化一个测试项目为了确认CocoaPods真的能用不要省这一步。随便建个测试目录mkdir ~/pod-test cd ~/pod-test pod init执行完pod init后目录里会多出一个Podfile。打开看一眼内容默认是给iOS平台准备的# Uncomment the next line to define a global platform for your project # platform :ios, 11.0然后执行pod install这一步如果你没有在Podfile里写任何依赖实际会很快完成并生成Podfile.lock。看到类似Pod installation complete! There are 0 dependencies from the Podfile and 0 total pods installed.就说明整个链路是通的。以后你只需要把真正的第三方库写进Podfile执行pod install就会拉取依赖并生成.xcworkspace文件记得打开工程时用.xcworkspace而不是.xcodeprojCocoaPods的依赖才会被正确引用。5. 常见错误与排错实录你踩过的坑我基本都踩过5.1 You dont have write permissions 经典权限报错现象ERROR: While executing gem ... (Gem::FilePermissionError) You dont have write permissions for the /Library/Ruby/Gems/2.6.0 directory.原因你还在用系统Rubygem要往系统目录写文件但没有权限。解决别试sudo gem install cocoapods这个命令确实能装成功但它会污染系统Ruby环境后续升级系统或安装其他Ruby相关工具时很容易出问题。正确做法是走第3节的rbenv方案。如果你已经装了rbenv但还报这个错看ruby -v是不是3.2.2which gem是不是~/.rbenv/shims/gem确认rbenv global 3.2.2生效后再试。5.2rbenv: version X.X.X is not installed版本没装上现象执行rbenv global 3.2.2报错说3.2.2不存在。原因安装过程失败了但你没注意到日志或者安装根本没开始。解决用rbenv versions查看当前已装的版本。如果列表里没有就重新执行rbenv install 3.2.2如果卡在下载就用第3.2节提到的RUBY_BUILD_MIRROR_URL环境变量走镜像。如果编译中途失败看日志里有没有failed to build gem native extension或clang: error之类字样有的话先装CommandLineTools。还有一种情况很隐蔽你执行rbenv install时用了sudo。rbenv不能配合sudo用因为sudo会把当前用户环境变量重置掉装出来的文件归属也会变成root用户后面各种奇怪权限问题都会冒出来。5.3pod: command not found装完却找不到命令现象gem install一切正常但执行pod --version提示找不到命令。原因可能性很多按顺序排查先检查rbenv rehash是否执行过which pod看看是不是指向~/.rbenv/shims/pod如果还是找不到gem list cocoapods看看gem是否真的存在如果gem存在但shim没有删掉~/.rbenv/shims下的pod再rehash一次往往能解决。解决rbenv rehash pod --version我遇到过最无语的情况是~/.zshrc里的PATH顺序不对导致系统在rbenv的shims之前找到了另一个版本的pod。查看一下echo $PATH确保~/.rbenv/shims在/usr/bin之前。5.4 卡在activesupport编译缺少命令行工具现象gem install cocoapods时长时间卡在类似Building native extensions. This could take a while...然后报ERROR: Failed to build gem native extension.原因CocoaPods的依赖链里有activesupport等gem为了性能会编译原生扩展比如json gem的C扩展这个动作需要调用系统的clang编译器。如果没有Xcode CommandLineTools或者装了Xcode但路径不对就会失败。解决xcode-select --install装完后重新执行gem install cocoapods。如果已经装了Xcode但还是报错执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer手动指定开发者目录再次尝试。5.5 问题速查表报错现象根本原因推荐解法Gem::FilePermissionError使用了系统Ruby换rbenv安装3.2.x版本Rubyrbenv: version not installed版本未安装/安装失败rbenv install 3.2.2必要时配镜像pod: command not foundshims未生成或PATH顺序错误rbenv rehash检查PATHFailed to build gem native extension缺少CommandLineToolsxcode-select --installdyld: Library not loaded多个Ruby环境路径污染重装rbenv并清理~/.zshrc中的多余Ruby配置下载Ruby源码卡死网络问题设置RUBY_BUILD_MIRROR_URL为国内镜像gem install下载很慢gem源网络不稳定换清华gem源见第3.5节6. Sonoma下的几个额外小提醒6.1 新系统上Terminal的权限弹窗Sonoma对终端app的权限提示比之前更严格第一次在终端里访问~/Desktop、~/Documents、~/Downloads这些目录时会弹授权窗口点允许就行。这个和CocoaPods本身没关系但如果你的项目放在桌面上pod install时偶发找不到路径先去系统设置里给终端加上完全磁盘访问权限就能根治。6.2 不要为了省事直接改系统Ruby我见过很多人用sudo gem install cocoapods -n /usr/local/bin这种方式把pod命令塞到/usr/local/bin绕过权限限制。短期看能用但系统升级时一旦Ruby版本被刷新这些gem就会变成孤儿文件甚至因为Gem环境不一致pod初始化时反复崩溃。我的建议是既然已经深入到了安装工具的层面就一次把环境理顺rbenv方案的成本其实只有十几分钟。6.3 每次新开终端后确认环境如果你配置好了rbenv但换了个终端窗口ruby -v又回到2.6.10了那一定是~/.zshrc没刷新或者没写对。新开终端会自动加载~/.zshrc正常不该出现这种情况。如果出现检查cat ~/.zshrc | grep rbenv看看那三行初始化代码是不是真的在。如果之前用的是bash后来切到了zsh之前写入~/.bash_profile的配置不会对zsh生效需要同步写一份。6.4 团队协作时把Ruby版本固定下来最后分享一个我自己的习惯如果项目团队不只你一个人我强烈建议在仓库根目录创建.ruby-version文件内容写3.2.2。这样所有成员一旦用rbenv进入目录后就会自动切到相同版本CocoaPods的lock文件、原生扩展的编译行为都会更统一省掉我本地能跑你本地为啥不行的口水战。这块我在实际项目中试过团队里有人用3.0.2有人用3.2.2最后发现某人本地安装某依赖时出现了只有新版Ruby才有的编译问题而老版Ruby又因为某个API废弃而报warning。统一版本后沟通成本立刻降了下来。
Sonoma下CocoaPods安装失败？用rbenv管理Ruby环境一劳永逸
1. Sonoma下安装CocoaPods为什么总是翻车1.1 系统自带Ruby的那个坑2024年把Mac升级到Sonoma之后很多iOS开发者做的第一件事就是打开终端敲下那句看了无数遍的命令gem install cocoapods然后下一秒就被红色报错糊了一脸ERROR: While executing gem ... (Gem::FilePermissionError) You dont have write permissions for the /Library/Ruby/Gems/2.6.0 directory.这不是你操作失误而是Sonoma系统下安装CocoaPods最典型的宿命。原因是macOS Sonoma自带的是Ruby 2.6.10版而系统为了保护核心文件把/usr/bin/ruby、/Library/Ruby/Gems这些目录统统划进了系统保护区域。普通用户没有写权限默认也不建议你硬用sudo去破解——因为一旦你sudo gem install cocoapods就会往系统Ruby目录里塞一堆依赖看起来装上了但下次系统升级可能直接给你重置掉甚至你更新系统后碰到权限冲突整个Gem环境直接坏掉。所以Sonoma下装CocoaPods的根本问题不是你敲错了命令而是你在用系统Ruby做不该由它做的事。1.2 Ruby版本冲突到底冲突在哪社区里常说的Ruby版本冲突本质上有三层意思第一层是系统Ruby版本太老。CocoaPods官方文档写的支持区间是Ruby 2.6但2024年最新版的CocoaPods1.15.x在安装依赖时很多gem的最新版本已经慢慢开始要求Ruby 2.7或更高系统自带的2.6.10虽然旧但未必报错却会经常遇到某些依赖的编译问题——因为新版activesupport等gem在Ruby 2.6下面已经不属于官方重点测试范围了。第二层是PATH路径错乱。很多人之前可能用Homebrew装过Ruby或者装过RVM导致系统里同时存在好几个Ruby环境。当你执行ruby -v时看到的是3.x但gem install装到的却是另一个路径下的gems然后pod命令找不到或者找到了又加载了旧版本的库报一堆dyld: Library not loaded之类的错。第三层是权限与配置互相纠缠。系统Ruby被SIP保护Homebrew的Ruby在/usr/local/opt/ruby或/opt/homebrew/opt/ruby如果你混着用gem的安装路径、环境变量、PATH顺序全都会打架。解决思路很清晰不要碰系统Ruby自己装一个用户级别的Ruby并且让这个Ruby成为当前shell里的唯一默认环境。这件事rbenv做得比RVM干净得多。2. 安装前的环境检查先把家底摸清楚2.1 确认系统版本和芯片类型动手之前先花一分钟看清自己的环境。在终端里依次执行sw_vers uname -m第一条命令会显示系统版本比如14.5之类的确认是Sonoma系列就行。第二条命令输出arm64说明是M1/M2/M3芯片的Apple Silicon机器输出x86_64说明是Intel芯片的老机器。这个信息很重要因为后续Homebrew的安装路径不一样Apple Silicon机器的Homebrew装在/opt/homebrewIntel机器装在/usr/local。很多报错其实都是因为自己手动改PATH时写错路径导致的。2.2 检查Ruby、Homebrew、CommandLineTools三件套接着检查以下几个内容ruby -v which ruby gem -v which gem brew -v xcode-select -p正常情况下你大概率会看到ruby是/usr/bin/ruby版本2.6.10gem是/usr/bin/gemHomebrew可能已经装好也可能提示command not foundxcode-select -p如果输出/Library/Developer/CommandLineTools或者/Applications/Xcode.app/Contents/Developer说明命令行工具没问题。如果没有装Homebrew先装。方法很简单官方一行命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这里多说一句国内网络环境下如果这条命令执行很慢可以把脚本下载后改国内镜像源再跑或者直接先配置Git的代理镜像。整体上Homebrew安装到机器没有坑最辛苦的是后面brew install rbenv时如果遇到网络问题可以在下面第3节里用我给出的镜像方案解决。如果xcode-select -p报错先执行xcode-select --install弹出的窗口点安装装完再检查。这一步不做后面rbenv install编译Ruby时百分之百会失败因为需要一个能用的C编译器clang。2.3 验证一个关键点当前Gem目录归属有时候你之前折腾过机器里已经有多个Ruby了。这时执行gem env home如果输出是/Library/Ruby/Gems/2.6.0说明gem还在系统目录下后面需要彻底切换到新环境。如果输出的是~/.rbenv/versions/xxx/lib/ruby/gems/...说明你可能之前装过rbenv那就直接跳到第3节检查版本即可。这一步建议认真看因为很多报错看起来是CocoaPods的问题实际上是你把gem装到了一个自己都不知道是哪里的目录。3. 用rbenv管理Ruby版本一劳永逸的核心方案3.1 为什么选rbenv而不是RVM很多老教程会推荐RVM但我的建议是新项目一律用rbenv。RVM的机制是替换shell函数会在你cd进目录时自动切换Ruby版本还能管理gemset功能强大但对新手来说太重了而且它会在~/.rvm下维护一大堆逻辑一旦和系统Ruby混用PATH环境变量很容易乱。rbenv的机制则很朴素它只是把~/.rbenv/shims目录放到PATH最前面这个目录里放了一堆代理程序shims当你输入ruby、gem、pod时实际执行的是shims里的软链脚本由rbenv根据你当前设定的版本把真正执行权交给~/.rbenv/versions/version/bin/下的对应程序。一句话总结rbenv做的唯一一件事就是管理PATH干净、透明、好排查。3.2 安装rbenv和ruby-build用Homebrew安装是最省事的方式brew update brew install rbenv ruby-buildruby-build是rbenv的插件负责从源码编译Ruby各版本。安装完成后执行rbenv -v能输出版本号就说明装好了。这里有个国内用户很容易踩的坑后续执行rbenv install 3.2.2时ruby-build会先从GitHub下载Ruby源码包网络差的时候会卡在Downloading ruby-3.2.2.tar.gz...这一步。解决办法是给ruby-build设置一个镜像环境变量export RUBY_BUILD_MIRROR_URLhttps://mirrors.ustc.edu.cn/ruby-build/然后再执行install命令下载速度完全不一样。这个变量只在当前终端有效如果之后要多次安装建议把它写进~/.zshrc。3.3 配置zsh环境变量最容易遗忘的一步如果你是macOS默认的zsh安装完rbenv后需要手动把初始化代码加进~/.zshrc。官方推荐的是这三行echo export PATH$HOME/.rbenv/bin:$PATH ~/.zshrc echo if command -v rbenv /dev/null; then eval $(rbenv init -); fi ~/.zshrc source ~/.zshrc第一行把rbenv的命令路径加进PATH第二行让当前shell初始化rbenv的shims第三行让配置立即生效。很多人装完rbenv后直接rbenv install报command not found或者装完Ruby后gem还是指向系统Ruby百分之九十都是因为这一步没做或者做完了没开新终端。要验证配置是否成功执行which rbenv如果输出~/.rbenv/bin/rbenv或者/opt/homebrew/bin/rbenv就OK了。3.4 安装指定版本的Ruby推荐3.2.x先看一下有哪些版本可以装rbenv install -l列表会很长建议装3.2.2或3.2.3。这个版本经过2024年大量iOS项目的验证和最新版CocoaPods兼容性最好。不建议一上来就追最新3.3.x虽然理论上没问题但有些老项目里的gem原生扩展在3.3上编译容易遇到小毛病犯不着给自己添堵。执行安装rbenv install 3.2.2这条命令会花几分钟因为是从源码编译期间你可能会看到刷屏的编译日志耐心等就行。如果过程中有BUILD FAILED的提示多半是缺少CommandLineTools或者网络问题回到第2.2节检查一下。装完后设置全局默认版本rbenv global 3.2.2这一步会生成一个~/.rbenv/version文件内容就是3.2.2告诉rbenv以后所有shell默认都用这个版本。然后执行ruby -v which ruby正常情况下ruby -v会显示ruby 3.2.2which ruby会指向~/.rbenv/shims/ruby。看到这个结果环境就对了。3.5 性能提效gem源换不换一句话说清Ruby的gem源默认是https://rubygems.org/国内访问速度不稳定。建议换成清华的镜像源gem sources --remove https://rubygems.org/ gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/执行完用gem sources -l确认源列表里只剩一个https://mirrors.tuna.tsinghua.edu.cn/rubygems/就行。这一步不影响后续任何操作只是让gem install从下载到结束快很多。4. 安装CocoaPods从命令行到第一个项目4.1 正式安装不需要sudo现在Ruby环境已经切到rbenv管理的3.2.2了直接执行gem install cocoapods注意这次前面不需要加sudo。因为rbenv把gems装到了~/.rbenv/versions/3.2.2/lib/ruby/gems/用户目录下的写入权限完全没问题。安装过程中会拉取一堆依赖gem包括activesupport、xcodeproj、cocoapods-core、cocoapods-downloader等等如果换过源的话一两分钟就能装完。如果卡在某个原生扩展的编译上八成是CommandLineTools的问题回到第2.2节。装完以后执行验证pod --version能看到版本号比如1.15.2就说明CocoaPods装好了。如果提示command not found:pod别慌执行一下rbenv rehashrehash的作用是让rbenv重新扫描所有已安装gem的可执行文件在shims目录里生成对应的代理命令。每次你通过gem安装或卸载了任何自带命令行的gem都习惯性执行一次就不会错。4.2 多个Ruby版本之间切换的坑有些老项目可能要求Ruby 2.7或3.0如果你用rbenv切到了另一个版本比如rbenv global 3.0.2那这个shell里的pod可能又找不到了。这是正常的因为每个Ruby版本下的gems是独立的你在3.2.2里装的CocoaPods3.0.2里当然没有。处理办法有两种切到对应版本后重新gem install cocoapods或者在项目目录里建一个.ruby-version文件写上3.2.2rbenv会在你进入这个目录时自动切换版本我个人用后者最多因为iOS老项目如果带了.ruby-version文件团队协作时大家本地环境就能一致起来少踩很多奇怪的兼容性问题。4.3 验证并初始化一个测试项目为了确认CocoaPods真的能用不要省这一步。随便建个测试目录mkdir ~/pod-test cd ~/pod-test pod init执行完pod init后目录里会多出一个Podfile。打开看一眼内容默认是给iOS平台准备的# Uncomment the next line to define a global platform for your project # platform :ios, 11.0然后执行pod install这一步如果你没有在Podfile里写任何依赖实际会很快完成并生成Podfile.lock。看到类似Pod installation complete! There are 0 dependencies from the Podfile and 0 total pods installed.就说明整个链路是通的。以后你只需要把真正的第三方库写进Podfile执行pod install就会拉取依赖并生成.xcworkspace文件记得打开工程时用.xcworkspace而不是.xcodeprojCocoaPods的依赖才会被正确引用。5. 常见错误与排错实录你踩过的坑我基本都踩过5.1 You dont have write permissions 经典权限报错现象ERROR: While executing gem ... (Gem::FilePermissionError) You dont have write permissions for the /Library/Ruby/Gems/2.6.0 directory.原因你还在用系统Rubygem要往系统目录写文件但没有权限。解决别试sudo gem install cocoapods这个命令确实能装成功但它会污染系统Ruby环境后续升级系统或安装其他Ruby相关工具时很容易出问题。正确做法是走第3节的rbenv方案。如果你已经装了rbenv但还报这个错看ruby -v是不是3.2.2which gem是不是~/.rbenv/shims/gem确认rbenv global 3.2.2生效后再试。5.2rbenv: version X.X.X is not installed版本没装上现象执行rbenv global 3.2.2报错说3.2.2不存在。原因安装过程失败了但你没注意到日志或者安装根本没开始。解决用rbenv versions查看当前已装的版本。如果列表里没有就重新执行rbenv install 3.2.2如果卡在下载就用第3.2节提到的RUBY_BUILD_MIRROR_URL环境变量走镜像。如果编译中途失败看日志里有没有failed to build gem native extension或clang: error之类字样有的话先装CommandLineTools。还有一种情况很隐蔽你执行rbenv install时用了sudo。rbenv不能配合sudo用因为sudo会把当前用户环境变量重置掉装出来的文件归属也会变成root用户后面各种奇怪权限问题都会冒出来。5.3pod: command not found装完却找不到命令现象gem install一切正常但执行pod --version提示找不到命令。原因可能性很多按顺序排查先检查rbenv rehash是否执行过which pod看看是不是指向~/.rbenv/shims/pod如果还是找不到gem list cocoapods看看gem是否真的存在如果gem存在但shim没有删掉~/.rbenv/shims下的pod再rehash一次往往能解决。解决rbenv rehash pod --version我遇到过最无语的情况是~/.zshrc里的PATH顺序不对导致系统在rbenv的shims之前找到了另一个版本的pod。查看一下echo $PATH确保~/.rbenv/shims在/usr/bin之前。5.4 卡在activesupport编译缺少命令行工具现象gem install cocoapods时长时间卡在类似Building native extensions. This could take a while...然后报ERROR: Failed to build gem native extension.原因CocoaPods的依赖链里有activesupport等gem为了性能会编译原生扩展比如json gem的C扩展这个动作需要调用系统的clang编译器。如果没有Xcode CommandLineTools或者装了Xcode但路径不对就会失败。解决xcode-select --install装完后重新执行gem install cocoapods。如果已经装了Xcode但还是报错执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer手动指定开发者目录再次尝试。5.5 问题速查表报错现象根本原因推荐解法Gem::FilePermissionError使用了系统Ruby换rbenv安装3.2.x版本Rubyrbenv: version not installed版本未安装/安装失败rbenv install 3.2.2必要时配镜像pod: command not foundshims未生成或PATH顺序错误rbenv rehash检查PATHFailed to build gem native extension缺少CommandLineToolsxcode-select --installdyld: Library not loaded多个Ruby环境路径污染重装rbenv并清理~/.zshrc中的多余Ruby配置下载Ruby源码卡死网络问题设置RUBY_BUILD_MIRROR_URL为国内镜像gem install下载很慢gem源网络不稳定换清华gem源见第3.5节6. Sonoma下的几个额外小提醒6.1 新系统上Terminal的权限弹窗Sonoma对终端app的权限提示比之前更严格第一次在终端里访问~/Desktop、~/Documents、~/Downloads这些目录时会弹授权窗口点允许就行。这个和CocoaPods本身没关系但如果你的项目放在桌面上pod install时偶发找不到路径先去系统设置里给终端加上完全磁盘访问权限就能根治。6.2 不要为了省事直接改系统Ruby我见过很多人用sudo gem install cocoapods -n /usr/local/bin这种方式把pod命令塞到/usr/local/bin绕过权限限制。短期看能用但系统升级时一旦Ruby版本被刷新这些gem就会变成孤儿文件甚至因为Gem环境不一致pod初始化时反复崩溃。我的建议是既然已经深入到了安装工具的层面就一次把环境理顺rbenv方案的成本其实只有十几分钟。6.3 每次新开终端后确认环境如果你配置好了rbenv但换了个终端窗口ruby -v又回到2.6.10了那一定是~/.zshrc没刷新或者没写对。新开终端会自动加载~/.zshrc正常不该出现这种情况。如果出现检查cat ~/.zshrc | grep rbenv看看那三行初始化代码是不是真的在。如果之前用的是bash后来切到了zsh之前写入~/.bash_profile的配置不会对zsh生效需要同步写一份。6.4 团队协作时把Ruby版本固定下来最后分享一个我自己的习惯如果项目团队不只你一个人我强烈建议在仓库根目录创建.ruby-version文件内容写3.2.2。这样所有成员一旦用rbenv进入目录后就会自动切到相同版本CocoaPods的lock文件、原生扩展的编译行为都会更统一省掉我本地能跑你本地为啥不行的口水战。这块我在实际项目中试过团队里有人用3.0.2有人用3.2.2最后发现某人本地安装某依赖时出现了只有新版Ruby才有的编译问题而老版Ruby又因为某个API废弃而报warning。统一版本后沟通成本立刻降了下来。
