CocoaPods 幾乎是 iOS 開發的標配,但第一次安裝時踩到的坑往往比使用本身還多。這篇把安裝、提速、日常使用三個階段會遇到的問題整理成一份可照做的筆記。
官方文件給的安裝方式很簡單:
$ sudo gem install cocoapods
$ pod setup
但終端機卻直接抱怨 sudo 不可用:
sudo: /etc/sudoers is owned by uid 502, should be 0
sudo: no valid sudoers sources found, quitting
這個錯誤的意思是 /etc/sudoers 的擁有者被改成了非 root 的 uid 502,導致 sudo 認為設定檔不可信而拒絕運作。網路上能查到的修法是用「修復磁碟權限」把檔案所有者改回 root,但實務上比較乾脆的做法是乾脆切到 root 身分執行安裝,也就是 su。
切過去之後可能會發現根本沒有 root 帳號可用,這時候得先到系統設定裡啟用它。Apple 官方支援文件提供的路徑如下(OS X Lion 10.7 以後):
不同 macOS 版本的介面配置略有差異(我當時用的是 10.9,從第五步開始就和文件不完全一致),但大致照著找都能找到。設定完成後別忘了把所有鎖頭關回去。
取得 root 權限後執行:
gem install cocoapods
pod setup
這一步不用急,反應會偏慢。稍等片刻會吐出一大堆訊息,出現 Overwrite the executable? [yN] 時輸入 y 繼續即可。
裝好之後可以試著搜尋套件,例如找 JSON 解析庫:
pod search json
一樣會等一會兒才跑出結果,輸出大致如下:
-> AFJSONPRequestOperation (1.0.0)
AFNetworking Extension for the JSONP format.
pod 'AFJSONPRequestOperation', '~> 1.0.0'
-> AFJSONRPCClient (2.0.0)
A JSON-RPC client build on AFNetworking.
pod 'AFJSONRPCClient', '~> 2.0.0'
- Versions: 2.0.0, 1.0.0, 0.4.0, 0.3.1, 0.3.0 [master repo]
CocoaPods 慢是眾所皆知的老問題,成因很多。其中一個容易忽略的環節是 RubyGems 本身版本過舊。取得 root 權限後執行:
gem update --system
等到 RubyGems system software updated 出現為止。我升級之後速度改善相當明顯。
1. 初始化。在終端 cd 進專案根目錄後執行 pod init,CocoaPods 會自動產生一個 Podfile:
# Uncomment this line to define a global platform for your project
# platform :ios, "6.0"
target "CocoaPods" do
end
target "CocoaPodsTests" do
end
2. 編輯 Podfile。用 vim 或任何編輯器,在對應的 target 區塊內寫上要引入的套件與版本。
3. 安裝相依套件。執行 pod install,CocoaPods 會下載並整合指定的函式庫。
4. 開啟專案。下載完成後專案目錄會多出一個 .xcworkspace 檔。

此後一律用 xcworkspace 開啟,而不是原本的 xcodeproj,否則會找不到由 CocoaPods 掛上的相依設定。
5. 更新版本。修改 Podfile 中的套件或版本後,執行 pod update 即可套用。
另外常見需求是「如何移除已配置的函式庫與徹底刪除 CocoaPods」:前者把 Podfile 中對應行刪掉再跑一次 pod update;後者則需刪除 Pods 目錄、Podfile.lock 與專案中的相關 build 設定,再重開專案。