目录

1. 安装与更新
2. 项目初始化与配置
3. 核心安装与更新命令
4. 查看与管理 Pod
5. 高级与辅助命令
6. 常见问题与解决方案
7. 最佳实践

安装与更新

在使用 CocoaPods 之前，确保你的 Mac 上已安装 Homebrew，这是 macOS 下的包管理工具。

1 安装 CocoaPods

打开终端,运行以下命令：

sudo gem install cocoapods

• sudo: 以管理员权限执行。
• gem install cocoapods: 使用 Ruby 的 gem 包管理器来安装 CocoaPods。

2 更新 CocoaPods

如果需要将 CocoaPods 更新到最新版本：

sudo gem update cocoapods

3 升级到 CocoaPods 1.8+ (推荐)

从 1.8 版本开始，CocoaPods 引入了新的依赖解析引擎，速度更快,建议升级：

sudo gem install cocoapods-deintegrate cocoapods-clean-build-artifacts

在你的项目中运行 pod install,它会自动升级。

项目初始化与配置

1 初始化 Podfile

在你的 Xcode 项目根目录（.xcodeproj 文件所在的目录）下，运行以下命令来创建 Podfile 文件：

pod init

执行后，你的项目目录中会出现一个 Podfile 文件，你可以用任何文本编辑器打开它,来添加你需要的第三方库。

示例 Podfile:

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
target 'MyApp' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  # Pods for MyApp
  pod 'Alamofire', '~> 5.4' # Alamofire 版本大约为 5.4
  pod 'Kingfisher', '~> 7.0' # Kingfisher 版本大约为 7.0
  target 'MyAppTests' do
    inherit! :search_paths
    # Pods for testing
  end
  target 'MyAppUITests' do
    # Pods for UI testing
  end
end

2 首次安装依赖

在编辑好 Podfile 后，回到终端,在项目根目录下运行以下命令来安装所有依赖：

pod install

重要提示：

• 首次安装后，请务必使用 .xcworkspace 文件来打开你的项目，而不是 .xcodeproj 文件。.xcworkspace 文件已经集成了 CocoaPods 的项目。
• 之后每次修改 Podfile（添加、删除或更新 Pod），都需要重新运行 pod install。

核心安装与更新命令

1 pod install

• 作用：根据 Podfile 文件安装或更新所有依赖。
• 场景：
  • 首次添加第三方库后。
  • 修改了 Podfile 中的 Pod 版本或新增了 Pod。
  • 需要更新所有 Pod 到 Podfile 中指定的最新兼容版本。
• 特点：它会创建或更新 Podfile.lock 文件，锁定依赖版本，确保团队成员和 CI/CD 环境使用完全相同的依赖版本。

2 pod update

• 作用：更新 Podfile 中指定的 Pod（或所有 Pod）到 Podfile 中允许的最新版本。
• 场景：
  • 你想手动更新某个第三方库到新版本。
  • pod install 无法解决依赖冲突，想尝试让 CocoaPods 重新计算所有依赖的最新兼容版本。
• 重要区别：
  • pod install 会严格遵守 Podfile.lock 的版本。
  • pod update 会忽略 Podfile.lock，去寻找 Podfile 中指定的版本范围内的最新版本，并生成新的 Podfile.lock。

如何更新单个 Pod？

# 更新 Alamofire 到 Podfile 中允许的最新版本
pod update Alamofire
# 更新所有 Pod 到 Podfile 中允许的最新版本
pod update

查看与管理 Pod

1 pod search <Pod名称>

• 作用：在 CocoaPods 的仓库中搜索指定的库。
• 示例：

pod search Alamofire

• 注意：首次使用 pod search 时，它会更新本地的 spec 仓库，可能需要一些时间，如果搜索结果过时或为空,可以尝试清理本地缓存后重试。

2 pod list

• 作用：列出当前项目中已安装的所有 Pod 及其版本。
• 示例：

pod list

3 outdated

• 作用：检查当前安装的 Pod 是否有更新，它会显示当前安装的版本、Podfile.lock 中锁定的版本,以及可用的最新版本。
• 示例：

pod outdated

• 输出示例：

  - [!]  The following pods are outdated because they are dependent on the deprecated `podspec` format.
  - `AFNetworking` is currently at 3.2.1 (latest is 4.0.1)
  - `Kingfisher` is currently at 6.3.0 (latest is 7.0.0)

  这个列表告诉你哪些库可以更新，以及如何更新（通常是 pod update <Pod名称>）。

4 lib lint

• 作用：验证你创建的 .podspec 文件是否有效，如果你要发布自己的 Pod,这个命令非常有用。
• 示例：

pod lib lint MyLibrary.podspec --allow-warnings

高级与辅助命令

1 deintegrate

• 作用：从项目中移除 CocoaPods 的集成，但不会删除 Podfile 和 Podfile.lock，它会删除 Pods 目录、.xcworkspace 文件以及相关的 Pods.xcodeproj。
• 场景：当你想完全放弃使用 CocoaPods,或者需要重新开始集成时。
• 安装：如果命令不存在,需要先安装这个插件：

sudo gem install cocoapods-deintegrate

• 使用：

pod deintegrate

2 clean

• 作用：清理 Pods 目录和 Pods.xcodeproj，相当于删除所有依赖然后重新安装,这可以解决一些编译缓存问题。
• 场景：pod install 后遇到奇怪的编译错误，可以尝试 pod clean 然后再 pod install。
• 安装：

sudo gem install cocoapods-clean-build-artifacts

• 使用：

pod clean

3 repo

• 作用：管理 CocoaPods 的 spec 仓库。
• 常用子命令：
  • pod repo list: 查看本地的所有 spec 仓库。
  • pod repo update: 更新所有本地的 spec 仓库（包括主仓库 trunk）。
  • pod repo update <仓库名>: 只更新指定的 spec 仓库。
  • pod repo push <仓库名> <Pod名称>.podspec: 将你的 Pod 发布到指定的私有仓库。

常见问题与解决方案

1 pod install 失败，提示 [!] Unable to find a specification for ...

• 原因：
  1. 网络问题，无法连接到 CocoaPods 的服务器。
  2. 本地 spec 仓库缓存过旧，找不到新发布的 Pod。
  3. Pod 名称拼写错误。
• 解决方案：
  1. 检查网络连接。
  2. 尝试更新本地的 spec 仓库：pod repo update，如果太慢，可以只更新你需要的 Pod 的 spec：pod repo update trunk。
  3. 使用 pod search <Pod名称> 确认名称是否正确。

2 pod install 非常慢

• 原因：CocoaPods 需要从远程下载所有 Pod 的源码，并执行 pod install 命令来解析依赖关系,这个过程可能很耗时。
• 解决方案：
  1. 使用国内镜像源（见下文）。
  2. 确保你的项目路径是英文的,中文字符路径可能导致各种奇怪问题。
  3. 升级到 CocoaPods 1.8+ 的新引擎。

3 pod update 后出现大量无法解析的依赖冲突

• 原因：你更新的某个 Pod 引入了新的依赖，与项目中现有的 Pod 产生了版本冲突。
• 解决方案：
  1. 查看 pod install 或 pod update 的输出日志,它会告诉你哪些库发生了冲突。
  2. 回退到上一个能正常工作的 Podfile.lock 版本（使用 Git 等版本控制工具）。
  3. 仔细阅读冲突库的更新日志,看是否有兼容性说明。
  4. 在 Podfile 中为冲突的库指定明确的版本，pod 'SomeConflictingLib', '~> 1.5'。

4 如何使用国内镜像源加速？

由于网络原因，访问官方源可能很慢，可以切换到国内镜像源,如清华大学镜像源。

1. 临时使用（当前终端会话有效）：

   pod install --repo-update --no-repo-update

   这会跳过更新 spec 仓库的步骤,但有时仍会慢。

2. 永久使用（推荐）： 在终端执行：

   pod repo remove trunk
   pod repo add trunk https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git
   pod repo update trunk

   之后所有 pod 命令都会优先使用清华镜像源。

最佳实践

1. 版本控制：务必将 Podfile 和 Podfile.lock 文件都提交到 Git 版本控制系统中。Podfile.lock 是保证团队开发一致性的关键。
2. 使用 .xcworkspace：养成使用 YourProject.xcworkspace 的习惯，而不是 .xcodeproj。
3. 谨慎使用 pod update：在 CI/CD 流程中，通常使用 pod install 而不是 pod update，以保证环境的稳定性，只在需要主动升级依赖时才使用 pod update。
4. 明确版本号：在 Podfile 中，尽量使用 ~> x.y 这样的版本约束，而不是直接写 x.y.z 或留空，这给了 CocoaPods 一些灵活性，同时又能避免引入破坏性更新。pod 'Alamofire', '~> 5.4' 表示版本可以是 4.x，但不能是 0.0。
5. 保持 Podfile 简洁：只为当前 Target 添加必要的 Pod，避免将所有 Pod 都放在主 Target 中。

希望这份详细的指南能帮助你更好地使用 CocoaPods！