macOS 安裝 CocoaPods 報錯 Gem::GemNotFoundException 解決方案

錯誤現象

Installing ri documentation for cocoapods-0.39.0
21 gems installed

$ pod setup
/Users/sibo/.rvm/rubies/ruby-2.0.0-p648/lib/ruby/site_ruby/2.0.0/rubygems.rb:250:in `find_spec_for_exe': can't find gem cocoapods (>= 0.a) (Gem::GemNotFoundException)
	from .../rubygems.rb:278:in `activate_bin_path'
	from /Users/sibo/.rvm/rubies/ruby-2.0.0-p648/bin/pod:22:in `<main>'

根本原因

Ruby 環境不一致：gem install 安裝到某個 Ruby 版本/ gemset，但 pod 命令調用的是另一個 Ruby 環境的可執行文件，導致找不到已安裝的 gem。

常見場景：

• RVM 切換了 Ruby 版本但未重新安裝 gem。
• 系統 Ruby (/usr/bin/ruby) vs RVM Ruby vs Homebrew Ruby 混用。
• sudo gem install 安裝到系統目錄，但用戶 PATH 優先指向 RVM 的 pod。

標準解決步驟

1. 完全卸載重裝 (最徹底)

# 1. 卸載所有 cocoapods 相關 gem
sudo gem uninstall cocoapods
sudo gem uninstall cocoapods-core
sudo gem uninstall cocoapods-deintegrate
sudo gem uninstall cocoapods-downloader
sudo gem uninstall cocoapods-plugins
sudo gem uninstall cocoapods-search
sudo gem uninstall cocoapods-stats
sudo gem uninstall cocoapods-trunk
sudo gem uninstall cocoapods-try
sudo gem uninstall xcodeproj
sudo gem uninstall molinillo
sudo gem uninstall nanaimo
sudo gem uninstall claide
sudo gem uninstall colored2
sudo gem uninstall escape
sudo gem uninstall fourflusher
sudo gem uninstall gh_inspector
sudo gem uninstall nap
sudo gem uninstall netrc
sudo gem uninstall atomos

# 2. 清理 gem 緩存
sudo gem cleanup

# 3. 重新安裝 (建議使用系統 Ruby 避免 RVM 坑)
sudo gem install cocoapods -n /usr/local/bin  # 指定安裝路徑在 PATH 中

# 4. 設置鏡像源 (國內必須)
gem sources --remove https://rubygems.org/
gem sources --add https://gems.ruby-china.com/
gem sources -l  # 驗證

# 5. 設置 Pod 源
pod repo remove master
pod repo add master https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git
# 或 CDN 源 (CocoaPods 1.10+)
# pod repo add trunk https://cdn.cocoapods.org/

2. RVM 環境專用修復

# 確認當前 Ruby
rvm current
ruby -v
which ruby
which gem

# 在當前 Ruby 下安裝
gem install cocoapods

# 確認 pod 路徑
which pod
# 應指向 ~/.rvm/rubies/ruby-x.x.x/bin/pod

# 如果不一致，重新加載 RVM
source ~/.rvm/scripts/rvm
rvm use ruby-x.x.x --default

3. 推薦：使用 Homebrew 安裝 (避開 Ruby/Gem 坑)

brew install cocoapods
# 自動處理依賴、路徑、更新，極其穩定
# 後續更新：brew upgrade cocoapods

• Homebrew 會安裝獨立的 Ruby 環境給 CocoaPods 使用，不污染系統/用戶 Ruby。
• M1/M2 Mac 完全支持。

驗證安裝

pod --version
# 輸出版本號即成功

pod setup
# 首次運行會克隆 Specs 索引 (可能較慢，耐心等待)
# 使用鏡像源會快很多

常見後續問題

總結

首選 Homebrew 安裝 (brew install cocoapods) 徹底避開 Ruby/Gem/RVM 環境地獄。若必須用 Gem，徹底卸載重裝並指定安裝路徑 (-n /usr/local/bin)，同時切換到國內鏡像源 (RubyGems + CocoaPods Specs)。