CocoaPods 是專門管理 iOS 專案中第三方開源庫的工具,源碼託管在 GitHub 上,自 2011 年 8 月啟動以來一直維持活躍更新。
開發 iOS 專案幾乎不可能不用第三方庫,AFNetworking、ASIHttpRequest 等都是常見選擇。但傳統做法 requires 手動下載源碼、手動配置依賴,庫一升級還得再手動更新一遍,非常繁瑣。CocoaPods 的價值就在於把這些依賴統一管理,配置與更新只要幾行指令就能搞定。
macOS 已預裝 Ruby 環境。若不確定版本,可在終端機執行:
$ ruby -v

確認之後,一行指令即可完成安裝:
$ sudo gem install cocoapods
但實務上這行指令常常卡住沒有反應,原因是網路環境無法正常連線到 cocoapods.org。解法是改用國內鏡像。先檢查目前的 Ruby 來源:
$ gem sources -l
預設會看到:
*** CURRENT SOURCES *** https://rubygems.org/
這個來源在部分網路下是連不通的,需要換成可訪問的鏡像。刪除原來源:
$ gem sources --remove https://rubygems.org/
終端機應回覆:
https://rubygems.org/ removed from sources
再加入可用鏡像(此處以阿里雲鏡像為例):
$ gem sources -a https://rubygems-china.oss.aliyuncs.com
此時再執行 gem sources -l,列表中應該只剩阿里雲這一項。接著重新執行安裝指令:
$ sudo gem install cocoapods
一切順利時會看到安裝進度,最後出現:
3 gems installed
安裝完成後,用搜尋功能驗證是否可用:
$ pod search AFNetworking
有機會卡在 Setting up CocoaPods master repo 很久,然後拋出錯誤。

這代表 CocoaPods 尚未就緒,需要先更新 pod 並下載依賴:
$ pod setup
若稍後仍出現同樣的錯誤,通常是環境問題,可能原因有三:gem 版本過舊、無法連上 GitHub、或 .cocoapods 目錄下的設定有誤。逐一排除:
先更新 gem:
$ sudo gem update --system
再確認能否連通 GitHub:
$ ping github.com
然後檢查 repo 清單:
$ pod repo list
CocoaPods 會把資訊下載到 ~/.cocoapods,進入該目錄查看實際大小:
$ cd ~/.cocoapods $ du -sh *

若顯示 0 repos,說明確實沒有安裝成功。重新執行 pod setup,等到出現 setup completed 提示,再用 pod list 確認套件列表已載入。
最後再試一次搜尋,如果出現:
[!] Unable to find a pod with name, author, summary, or description matching `AFNetworking`
刪掉搜尋索引快取即可:
$ rm ~/Library/Caches/CocoaPods/search_index.json
之後再執行 pod search AFNetworking 就正常了。
切到專案目錄:
$ cd 專案路徑
建立 Podfile:
$ vim Podfile
按 i 進入插入模式後編輯。這裡要特別注意版本寫法——網路上大量流傳的舊寫法在新版 CocoaPods 下會直接報錯:
platform :ios, '8.1' pod 'AFNetworking', '~> 2.0'
它會提示 [!] The dependency `AFNetworking (~> 3.0)` is not used in any concrete target.。新版官方建議的寫法必須明確指定 target:
platform :ios, '8.0'
target '你的專案名稱' do
pod 'AFNetworking', '~> 3.0'
end
其中「你的專案名稱」就是 xx.xcodeproj 去掉副檔名後的 xx。
寫完按 esc,輸入 :wq 保存退出。此時專案目錄下會多出 Podfile,請注意它必須與 .xcodeproj 位於同一層目錄。
最後執行:
$ pod install
沒有報錯就完成了。之後開啟專案一律使用 .xcworkspace。