CocoaPods 使用指南

KnightSama 2016-05-10 iOS

CocoaPods 是常用的开发 iOS/macOS 程序的三方库依赖管理工具。通过 CocoaPods 我们可以定义自己的依赖关系，方便的对第三方库进行管理。

# 安装

CocoaPods 是用 Ruby 语言编写，安装 CocoaPods 前我们需要先安装 Ruby，在此之前请确保已经安装 Homebrew

MacOS 自带 Ruby 环境，但一般版本较低，我们可以通过 Ruby 版本管理工具来安装管理

# 使用 RVM 安装 Ruby

RVM 是开源的 Ruby 版本管理工具，可以管理多个 Ruby 版本并自由切换

# 安装 RVM

curl -L get.rvm.io | bash -s stable

# 指定源

source ~/.bashrc
source ~/.bash_profile

1
2

# 查看 RVM 版本

rvm -v

# 列出 Ruby 可安装版本信息

rvm list known

# 安装需要安装的版本

rvm install 2.6.0

# 设置为默认版本

rvm use 2.6.0 --default

# 更换 gem 源

gem 默认的源国内无法连接，我们可以切换为镜像源

gem sources --remove https://rubygems.org/
gem sources --add https://gems.ruby-china.com/

1
2

更换完检查是否只有 ruby-china 一个源

gem sources -l

# 使用 rbenv 安装 Ruby

rbenv 与 RVM 一样也是常用的 Ruby 管理工具

# 安装 rbenv

我们可以直接使用 Homebrew 安装

brew install rbenv

# 在配置文件中初始化

如果用的 bash 脚本

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc

1
2

如果用的 zsh

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init -)"' >> ~/.zshrc

1
2

# 列出 Ruby 可安装版本信息

rbenv install --list

# 安装需要安装的版本

rbenv install 2.6.0

# 设置版本

# 设置全局版本
rbenv global 2.6.0
# 设置本地版本
rbenv local 2.6.0
# 设置当前终端版本
rbenv shell 2.6.0

1
2
3
4
5
6

注意

切换完版本后需要执行

rbenv rehash

# 开始安装 CocoaPods

安装完 Ruby 后我们就可以继续安装 CocoaPods

sudo gem install -n /usr/local/bin cocoapods

# 安装本地库

pod setup

# 设置仓库

git clone https://github.com/CocoaPods/Specs.git master --progress

如果速度太慢可以使用下面的镜像

git clone https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git  ~/.cocoapods/repos/trunk

# 最新版本的 CocoaPods 默认使用 CDN 了，我们可以在 Podfile 上添加

source 'https://cdn.cocoapods.org/'

至此我们的 CocoaPods 就安装完毕了

# 创建 Podfile

Podfile 是一个文件，它通过 Ruby 的语法来描述依赖关系，定义项目所需要的三方库。我们通过配置这个文件来将指定版本的三方库或我们自己创建的私有库引入到工程中来。

下面介绍了该文件的简单配置，更加详细的设置可以查看官方文档

# 添加平台

下面指定了平台是 iOS，版本是 11.0

platform :ios, '11.0'

# 通过 `Source` 指定依赖库的来源

如不写则是默认库，我们可以添加自己的私有库

source 'https://github.com/CocoaPods/Specs.git'

# 忽略引入库的所有警告

inhibit_all_warnings!

# 生成 framework 文件

导入 Swift 框架与动态库时需要添加

use_frameworks!

# 指定依赖项与版本号

最简单的依赖声明，依赖指定项目的最新版本

pod 'AFNetworking'

通过添加版本号来依赖指定的版本

pod 'AFNetworking', '1.0.0'

除了指定版本号，我们还可以通过下面的方式进行版本管理

版本号	描述
>0.1	高于 0.1 的任何版本
>=0.1	0.1 和高于 0.1 的任何版本
<0.1	低于 0.1 的任何版本
<=0.1	0.1 和低于 0.1 的任何版本
~>0.1.1	0.1.1 到 0.2 之间的最新版本，不包含 0.2

# 安装指定的模块

默认情况下会安装所有定义在 Podspec 里面的默认模块 (Subspec)。我们可以通过下面的方式安装指定子模块

# 安装 Attribute 模块
pod 'QueryKit/Attribute'

1
2

可以通过下面的方式指定集合安装

pod 'QueryKit', :subspecs => ['Attribute', 'QuerySet']

# 指定安装源

可以通过 :git 从指定的地址安装依赖项

pod 'AFNetworking', :git => 'https://github.com/AFNetworking/AFNetworking.git'

可以通过 :branch 指定分支

pod 'AFNetworking', :git => 'https://github.com/AFNetworking/AFNetworking.git', :branch => 'dev'

通过 :tag 指定某个 tag

pod 'AFNetworking', :git => 'https://github.com/AFNetworking/AFNetworking.git', :tag => '0.7.0'

注意

通过上面的方式安装必须确保 podspec 文件存在于仓库的根目录中

我们可以通过 :podspec 指定一个外部的 podspec 文件来引入一个不带 podspec 的库

pod 'AFNetworking', :podspec => 'https://example.com/AFNetworking.podspec'

可以通过 :path 来使用本地文件

pod 'AFNetworking', :path => '~/Documents/AFNetworking'

注意

通过本地文件的方式安装必须确保 podspec 文件也在这个文件夹中

# 给指定的 target 添加依赖

下面的例子中给名称为 Demo 的 target 添加依赖

target 'Demo' do
    pod 'AFNetworking'
end

1
2
3

注意

如果我们不显式指定 target，CocoaPods 会创建一个名称为 default 的隐式 target 和工程中第一个 target 相对应，此时只有工程中第一个 target 能够使用 Pods 依赖库

如果工程中有多个 target，并且存在重复的依赖项，例如 targetA 需要依赖 RxSwift、RxCocoa、SnapKit，targetB 需要依赖 RxSwift、RxCocoa、SwiftyJSON，其中 RxSwift、RxCocoa 是相同的依赖，则我们可以通过下面的三种方法来实现引入

# 这里的 abstract_pod 在实际 targets 中不存在，是虚拟的
abstract_target 'abstract_pod' do
    # 这里是公共的依赖项
    pod 'RxSwift'
    pod 'RxCocoa'
    # 不同的 target 单独配置不同的依赖项
    target 'targetA' do
        pod 'SnapKit'
    end
    
    target 'targetB' do
        pod 'SwiftyJSON'
    end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 循环引入公共依赖
targets = ['targetA','targetB']
targets.each do |t|
    target t do
        pod 'RxSwift'
        pod 'RxCocoa'
    end
end
# 不同的 target 单独配置不同的依赖项
target 'targetA' do
    pod 'SnapKit'
end
    
target 'targetB' do
    pod 'SwiftyJSON'
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 定义公共 pods
def commonPods
    pod 'RxSwift'
    pod 'RxCocoa'
end

# 不同的 target 单独配置不同的依赖项,同时引入公共 pods
target 'targetA' do
    commonPods
    pod 'SnapKit'
end
    
target 'targetB' do
    commonPods
    pod 'SwiftyJSON'
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 常用指令

# 搜索三方库

通过下面的指令我们可以搜索指定的三方库的信息

pod search AFNetworking

# 更新本地依赖库列表

下面的指令可以更新 Pods 的本地依赖库，如果依赖库不是最新的那么有些新添加的库就无法通过 pod search 搜索到

pod setup

# 安装依赖库

我们可以通过下面两种指令来安装依赖库

pod install
# 或者
pod update

1
2
3

pod install 会根据 Podfile 文件指定的内容去安装依赖库，如果存在 Podfile.lock 文件，则按该文件中指定的版本安装。这个方法有利于团队统一依赖库版本比较常用。
pod update 会根据 Podfile 文件对版本的描述获取最新依赖库的版本，如果 Podfile 中没有指定依赖库的安装版本则永远为最新版本，该指令会无视 Podfile.lock 文件。

# 其他重要文件

# Podfile.lock

第一次安装依赖库后 CocoaPods 会生成一个 Podfile.lock 文件，其中包含了当前项目中安装的依赖库的版本号，还包含了当前执行该命令的 CocoaPods 的版本号。当其他人通过 pod install 指令安装时会根据该文件中的版本号进行安装，有利于团队一致性。所以要把这个文件添加到版本管理中。

# Podspec

如果我们要制作自己的 CocosPod 库则需要创建该文件，这个文件描述了库的一些详细信息，其中具体的配置可以参阅官方文档

这里可以参照 AFNetworking 的配置

Pod::Spec.new do |s|
  s.name     = 'AFNetworking'
  s.version  = '4.0.1'
  s.license  = 'MIT'
  s.summary  = 'A delightful networking framework for Apple platforms.'
  s.homepage = 'https://github.com/AFNetworking/AFNetworking'
  s.social_media_url = 'https://twitter.com/AFNetworking'
  s.authors  = { 'Mattt Thompson' => 'm@mattt.me' }
  s.source   = { :git => 'https://github.com/AFNetworking/AFNetworking.git', :tag => s.version }


  s.ios.deployment_target = '9.0'
  s.osx.deployment_target = '10.10'
  s.watchos.deployment_target = '2.0'
  s.tvos.deployment_target = '9.0'

  s.ios.pod_target_xcconfig = { 'PRODUCT_BUNDLE_IDENTIFIER' => 'com.alamofire.AFNetworking' }
  s.osx.pod_target_xcconfig = { 'PRODUCT_BUNDLE_IDENTIFIER' => 'com.alamofire.AFNetworking' }
  s.watchos.pod_target_xcconfig = { 'PRODUCT_BUNDLE_IDENTIFIER' => 'com.alamofire.AFNetworking-watchOS' }
  s.tvos.pod_target_xcconfig = { 'PRODUCT_BUNDLE_IDENTIFIER' => 'com.alamofire.AFNetworking' }

  s.source_files = 'AFNetworking/AFNetworking.h'

  s.subspec 'Serialization' do |ss|
    ss.source_files = 'AFNetworking/AFURL{Request,Response}Serialization.{h,m}'
  end

  s.subspec 'Security' do |ss|
    ss.source_files = 'AFNetworking/AFSecurityPolicy.{h,m}'
  end

  s.subspec 'Reachability' do |ss|
    ss.ios.deployment_target = '9.0'
    ss.osx.deployment_target = '10.10'
    ss.tvos.deployment_target = '9.0'

    ss.source_files = 'AFNetworking/AFNetworkReachabilityManager.{h,m}'
  end

  s.subspec 'NSURLSession' do |ss|
    ss.dependency 'AFNetworking/Serialization'
    ss.ios.dependency 'AFNetworking/Reachability'
    ss.osx.dependency 'AFNetworking/Reachability'
    ss.tvos.dependency 'AFNetworking/Reachability'
    ss.dependency 'AFNetworking/Security'

    ss.source_files = 'AFNetworking/AF{URL,HTTP}SessionManager.{h,m}', 'AFNetworking/AFCompatibilityMacros.h'
  end

  s.subspec 'UIKit' do |ss|
    ss.ios.deployment_target = '9.0'
    ss.tvos.deployment_target = '9.0'
    ss.dependency 'AFNetworking/NSURLSession'

    ss.source_files = 'UIKit+AFNetworking'
  end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

下面是发现的关于 CocoaPods 的好文章

CocoaPods 历险记

KnightSama‘s Blog

Choose mode