CocoaPods：从 0 到 1 的依赖管理调研笔记

本文目的：写给「只听过『pod install』，但根本不知道这玩意儿在干嘛」的 iOS 小白。读完你能：
用一句人话解释「包管理器」是个什么东西，为什么 iOS 离不开它；
看懂一个真实项目里的 Podfile / Podfile.lock / .xcworkspace 各自是干啥的；
自己从 0 搭一个新工程，把 Alamofire、SnapKit 这种知名第三方库装进去；
看懂 pod install 终端里刷过的几十行日志，背后到底发生了什么；
知道 CocoaPods 和 Swift Package Manager (SPM)、Carthage 的关系，不会一上来就被 3 个名字砸晕。

0. 先回答一个灵魂问题：什么是「包管理器」？

0.1 想象你要做一道「番茄炒蛋」

你打开冰箱，发现没番茄、没鸡蛋、没葱、没盐。摆在你面前的有两条路：

   方案 A：自己种 / 自己养                方案 B：去超市买
   ────────────────────                  ────────────────────
   ① 买地、播种番茄秧                       ① 推个购物车
   ② 养几只母鸡等下蛋                       ② 番茄、鸡蛋、葱、盐 → 全丢进车
   ③ 等 3 个月 ~ 1 年                      ③ 收银台扫码付款
   ④ 收获、清洗、然后才能炒                 ④ 回家炒菜
                                            
   时间：以年为单位                        时间：30 分钟
   质量：看天                              质量：明码标价、有保质期

正常人都选 方案 B —— 去超市。

为什么？因为 超市这个「中间平台」帮你做了三件事：

集中：上万种商品摆在一起，不用满世界找；
标准化：每件商品都有条形码、价格、保质期、产地；
流通：源源不断地补货、淘汰过期品。

📌 包管理器 ≈ 程序员的超市。 你要写 App，需要用别人写好的网络库、UI 库、加密库……包管理器就是把这些「代码商品」集中起来、贴好标签、随用随取的那个平台。

0.2 没有包管理器的世界有多惨

把时间倒回到 2010 年（CocoaPods 还没出生）。当时一个 iOS 程序员要用一个第三方库，比如 AFNetworking（现代 Alamofire 的爷爷），完整流程是：

   第 1 步：去 GitHub 找作者主页
   第 2 步：手动 git clone 或下 zip
   第 3 步：把代码文件一个个拖进 Xcode 工程
   第 4 步：手动配置 Header Search Paths
   第 5 步：手动加 -ObjC、-fno-objc-arc 等编译参数
   第 6 步：手动加系统依赖框架（SystemConfiguration、Security ...）
   第 7 步：编译报错 → 谷歌一下午 → 改配置 → 再编译
   第 8 步：作者发布新版，重新执行第 2~7 步
   第 9 步：你换台电脑开发，所有人重新踩一遍坑

而且，库 A 依赖库 B，库 B 依赖库 C，库 C 又依赖库 A 的某个旧版本 —— 这种「依赖地狱」靠人脑根本理不清。

📌 CocoaPods 解决的核心痛点：把上面 9 步 压缩成一行命令 pod install。

1. CocoaPods 到底是个什么东西？

1.1 三句话讲清楚

CocoaPods 是 iOS / macOS 圈子里最早、最流行、用得最广的 Objective-C / Swift 第三方库管理工具。它本身是用 Ruby 写的命令行程序。你给它一份「购物清单」（Podfile），它就帮你把所有需要的库下载好、配好、塞进 Xcode 工程。

1.2 CocoaPods 在外卖平台里的位置

如果把 iOS 开发比作一次外卖：

   ┌───────────────────────────────────────────────────────────────┐
   │                     iOS App 开发的厨房                          │
   ├───────────────────────────────────────────────────────────────┤
   │                                                                │
   │   👨‍🍳 你（iOS 开发者）                                          │
   │       │                                                        │
   │       │  下单：「我要 Alamofire 5.8 + SnapKit 5.7」              │
   │       ▼                                                        │
   │   ┌──────────────────────┐                                     │
   │   │   📋 Podfile          │  ← 购物清单（你手写）                 │
   │   └──────────┬───────────┘                                     │
   │              │  pod install                                    │
   │              ▼                                                 │
   │   ┌──────────────────────┐                                     │
   │   │  🛵 CocoaPods         │  ← 外卖小哥（Ruby 程序）              │
   │   │   去仓库取货 / 送货      │                                     │
   │   └──────────┬───────────┘                                     │
   │              │                                                 │
   │              ▼                                                 │
   │   ┌──────────────────────┐                                     │
   │   │  🏬 Specs Repo        │  ← 中央商品目录（在 GitHub 上）        │
   │   │  （记录每个库在哪、版本）  │                                     │
   │   └──────────┬───────────┘                                     │
   │              │                                                 │
   │              ▼                                                 │
   │   ┌──────────────────────┐                                     │
   │   │  📦 Pods/ 文件夹       │  ← 货送到家，整齐摆好                  │
   │   │  + .xcworkspace 文件  │     可以直接用                         │
   │   └──────────────────────┘                                     │
   │                                                                │
   └───────────────────────────────────────────────────────────────┘

外卖平台角色	CocoaPods 中对应的概念	它在干嘛
你下单的菜单	Podfile	你手写：我要哪些库、什么版本
餐厅老板写的菜品介绍	Podspec	库作者写：我这个库叫啥、依赖啥、源码在哪
平台里所有餐厅的总目录	Specs Repo	中央索引：所有 Podspec 的集合
外卖小哥	CocoaPods CLI（pod 命令）	真正干活的程序，下载 + 安装
送来的菜	Pods/ 文件夹	下载好的源码，已经塞进工程里
收据小票（精确到几点几分）	Podfile.lock	这次实际装的版本号，防止下次抓错

1.3 一句话总结

📌 Podfile 是你写的「我要买啥」，Podspec 是库作者写的「我卖的啥」，Specs Repo 是把所有 Podspec 摆在一起的货架，CocoaPods 命令行就是那个跑腿的小哥。

2. 五大核心概念详解

新手最容易在这 5 个概念上「字面懂、组合起来就晕」。我们一个个拆。

2.1 Pod —— 一个「商品」

「Pod」就是 一个第三方库 的代号。比如：

Alamofire 是一个 Pod（网络请求库）
SnapKit 是一个 Pod（自动布局库）
SDWebImage 是一个 Pod（图片加载库）

🎯 类比：超市里的一袋大米 = 一个 Pod。

2.2 Podfile —— 你的「购物清单」

放在工程根目录的一个 纯文本文件，名字就叫 Podfile（没扩展名）。一个最小的例子：

ruby

# Podfile
platform :ios, '14.0'                  # 我做的是 iOS App，最低支持 iOS 14
use_frameworks!                        # 用动态 framework 形式（后面讲）

target 'MyAwesomeApp' do               # 我的 App 叫 MyAwesomeApp
  pod 'Alamofire', '~> 5.8'            # 我要 Alamofire，5.8.x 任意版本
  pod 'SnapKit', '~> 5.7'              # 我要 SnapKit，5.7.x 任意版本
  pod 'SDWebImage'                     # 我要 SDWebImage，最新稳定版
end

🎯 类比：你写在小纸条上的「番茄 2 个、鸡蛋 6 个、葱 1 把、盐 1 包」，就是 Podfile。

⚠️ Podfile 是 Ruby 语法，但你不用会 Ruby —— 99% 的场景你只需要照抄上面这种 DSL 风格。

2.3 Podfile.lock —— 你的「订单小票」

第一次执行 pod install 后，CocoaPods 会自动生成一个 Podfile.lock，记录 这次实际装到的精确版本号：

PODS:
  - Alamofire (5.8.1)
  - SnapKit (5.7.1)
  - SDWebImage (5.18.10)
    - SDWebImage/Core (= 5.18.10)
  - SDWebImage/Core (5.18.10)

DEPENDENCIES:
  - Alamofire (~> 5.8)
  - SnapKit (~> 5.7)
  - SDWebImage

SPEC CHECKSUMS:
  Alamofire: f455c2c5cf...
  SnapKit:   d612e99e67...
  SDWebImage: a99e6cfa6f...

COCOAPODS: 1.15.2

🎯 类比：
Podfile 是你写的「番茄、鸡蛋、葱、盐」（模糊，鸡蛋哪个牌子无所谓）；
Podfile.lock 是收银小票「光明草鸡蛋 ¥18.90 × 1 / 古船面粉 ¥12.50 × 1」（精确，能查到具体哪批货）。

为什么需要 lock 文件？想象一个团队 5 个人：

   ❌ 没有 lock 文件的世界：
   小明 周一 跑了 pod install → 装到 Alamofire 5.8.0，能跑
   小红 周三 同一个 Podfile 跑 pod install → 装到 Alamofire 5.8.5（作者刚发新版，有 bug）→ 崩了
   两人代码一模一样，但行为不一样 → 排查到天荒地老

   ✅ 有 lock 文件的世界：
   小明跑完 → 提交 Podfile.lock 到 Git
   小红 git pull → 跑 pod install → CocoaPods 看到 lock 写着 5.8.0 → 也装 5.8.0
   两人环境完全一致 → 世界和平

📌 铁律：Podfile.lock 必须提交到 Git！ 不提交是新手最常犯的错误之一。

2.4 Podspec —— 商品的「说明书」

每一个 Pod 在它自己的代码仓库里，都有一个 XXX.podspec 文件，由库的作者写。看 Alamofire 的简化版：

ruby

# Alamofire.podspec
Pod::Spec.new do |s|
  s.name         = 'Alamofire'
  s.version      = '5.8.1'
  s.license      = 'MIT'
  s.summary      = 'Elegant HTTP Networking in Swift'
  s.homepage     = 'https://github.com/Alamofire/Alamofire'
  s.author       = { 'Alamofire Software Foundation' => 'info@alamofire.org' }
  s.source       = { :git => 'https://github.com/Alamofire/Alamofire.git', :tag => '5.8.1' }
  s.swift_versions = ['5.5', '5.6', '5.7', '5.8', '5.9']
  s.ios.deployment_target = '12.0'
  s.source_files = 'Source/**/*.swift'
  s.frameworks   = 'CFNetwork'
end

读法：

name / version：商品名 + 型号
source：源码在 GitHub 哪个 tag
source_files：哪些文件需要被编进来
frameworks：还要带上系统的什么框架
dependencies（这里没列出）：本商品依赖哪些其他 Pod

🎯 类比：超市货架上每袋大米背面那张「净含量 5kg / 产地东北 / 保质期 12 个月 / 配料：稻米」的标签 = 一个 Podspec。

2.5 Specs Repo —— 中央「商品目录」

CocoaPods 自己维护着一个超大的 GitHub 仓库：CocoaPods/Specs，里面存放着 几乎所有公开 Pod 的所有版本的 podspec 文件：

Specs/
└── Alamofire/
    ├── 5.8.0/Alamofire.podspec.json
    ├── 5.8.1/Alamofire.podspec.json
    └── 5.9.0/Alamofire.podspec.json
└── SnapKit/
    ├── 5.6.0/SnapKit.podspec.json
    ├── 5.7.0/SnapKit.podspec.json
    └── ...

第一次安装 CocoaPods，它会把整个 Specs Repo 下到本地（路径在 ~/.cocoapods/repos/），所以第一次特别慢（仓库 1G+）。

🎯 类比：超市每天更新一次的商品总目录册（厚厚一本电话簿），告诉你「光明牛奶今天上货 200 箱、价格 ¥58/箱」。

2.6 .xcworkspace —— Xcode 的「套餐」

执行 pod install 之后，工程目录下会多出一个 MyAwesomeApp.xcworkspace 文件。之后你必须用它打开 Xcode，不能再用 .xcodeproj 了。

   .xcodeproj    = 一份单点菜（只有你的 App 工程）
   .xcworkspace  = 一份套餐（你的 App 工程 + 所有 Pods 工程）

为什么？因为 CocoaPods 把所有第三方库 统一放到一个叫 Pods 的 Xcode 工程里，再用 workspace 把「你的工程」和「Pods 工程」绑在一起编译：

   MyAwesomeApp.xcworkspace
   ├── MyAwesomeApp.xcodeproj    （你的代码）
   └── Pods.xcodeproj            （所有第三方库）
       ├── Alamofire
       ├── SnapKit
       └── SDWebImage

🎯 类比：以前你只点一份米饭（.xcodeproj），现在改套餐（.xcworkspace）：米饭 + 三菜一汤一起上桌。

3. 环境搭建：5 分钟把 CocoaPods 装上

3.1 前置条件

工具	用来干嘛	检查命令
macOS	CocoaPods 只能在 Mac 上装（Windows/Linux 没 Xcode）	—
Xcode	iOS 编译器 + 模拟器	`xcodebuild -version`
Ruby	CocoaPods 是 Ruby 写的	`ruby -v`
Git	Specs Repo 要从 GitHub 拉	`git --version`

macOS 自带 Ruby 和 Git，正常都不用单独装。

3.2 三种安装方式（推荐第二种）

方式一：系统 Ruby + sudo（最简单但不推荐）

bash

sudo gem install cocoapods

⚠️ 缺点：动了系统 Ruby，以后系统升级或换其他 Ruby 工具容易冲突。

方式二：用 Homebrew 装（推荐 ✅）

bash

brew install cocoapods

干净、好升级，跟其他 brew 包一起管理。

方式三：用 rbenv / rvm 管理 Ruby（专业用法）

适合同时维护多个 Ruby 项目的人，新手不用碰。

3.3 验证安装

bash

pod --version
# 输出 1.15.2 之类就 OK

3.4 第一次跑会很慢，要有心理准备

第一次执行任何 pod install 时，CocoaPods 会去 clone 一个 1G+ 的 Specs Repo。如果你在国内：

bash

# 把官方源换成清华镜像（仅作举例，可能已变化）
pod repo remove master
pod repo add master https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git

4. 实战：从 0 到 1 装第一个 Pod

我们做一件具体的事：新建一个 iOS 工程，集成 Alamofire（一个 Swift 网络库），然后调一个 GET 接口。

4.1 第 1 步：新建 Xcode 工程

打开 Xcode → File → New → Project → iOS App → 起名 HelloPods → 选个目录保存。

4.2 第 2 步：在工程根目录创建 Podfile

打开终端：

bash

cd ~/path/to/HelloPods   # cd 到刚才创建工程的位置（含 .xcodeproj 的那一层）
pod init                 # CocoaPods 会自动生成模板 Podfile

打开生成的 Podfile，改成：

ruby

platform :ios, '15.0'
use_frameworks!

target 'HelloPods' do
  pod 'Alamofire', '~> 5.8'
end

4.3 第 3 步：执行 pod install

bash

pod install

这一行命令背后大致经历了 5 步（细节见第 7 章）：

   1) 解析 Podfile  →  「哦，要装 Alamofire 5.8.x」
   2) 查 Specs Repo →  「最新匹配的是 5.8.1」
   3) 下载源码      →  把 Alamofire 5.8.1 下到本地 Pods/ 目录
   4) 生成 Pods 工程 → 把源码组织成一个新的 .xcodeproj
   5) 创建 .xcworkspace → 把你的工程和 Pods 工程绑在一起

终端最后会看到：

[!] Please close any current Xcode sessions and use `HelloPods.xcworkspace` for this project from now on.

4.4 第 4 步：用 .xcworkspace 打开

bash

open HelloPods.xcworkspace

⚠️ 千万别再双击 .xcodeproj，那样 import Alamofire 会报红。

4.5 第 5 步：在代码里调用

打开 ViewController.swift：

swift

import UIKit
import Alamofire   // ← 直接 import，CocoaPods 已经把它接进来了

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        AF.request("https://httpbin.org/get").responseJSON { response in
            print(response)
        }
    }
}

Cmd + R 跑起来，控制台能看到 JSON 输出 → 大功告成。

4.6 一图回顾

   pod init        →  生成 Podfile 模板
        │
        ▼
   编辑 Podfile    →  写下你要装的库
        │
        ▼
   pod install     →  下载 + 配置 + 生成 workspace + 写 lock
        │
        ▼
   open .xcworkspace → 用它打开 Xcode
        │
        ▼
   import XXX      →  直接用！

5. Podfile 写法详解

新手看到别人项目里几十行 Podfile 容易蒙圈。其实万变不离 6 个套路。

5.1 版本号的 6 种写法

ruby

pod 'Alamofire'                     # 1. 不指定版本：最新稳定版
pod 'Alamofire', '5.8.1'            # 2. 精确锁定 5.8.1
pod 'Alamofire', '> 5.7'            # 3. 严格大于 5.7
pod 'Alamofire', '>= 5.7'           # 4. 大于等于 5.7
pod 'Alamofire', '~> 5.8'           # 5. 5.8.x 中最高版（不超过 5.9）
pod 'Alamofire', '~> 5.8.0'         # 6. 5.8.0 ~ 5.8.x 中最高版（不超过 5.9.0）

🎯 类比 ~> 操作符：
~> 5.8 ≈「我要 5 系列里 8.* 的牛奶，9.* 不要」（小版本随便升）
~> 5.8.0 ≈「我要 5.8 牌子里第 0 批之后的」（只允许补丁升级）
这是最常用的写法 —— 平衡「拿到 bug 修复」和「不被破坏性变更搞挂」。

5.2 从特殊位置拉源码

ruby

# 不从 Specs Repo 走，直接从 GitHub 某个分支
pod 'MyLib', :git => 'https://github.com/me/MyLib.git', :branch => 'develop'

# 锁死某个 commit
pod 'MyLib', :git => 'https://github.com/me/MyLib.git', :commit => 'abc1234'

# 从本地路径（最常用于 debug 一个第三方库）
pod 'MyLib', :path => '../MyLib'

🎯 类比：
默认 = 从大超市买
:git = 直接从厂家发货
:path = 自己家厨房现做的（适合调试）

5.3 多个 target 共享依赖

一个项目里可能同时有 App、Today Widget、Watch App 三个 target：

ruby

def common_pods
  pod 'SnapKit'
  pod 'SDWebImage'
end

target 'MyApp' do
  common_pods
  pod 'Alamofire'    # App 才需要网络库
end

target 'MyAppWidget' do
  common_pods         # Widget 也用 SnapKit + SDWebImage
end

target 'MyAppTests' do
  pod 'Quick'         # 测试 target 单独装测试库
  pod 'Nimble'
end

5.4 use_frameworks! 是干嘛的？

ruby

use_frameworks!         # 用动态 framework
# 或者
use_frameworks! :linkage => :static   # CocoaPods 1.9+，用静态 framework

简化理解：

不写 use_frameworks! → 第三方库以 静态库 .a 形式编入（不支持 Swift Pod）
写了 use_frameworks! → 以 动态 framework 形式编入（Swift 必须）

🎯 类比：
静态库 = 真空包装的预制菜 —— 直接塞进 App 包里，启动快、包体大
动态库 = 冷链外送的鲜菜 —— App 启动时再加载，包体小、启动略慢

写 Swift 项目无脑加 use_frameworks! 就对了。

6. 常用命令速查

命令	干啥	什么时候用
`pod init`	生成 Podfile 模板	新项目第一次集成
`pod install`	按 Lock 文件装依赖	团队成员 git clone 后第一次、改了 Podfile 之后
`pod update`	忽略 Lock，重新解析最新版	你想主动升级某个库
`pod update Alamofire`	只升级 Alamofire 一个	想稳，只升一个
`pod outdated`	列出所有可升级的 Pod	升级前先看一眼
`pod search XXX`	搜库	不知道库的精确名字
`pod repo update`	更新本地 Specs Repo	找不到新版本时
`pod cache clean --all`	清缓存	出现奇怪的下载 / 校验问题
`pod deintegrate`	把项目里所有 CocoaPods 痕迹卸干净	想换 SPM 时

6.1 install vs update 的灵魂区别

这是面试和日常都最爱问的：

   pod install
   ───────────
   有 Podfile.lock → 严格按 lock 里写的版本装
   没 Lock 文件     → 按 Podfile 解析最新匹配版，并生成 lock

   pod update
   ──────────
   不管有没有 lock，**重新去 Specs Repo 解析一遍** Podfile，把能升的都升上去

🎯 类比：
install = 拿着 昨天的小票 去超市，叫店员「按这小票上一模一样的牌子型号给我重买一份」
update = 拿着 空白购物清单 去超市，「按我的菜谱看看现在有啥新货，挑最新的拿」

⚠️ 新手最大的坑之一：每天上班 pod update，结果每天版本都飘 → 同事代码到你这儿就崩。正确习惯：99% 时间用 install，只有想主动升级时才 update。

7. 工作原理：pod install 背后的 7 步

我们把第 4 章那行 pod install 拆开看。理解这 7 步，以后排查问题会轻松 10 倍。

   ┌─────────────────────────────────────────────────────────────┐
   │ Step 1：读 Podfile                                            │
   │   解析你写的 DSL，得到「目标列表」                                  │
   │   target HelloPods → [Alamofire ~> 5.8]                      │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 2：检查 Podfile.lock                                     │
   │   有 lock：按 lock 里写的精确版本走                                 │
   │   没 lock：按 Podfile 的版本约束去查                                │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 3：解析依赖图（依赖求解）                                      │
   │   Alamofire 依赖 X，X 依赖 Y → 把整张依赖图算清楚                    │
   │   并解决「A 要 Y 1.x、B 要 Y 2.x」这种冲突                          │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 4：在 Specs Repo 查每个 Pod 的 Podspec                    │
   │   ~/.cocoapods/repos/master/Specs/Alamofire/5.8.1/...        │
   │   → 拿到 source 字段：git@github.com:.../tag 5.8.1            │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 5：下载源码到 Pods/ 目录                                    │
   │   git clone --depth=1 + checkout 对应 tag                    │
   │   缓存到 ~/Library/Caches/CocoaPods/                          │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 6：生成 Pods.xcodeproj                                    │
   │   把所有源码按 Podspec 里写的 source_files 配置组织成 Xcode 工程    │
   │   自动配好 Header Search Paths / Linker Flags / Framework 等  │
   └─────────────────────────────────────────────────────────────┘
                                ▼
   ┌─────────────────────────────────────────────────────────────┐
   │ Step 7：生成 / 更新 .xcworkspace                                │
   │   把你的 .xcodeproj 和 Pods.xcodeproj 绑成一个 workspace        │
   │   写出 Podfile.lock                                           │
   └─────────────────────────────────────────────────────────────┘

🎯 再用外卖类比一遍：
看清单 → 2. 翻一下昨天的小票 → 3. 想想「番茄炒蛋」需要番茄+鸡蛋+葱花，列出完整购物清单 →
在大众点评上查每家店地址 → 5. 一家家小哥跑去取 → 6. 整齐摆到你家厨房台面 → 7. 在饭桌上摆好

8. 进阶：什么时候你会接触到这些？

8.1 私有 Pod —— 公司内部库

公司有 10 个 App，都要用同一套登录 SDK。怎么办？做成一个 私有 Pod：

   1. 把登录 SDK 代码放到公司 GitLab 私有仓
   2. 写一个 LoginSDK.podspec 描述它
   3. 把 podspec 推到「公司内部 Specs Repo」（一个内部 Git 仓）
   4. 各 App 的 Podfile 加：
      source 'https://gitlab.company.com/ios/specs.git'   ← 私有源
      source 'https://cdn.cocoapods.org/'                 ← 官方源
      pod 'LoginSDK', '~> 1.0'

🎯 类比：除了大众超市（公共 Specs Repo），公司还有「员工内购货架」（私有 Specs Repo）。

8.2 二进制 Pod —— 加快编译速度

大型项目几百个 Pod，每次 clean build 半小时起步 ——「把第三方库预编译成 .framework 直接发布」就是常见解法（Firebase、各种厂商 SDK 都这么做）。

ruby

# 直接给 framework
s.vendored_frameworks = 'XXXSDK.framework'

代价是：拿不到源码、调试时只能看汇编。

8.3 Podspec 自己写一个

如果你要把自己写的开源库发到 CocoaPods，你需要：

bash

pod spec create MyAwesomeLib    # 生成模板
# 编辑 MyAwesomeLib.podspec
pod spec lint                    # 本地检查
pod trunk push                   # 推到官方 Specs Repo

9. CocoaPods vs SPM vs Carthage：3 个选 1 个？

iOS 圈历史上一共出现过 3 个主流依赖管理工具，对比一下：

维度	CocoaPods	Carthage	SPM (Swift Package Manager)
出生	2011	2014	2019（Xcode 11 起原生支持）
出品方	社区	社区	Apple 官方
写啥	Ruby DSL（Podfile）	Cartfile	Package.swift
改不改你的 Xcode 工程	大改，生成 .xcworkspace	不改，只编出 framework，剩下你自己拖	不改，Xcode 内置支持
学习曲线	中（要懂一点 Ruby + workspace）	低	低（Xcode UI 一键加）
社区库丰富度	⭐⭐⭐⭐⭐ 最全	⭐⭐⭐	⭐⭐⭐⭐ 增长非常快
编译速度	中	快（预编译）	中
现状	老项目主流	基本被淘汰	新项目首选

📌 2026 年的选型建议：
新项目：优先 SPM，简单、官方支持、零配置；
老项目：继续用 CocoaPods 没问题，迁移成本不一定划算；
混用：完全可以一个项目同时用 SPM + CocoaPods（很多大厂在迁移期就是这样）。
但即便 SPM 是未来，国内绝大多数公司的存量 iOS 工程仍然在用 CocoaPods，所以这门技能短期内不会过时。

10. 常见坑 & 故障排查

10.1 「Unable to find a specification for XXX」

[!] Unable to find a specification for `Alamofire`

原因 90% 是本地 Specs Repo 太旧，没有这个新版本。

bash

pod repo update          # 老版本叫法
pod install --repo-update  # 一条命令搞定

10.2 「Sandbox not in sync with Podfile.lock」

Xcode 报错说「沙盒和 lock 文件不一致」。

原因：你的 Podfile.lock 跟 Pods/ 目录里实际的版本对不上 —— 通常是 git 切了分支但忘了 pod install。

解法：

bash

pod install

10.3 import 完红线还在

打开了 .xcodeproj 而不是 .xcworkspace。关掉重开 .xcworkspace。

10.4 升级 Xcode 后 Pod 全炸

Xcode 大版本升级会改 build 系统。

bash

pod deintegrate    # 把项目里 CocoaPods 痕迹清干净
pod install        # 重装

10.5 国内下载特别慢

换镜像源（清华、Gitee 都有）
大文件（如 Firebase）配上代理：export ALL_PROXY=http://127.0.0.1:7890

10.6 .gitignore 该忽略 Pods/ 吗？

历史上有两派打架：

提交 Pods/	不提交 Pods/
✅ git clone 后立刻能编译	✅ 仓库小
❌ 仓库巨大	❌ 新人要多跑一次 pod install
❌ diff 噪音爆炸	❌ 第三方源被删时无解

📌 当今主流：不提交 Pods/，但务必提交 Podfile 和 Podfile.lock。

.gitignore 标准写法：

# CocoaPods
Pods/
# 但保留 Podfile 和 Podfile.lock（默认就保留）

11. 推荐学习路径

   Day 1：理解「包管理器」概念（本文 §0~§2）
       │
       ▼
   Day 2：装好 CocoaPods，跑通第一个 Alamofire 示例（§3~§4）
       │
       ▼
   Day 3：吃透 Podfile 的 6 种版本写法（§5）
       │
       ▼
   Day 4：搞懂 install vs update 区别（§6~§7）
       │
       ▼
   Week 2：开始读公司项目里的 Podfile，能解释每一行
       │
       ▼
   Week 3：尝试自己发一个 Pod（§8.3）
       │
       ▼
   Month 2：研究 SPM，了解差异和迁移路径（§9）

12. 一句话记忆卡

概念	一句话
包管理器	程序员的超市
Pod	一袋大米
Podfile	你写的购物清单
Podspec	商品标签
Specs Repo	中央商品目录
Podfile.lock	收银小票
.xcworkspace	套餐而非单点
pod install	按昨天小票照单全收
pod update	重新去货架挑最新的
use_frameworks!	Swift 项目无脑加

13. 延伸阅读

官方文档：https://guides.cocoapods.org/
Podfile 语法：https://guides.cocoapods.org/syntax/podfile.html
Podspec 语法：https://guides.cocoapods.org/syntax/podspec.html
中央 Specs 仓库：https://github.com/CocoaPods/Specs
SPM 对照学习：https://www.swift.org/package-manager/

📌 学完本文你应该能做到：拿到一个陌生的 iOS 项目，看 Podfile 的前 5 行就能猜出这个项目的技术栈（网络用啥、UI 用啥、图片用啥），并且能在自己机器上一行 pod install 跑起来。这就是 0 到 1 的全部目标。

CocoaPods：从 0 到 1 的依赖管理调研笔记 ​

0. 先回答一个灵魂问题：什么是「包管理器」？ ​

0.1 想象你要做一道「番茄炒蛋」 ​

0.2 没有包管理器的世界有多惨 ​

1. CocoaPods 到底是个什么东西？ ​

1.1 三句话讲清楚 ​

1.2 CocoaPods 在外卖平台里的位置 ​

1.3 一句话总结 ​

2. 五大核心概念详解 ​

2.1 Pod —— 一个「商品」 ​

2.2 Podfile —— 你的「购物清单」 ​

2.3 Podfile.lock —— 你的「订单小票」 ​

2.4 Podspec —— 商品的「说明书」 ​

2.5 Specs Repo —— 中央「商品目录」 ​

2.6 .xcworkspace —— Xcode 的「套餐」 ​

3. 环境搭建：5 分钟把 CocoaPods 装上 ​

3.1 前置条件 ​

3.2 三种安装方式（推荐第二种） ​

方式一：系统 Ruby + sudo（最简单但不推荐） ​

方式二：用 Homebrew 装（推荐 ✅） ​

方式三：用 rbenv / rvm 管理 Ruby（专业用法） ​

3.3 验证安装 ​

3.4 第一次跑会很慢，要有心理准备 ​

4. 实战：从 0 到 1 装第一个 Pod ​

4.1 第 1 步：新建 Xcode 工程 ​

4.2 第 2 步：在工程根目录创建 Podfile ​

4.3 第 3 步：执行 pod install ​

4.4 第 4 步：用 .xcworkspace 打开 ​

4.5 第 5 步：在代码里调用 ​

4.6 一图回顾 ​

5. Podfile 写法详解 ​

5.1 版本号的 6 种写法 ​

5.2 从特殊位置拉源码 ​

5.3 多个 target 共享依赖 ​

5.4 use_frameworks! 是干嘛的？ ​

6. 常用命令速查 ​

6.1 install vs update 的灵魂区别 ​

7. 工作原理：pod install 背后的 7 步 ​

8. 进阶：什么时候你会接触到这些？ ​

8.1 私有 Pod —— 公司内部库 ​

8.2 二进制 Pod —— 加快编译速度 ​

8.3 Podspec 自己写一个 ​

9. CocoaPods vs SPM vs Carthage：3 个选 1 个？ ​

10. 常见坑 & 故障排查 ​

10.1 「Unable to find a specification for XXX」 ​

10.2 「Sandbox not in sync with Podfile.lock」 ​

10.3 import 完红线还在 ​

10.4 升级 Xcode 后 Pod 全炸 ​

10.5 国内下载特别慢 ​

10.6 .gitignore 该忽略 Pods/ 吗？ ​

11. 推荐学习路径 ​

12. 一句话记忆卡 ​

13. 延伸阅读 ​

CocoaPods：从 0 到 1 的依赖管理调研笔记

0. 先回答一个灵魂问题：什么是「包管理器」？

0.1 想象你要做一道「番茄炒蛋」

0.2 没有包管理器的世界有多惨

1. CocoaPods 到底是个什么东西？

1.1 三句话讲清楚

1.2 CocoaPods 在外卖平台里的位置

1.3 一句话总结

2. 五大核心概念详解

2.1 Pod —— 一个「商品」

2.2 Podfile —— 你的「购物清单」

2.3 Podfile.lock —— 你的「订单小票」

2.4 Podspec —— 商品的「说明书」

2.5 Specs Repo —— 中央「商品目录」

2.6 .xcworkspace —— Xcode 的「套餐」

3. 环境搭建：5 分钟把 CocoaPods 装上

3.1 前置条件

3.2 三种安装方式（推荐第二种）

方式一：系统 Ruby + sudo（最简单但不推荐）

方式二：用 Homebrew 装（推荐 ✅）

方式三：用 rbenv / rvm 管理 Ruby（专业用法）

3.3 验证安装

3.4 第一次跑会很慢，要有心理准备

4. 实战：从 0 到 1 装第一个 Pod

4.1 第 1 步：新建 Xcode 工程

4.2 第 2 步：在工程根目录创建 Podfile

4.3 第 3 步：执行 pod install

4.4 第 4 步：用 .xcworkspace 打开

4.5 第 5 步：在代码里调用

4.6 一图回顾

5. Podfile 写法详解

5.1 版本号的 6 种写法

5.2 从特殊位置拉源码

5.3 多个 target 共享依赖

5.4 use_frameworks! 是干嘛的？

6. 常用命令速查

6.1 install vs update 的灵魂区别

7. 工作原理：pod install 背后的 7 步

8. 进阶：什么时候你会接触到这些？

8.1 私有 Pod —— 公司内部库

8.2 二进制 Pod —— 加快编译速度

8.3 Podspec 自己写一个

9. CocoaPods vs SPM vs Carthage：3 个选 1 个？

10. 常见坑 & 故障排查

10.1 「Unable to find a specification for XXX」

10.2 「Sandbox not in sync with Podfile.lock」

10.3 import 完红线还在

10.4 升级 Xcode 后 Pod 全炸

10.5 国内下载特别慢

10.6 .gitignore 该忽略 Pods/ 吗？

11. 推荐学习路径

12. 一句话记忆卡

13. 延伸阅读