CocoaPods 是 iOS/Mac 開發中最主流的相依性管理工具。它可以幫你把第三方元件下載、擺到正確位置、設定好編譯參數,全部自動化。本文從環境建置一路寫到實戰,包含兩個常見使用場景。
沒有 CocoaPods 的年代,用第三方元件你得手動下載原始碼、拖進專案、設定 header search path、處理 framework 相依、更新時還要重新來一遍。CocoaPods 把這一切收斂成一個 Podfile 加上一行指令。
CocoaPods 本身是用 Ruby 寫的,因此必須先有 Ruby 環境。不建議在 Windows 上折騰,你需要的是:
強烈建議新手使用 Ubuntu,能省掉不少不必要的麻煩。
以下程式碼區塊中,以 $ 開頭的表示需要在終端機中執行(輸入時不含 $ 符號)。
# For Mac # 先安裝 Xcode 開發工具,它會順帶幫你裝好 Unix 環境需要的開發套件 # 然後安裝 Homebrew ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go/install)"
RVM(Ruby Version Manager)用來管理多個 Ruby 版本,這裡先裝起來,後面會用到。
$ curl -L https://get.rvm.io | bash -s stable
過程中可能會詢問 sudo 管理員密碼,並透過 Homebrew 自動安裝相依套件。等待一段時間後即完成。
接著載入 RVM 環境(若另開新的終端視窗則不必做這步,它會自動載入):
$ source ~/.rvm/scripts/rvm
確認安裝結果:
$ rvm -v rvm 1.22.17 (stable) by Wayne E. Seguin <wayneeseguin@gmail.com>, Michal Papis <mpapis@gmail.com> [https://rvm.io/]
$ rvm install 2.0.0
同樣需要等待下載與編譯。完成後,Ruby 與 RubyGems 就一併就緒了。
把指定版本設為系統預設:
$ rvm 2.0.0 --default
也可以換成其他版本號,前提是你已用 rvm install 裝過該版本。接著驗證:
$ ruby -v ruby 2.0.0p247 (2013-06-27 revision 41674) [x86_64-darwin13.0.0] $ gem -v 2.1.6 $ gem source -r https://rubygems.org/ $ gem source -a https://ruby.taobao.org
$ gem install rails $ rails -v Rails 3.2.13
這一步與 CocoaPods 無直接關係,但 Ruby 環境建立後通常也會順手裝上。
如果你的機器已經有可用的 Ruby 環境,安裝 CocoaPods 只需要一行:
sudo gem install cocoapods
但,且慢。 在部分網路環境下,執行這行指令後會發現老半天沒反應。原因無他——cocoapods.org 被那堵牆擋住了。
解法是改用鏡像來源。依序執行:
$ gem sources --remove https://rubygems.org/ // 等它有反應後再執行下一行 $ gem sources -a https://ruby.taobao.org/
驗證來源是否只剩鏡像:
$ gem sources -l
只有出現以下內容才算成功:
*** CURRENT SOURCES *** https://ruby.taobao.org/
完成後,終端畫面大致如下:

再次執行安裝指令:
$ sudo gem install cocoapods
等十幾秒,CocoaPods 就裝好了,不需要其他設定。

使用比安裝更簡單。以下用兩個實際場景說明。
AFNetworking 的 GitHub 位址:https://github.com/AFNetworking/AFNetworking
先確認它支援 CocoaPods:
$ pod search AFNetworking
幾秒後會列出相關資訊:

看來是支援的,那就開始吧。
1. 建立測試專案。 用 Xcode 開一個名為 CocoaPodsDemo 的專案。先截一張「尚未支援 CocoaPods」時的目錄結構,稍後對照:

2. 建立 Podfile。 CocoaPods 之所以知道要下載哪些元件,全靠這個檔案(檔名必須正好是 Podfile,沒有副檔名)。每個專案只需要一個 Podfile,並與 .xcodeproj 放在同一層目錄。
在終端進入專案目錄後建立它:
$ vim Podfile
填入內容:
platform :ios, '7.0' pod "AFNetworking", "~> 2.0"
這兩行不是憑空來的,可以在 AFNetworking 的 GitHub 頁面找到。意思是:支援 iOS 7.0 以上,要下載 2.0 系列。存檔退出(vim 下輸入 :wq)。
3. 安裝。
$ pod install
注意這行必須在專案目錄下執行。輸出大致如下:
Analyzing dependencies Downloading dependencies Installing AFNetworking (2.0.2) Generating Pods project Integrating client project [!] From now on use `CocoaPodsDemo.xcworkspace`.
最後一句話很重要:以後請用 CocoaPodsDemo.xcworkspace 開啟專案,而不是原本的 .xcodeproj。除了 workspace,你還會看到多出的 Podfile.lock 與 Pods 目錄。
打開 workspace 後,目錄結構變成:

AFNetworking 已經成功進來了。現在就可以直接:
#import <AFNetworking.h> // 或 #import "AFNetworking.h"
小結一下這個場景的兩個動作:先在專案裡建立描述需求的 Podfile,然後執行 pod install。至於 Podfile 該怎麼寫,通常元件的作者會在 README 裡直接告訴你。
新手常遇到的狀況:在 GitHub 找到一份符合需求的程式碼,興沖沖下載回來一編譯,滿屏錯誤,仔細一看全是找不到某某 header。這通常意味著專案使用了 CocoaPods,而你還沒把相依元件裝回來。
以 UAAppReviewManager 為例(一個能提醒使用者去 App Store 評分的元件)。下載後打開 Example 專案編譯,你會看到一堆找不到 header 的錯誤;同時也會發現 Example 目錄下有三個與 CocoaPods 相關的檔案/目錄:Podfile、Podfile.lock 與 Pods:

此時打開終端,進入與 Podfile 同一層的目錄,執行:
$ pod update
幾秒(視網路狀況可能十幾秒)後:
Analyzing dependencies Fetching podspec for `UAAppReviewManager` from `../` Downloading dependencies Installing UAAppReviewManager (0.1.6) Generating Pods project Integrating client project [!] From now on use `UAAppReviewManagerExample.xcworkspace`.
回到目錄會看到多了 UAAppReviewManagerExample.xcworkspace:

用它開啟專案並編譯執行,成功:

這裡有個容易困惑的細節:如果你剛才輸入的是 pod install 而不是 pod update,會看到類似這樣的錯誤:
[!] Required version (UAAppReviewManager (from `../`)) not found for `UAAppReviewManager`. Available versions: 0.1.6
原因是 Podfile.lock 已過期:pod install 會嚴格按照 lock 檔指定的版本安裝,若該版本已不存在於來源(例如本地元件升級了),就會失敗;而 pod update 會忽略 lock 檔的限制,重新解析並抓取最新可用版本。
實務上的判斷很簡單:
pod update 元件名稱 只更新單一套件。若拿不準,先試 pod install,失敗再改用 pod update 即可。
第一,Podfile.lock 必須進版控。它記錄了確切的元件版本與其相依關係,是團隊能跑出相同結果的關鍵;而 Pods/ 目錄通常不進版控。
第二,務必用 .xcworkspace 開專案。直接開 .xcodeproj 會因為少了 Pods target 而編譯失敗。
第三,若遇到 pod install 卡住不動,多半是 spec repo 更新過慢,可考慮改用 CDN 來源或先執行 pod repo update。
第四,較新的專案建議直接採用 Swift Package Manager 或較新版的 CocoaPods 整合方式;本篇的 Ruby/RVM 建置流程反映的是較早期環境,實際操作時請以目前官方文件為準。