CocoaPods 的安装、使用和常见问题

发表于 更新于 分类于 ， 阅读次数： Disqus： 本文字数： 2.2k 阅读时长 ≈ 8 分钟

二〇一五年的最后一天，我还在这里布道。自己都醉了。

一、介绍

CocoaPods 是 iOS 项目的依赖管理工具，该项目源码在 Github 上管理。开发 iOS 项目不可避免地要使用第三方开源库，CocoaPods 的出现使得我们可以节省设置和第三方开源库的时间。

在使用 CocoaPods 之前，开发项目需要用到第三方开源库的时候，我们需要：

  1. 把开源库的源代码复制到项目中
  2. 添加一些依赖框架和动态库
  3. 设置 -ObjC，-fno-objc-arc 等参数
  4. 管理他们的更新

在使用 CocoaPods 后，我们只需要把用到的开源库放到一个名为 Podfile 的文件中，然后执行 pod install。Cocoapods 就会自动将这些第三方开源库的源码下载下来，并且为我们的工程设置好相应的系统依赖和编译参数。

二、原理

CocoaPods 的原理是将所有的依赖库都放到另一个名为 Pods 的项目中，然后让主项目依赖 Pods 项目，这样，源码管理工作都从主项目移到了 Pods 项目中。Pods 项目最终会编译成一个名为 libPods.a 的文件，主项目只需要依赖这个 .a 文件即可。

三、安装

CocoaPods 可以方便地通过 Mac 自带的 RubyGems 安装。

  1. 先升级 gem

打开 Terminal（终端），输入以下命令：

1
sudo gem update --system

升级成功后会提示：

1
RubyGems system software updated
  1. 继续执行：
1
sudo gem install cocoapods
  1. 执行完这句如果报以下错误（没有请跳过）：
1
2
3
ERROR: Could not find a valid gem 'cocoapods' (>= 0)， here is why:
Unable to download data from https://rubygems.org/ - Errno::ETIMEDOUT: Operation timed out - connect(2) (https://rubygems.org/latest_specs.4.8.gz)
ERROR: Possible alternatives: cocoapods

这是因为 ruby 的软件源 https://rubygems.org 使用亚马逊的云服务，被我大天朝屏蔽了，需要更新一下 ruby 的源。依次执行以下命令行：

1
2
3
4
gem sources -l #查看当前 ruby 的源
gem sources --remove https://rubygems.org/
gem sources -a https://ruby.taobao.org/
gem sources -l
  1. 接下来进行安装，执行：
1
pod setup

Terminal 会停留在 Setting up CocoaPods master repo 这个状态一段时间，是因为要进行下载安装，而且目录比较大，需要耐心等待一下。如果想加快速度，可使用 CocoaPods 的镜像索引。（文章末尾附使用镜像索引的方法，点击跳转）

安装成功后，你会看到以下提示:

1
2
3
...

Setup completed

至此安装完成！

四、使用

进入 iOS 项目所在的目录（项目根目录）。

  1. 详细讲解版（老鸟请直接跳过）

执行命令：

1
touch Podfile

这句是说新建一个名为 Podfile 的文件（不能写成别的名字，也可以自己在工程根目录里面直接新建）。

然后对该文件进行编辑，执行命令：

1
open -e Podfile

第一次执行这个命令，会有一个空白文件打开，可以先放在一边。

Podfile 文件的格式应该类似以下：

1
2
3
4
5
platform :ios， '7.0'

pod 'AFNetworking'， '~> 2.6.3'
pod 'LCTabBarController'， '~> 1.2.2'
pod 'LCBannerView'

需要 注意 以下几点：

a. platform 那一行，ios 三个字母都要小写，而且与前面的冒号之间不能有间隔。
b. 后面的版本号也可以不写，但是有些开源库对版本是有要求的，比如要在 iOS 7.0 以上才能运行，遇到这样的开源库就需要写上版本号。
c. platform 下面就是 CocoaPods 需要集成的开源库，根据你的需要确定集成成些库。

  1. 老鸟版

执行命令：

1
vim Podfile
  1. 举个栗子 🌰：

我要集成 AFNetworking 这个库类，需要在 CocoaPods 里面先搜索是否有需要的库，在 Terminal 中输入：

1
pod search AFNetworking

回车之后就可以看到和你搜索的关键字相关的一些库类，如下图：

By Leo

其中第一个就是我们需要的，把 pod ‘AFNetworking’, ‘~>3.0.3’ 复制到我们的 Podfile 文件中，保存。

AFNetworking 2.x： pod ‘AFNetworking’, ‘~>2.6.3’

然后在 Terminal 中执行 ：

1
2
3
4
pod install

# 建议使用下一句命令，在天朝速度更快（不更新本地仓库）
pod install --verbose --no-repo-update

这样，AFNetworking 就已经下载完成并设置好了编译参数和依赖。

相关阅读：【iOS】使用 AFNetworking 如何设置 HTTP Header

以后使用的时候切记以下两点：

a. 从此以后需要使用 CocoaPods 生成的 *.xcworkspace 文件来打开工程，而不是使用以前的 *.xcodeproj 文件
b. 每次更改了 Podfile 文件，都需要执行一次 pod update 命令（建议使用 pod update --verbose --no-repo-update）

  1. pod install 与 pod update 的区别

当执行 pod install之后，除了 Podfile，还会生成一个名为 Podfile.lock 的文件，它会 锁定 当前各依赖库的版本，之后即使多次执行 pod install 也不会更改版本，只有执行 pod update 才会改变 Podfile.lock。在多人协作的时候，这样可以防止第三方库升级时候造成大家各自的第三方库版本不一致。所以在提交版本的时候不能把它落下，也不要添加到 .gitignore 中.

五、常见问题

  1. 升级 OS X 10.11 后，运行 pod 命令出现如下错误：
1
-bash: pod: command not found

解决方法：

1
sudo gem install -n /usr/local/bin cocoapods
  1. 错误： 
    1
    [!] Invalid Podfile file: undefined local variable or method 'en_US' for #<Pod::Podfile:0x00000102a5d8b0>. Updating CocoaPods might fix the issue.

原因：单引号格式，可能是手动输入导致

解决办法：前往 系统偏好设置 - 键盘 - 文本 - 将“使用智能引号和破折号”一项取消勾选 - 再将 Podfile 里面的单（双）引号修改一下

  1. 错误： 
    1
    ArgumentError - invalid byte sequence in US-ASCII

原因：字符集错误

解决办法：
使用 locale 命令查看当前的字符集，如果都是 zh，需要执行以下命令：

1
2
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

然后再使用 locale 命令查看，已经改过来了。

  1. 错误： 
    1
    2
    3
    4
    5
    6
    7
    [!] The YMTea [Debug] target overrides the OTHER_LDFLAGS build setting defined in 'Pods/Target Support Files/Pods/Pods.debug.xcconfig'. This can lead to problems with the CocoaPods installation
    Use the $(inherited) flag， or
    Remove the build settings from the target.
    [!] The YMTea [Release] target overrides the OTHER_LDFLAGS build setting defined in 'Pods/Target Support Files/Pods/Pods.release.xcconfig'. This can lead to problems with the CocoaPods installation

    - Use the '$(inherited)' flag， or
    - Remove the build settings from the target.

原因：我是在已有项目中集成 CocoaPods 的时候遇到这个问题。原因是项目 Target 中做了一些设置，CocoaPods 也做了默认的设置，如果两个设置结果不一致，就会造成问题。

解决方法：我想要使用 CocoaPods 中的设置，分别在我的项目中定义 PODS_ROOT 和 Other Linker Flags 的地方（build settings），拷贝输入值 $(inherited) ，进入终端，执行 pod update。警告没了，回到 Xcode，build 通过。

网上还流行另外一种简单粗暴的方法：点击项目文件 project.xcodeproj，右键显示包内容，用文本编辑器打开 project.pbxproj，删除 OTHER_LDFLAGS 的地方，保存。（这种我没试过，建议实在搞不定再尝试）

  1. 错误：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[!] Oh no， an error occurred.

It appears to have originated from your Podfile at line 2.

Search for existing GitHub issues similar to yours:
https://github.com/CocoaPods/CocoaPods/search?q=%2FUsers%2Fxiao6%2FMusic%2FGI06%E5%AE%9E%E8%AE%AD%E8%8A%B8%E8%8C%97%E8%8C%B6%E5%8F%B6%2FYMTea%2FPodfile%3A2%3A+syntax+error%2C+unexpected+%27%3A%27%2C+expecting+end-of-input%0Aplatform+%3A+ios%2C+%277.0%27%0A++++++++++%5E&type=Issues

If none exists， create a ticket， with the template displayed above， on:
https://github.com/CocoaPods/CocoaPods/issues/new

Be sure to first read the contributing guide for details on how to properly submit a ticket:
https://github.com/CocoaPods/CocoaPods/blob/master/CONTRIBUTING.md

Don't forget to anonymize any private data!

原因：这个问题比较蛋疼，弄了好久，仔细看发现就是因为 Podfile 文件里面 platform 那一行，冒号和 ios 之间多了一个空格。。。。

解决方法：删掉 Podfile 文件里面 platform 那一行冒号和 ios 之间的空格即可。

附：如何使用镜像索引

⬆️ 返回安装步骤

所有项目的 podspec 文件都托管在 https://github.com/CocoaPods/Specs，第一次执行 pod setup 时，CocoaPods 会将这些 podspec 索引文件更新到本地的 ~/.cocoapods 目录下，这个索引文件比较大，所以第一次更新时非常慢。友好人士在国内的服务器建立了 CocoaPods 索引库的镜像，所以执行索引跟新操作时候会快很多。具体操作方法如下:

1
2
3
pod repo remove master
pod repo add master https://gitcafe.com/akuandev/Specs.git
pod repo update

这是使用 GitCafe 上的镜像，将以上代码中的 https://gitcafe.com/akuandev/Specs.git 替换成 http://git.oschina.net/akuandev/Specs.git 即可使用 OSChina 上的镜像。

原文来自简书：CocoaPods的安装使用和常见问题 ——By CoderAO，略有修改。

以上

你好，二〇一六。

联系与捐赠

  • Mail: echo bGVvZGF4aWFAZ21haWwuY29tCg== | base64 -D
  • GitHub: iTofu