Cocoapods 仓库管理指南

最近更新：2024年5月23日

本文档涵盖私有库的完整管理流程、公有库的发布步骤以及常见问题的解决方案。

1. Git 代码搬迁

当需要迁移 Git 项目时，请遵循以下步骤：

在新 Git 服务器上创建一个同名的空项目（不同名也可，但后续步骤需相应调整）。
在本地克隆旧 Git 的代码仓库：
```
git clone <旧项目地址>
```
（若本地已存在该项目，可使用 git remote -v 查看当前远程仓库地址）。
将本地代码镜像推送至新仓库：
```
git push --mirror <新项目地址>
```
验证迁移：从新 Git 地址克隆代码到本地，确认项目完整无误。

2. 私有 Pod 库（组件库）管理

2.1 创建 Pod 组件工程

以创建 YBBluetoothKit 为例：

pod lib create YBBluetoothKit

创建过程中需回答以下问题：

选择平台：iOS 或 macOS → 例如 ios
选择语言：Swift 或 ObjC → 例如 swift
包含 Demo：是否创建示例工程 → 例如 yes
测试框架：选择 Quick 或 None → 例如 none
视图测试：是否进行基于视图的测试 → 例如 no

2.2 配置 Podspec 文件

关键字段必须修改，示例如下：

Pod::Spec.new do |s|
  s.name             = 'YBBluetoothKit'           # 库名称，通常与项目名一致
  s.version          = '0.1.0'                    # 版本号，每次更新需调整
  s.summary          = '适用于iOS的蓝牙功能封装库'  # 简明扼要的简介
  s.description      = <<-DESC                     # 详细描述（可选）
                        提供蓝牙设备的连接、数据读写等功能封装。
                       DESC
  s.homepage         = 'http://your.domain/YBBluetoothKit'  # 项目主页
  s.license          = { :type => 'MIT', :file => 'LICENSE' }
  s.author           = { 'YourName' => 'your.email@example.com' }
  s.source           = { :git => 'http://your.domain/YBBluetoothKit.git', :tag => s.version.to_s }  # 源码地址
  s.ios.deployment_target = '10.0'                # 最低支持版本
  s.source_files     = 'YBBluetoothKit/Classes/**/*'  # 源码路径
  s.swift_version    = '5.0'                      # Swift版本（如为Swift项目）
  # s.dependency 'SomeOtherPod'                   # 依赖的第三方库（可选）
end

2.3 本地验证 Podspec

在 podspec 文件所在目录执行：

pod lib lint --allow-warnings

出现 YBBluetoothKit passed validation. 即表示成功。

2.4 设置远程仓库并推送

git remote add origin <您的远程仓库地址>
git add .
git commit -m "初始化项目"
git tag -m "版本0.1.0" 0.1.0
git push origin master
git push --tags

2.5 远程验证 Podspec

pod spec lint --allow-warnings

3. Pod 索引库（Specs 主仓库）

3.1 创建索引库

在 Git 上创建空项目（如 ManagerSpecRepo）用于存放所有私有组件的 spec 文件。

3.2 本地添加索引库

pod repo add ManagerSpecRepo <索引库Git地址>

3.3 推送组件至索引库

pod repo push ManagerSpecRepo YBBluetoothKit.podspec --allow-warnings

常用索引库管理命令：

查看本地索引库：pod repo list
删除本地索引库：pod repo remove <库名>

4. 私有库更新流程

更新代码后，修改 podspec 文件中的 s.version。

提交代码并打上新 tag：

git commit -am "更新内容"
git tag -m "新版本描述" <新版本号>
git push origin master --tags

执行本地验证：
```
pod lib lint --allow-warnings
```

推送更新至索引库：

pod repo push ManagerSpecRepo YBBluetoothKit.podspec --allow-warnings

复杂场景参数：

含静态库：添加 --use-libraries

依赖其他私有库：指定 sources

pod repo push ManagerSpecRepo YBBluetoothKit.podspec --sources="http://您的私有Spec库,https://github.com/CocoaPods/Specs.git" --allow-warnings --use-libraries

5. 发布到公有库（CocoaPods Trunk）

5.1 注册 Trunk

首次使用需注册：

pod trunk register your.email@example.com 'Your Name' --description='MacBook Pro'

验证邮箱后即可发布。

5.2 发布到公有库

确保项目已在 GitHub 上开源，且 podspec 通过验证：
```
pod spec lint --allow-warnings
```

执行发布：

pod trunk push YBBluetoothKit.podspec --allow-warnings

发布后可通过 pod search YBBluetoothKit 查询。

5.3 管理公有库

查看信息：pod trunk me
添加维护者：pod trunk add-owner YBBluetoothKit other@email.com

6. 常见问题与解决方法

本地验证警告：
- 现象：due to 2 warnings
- 解决：添加 --allow-warnings 参数
模拟器不可用：
- 现象：Simulator is not available
- 解决：更新 CocoaPods：sudo gem install cocoapods --pre
Xcode 路径错误：
- 现象：Must be in the root of the repo...
- 解决：重置路径：sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
Spec 验证失败：
- 解决：添加 --verbose --use-libraries --allow-warnings 参数
Git 仓库不存在：
- 现象：fatal: repository '' not found
- 解决：确认本地索引库是否存在（pod repo list）
Swift 版本警告：
- 现象：uses Swift 3.0 by default
- 解决：创建版本文件：echo "5.0" > .swift-version
依赖冲突：
- 现象：could not find compatible versions
- 解决：
  1. 临时注释 Podfile 中的源和依赖
  2. 执行 pod install
  3. 恢复注释内容后再执行 pod install
找不到公有库 Specification：
- 现象：Unable to find a specification for
- 解决：执行 pod update 或 pod repo update

7. 总结建议

版本管理：遵循语义化版本控制（Semantic Versioning）
依赖管理：明确区分公有依赖和私有依赖
验证流程：坚持先本地后远程的验证顺序
文档维护：保持 README 和 podspec 文档的及时更新

如有其他问题，可参考 CocoaPods 官方指南或查看项目具体错误信息进行分析。

Swift 私有库、公有库、组件化快速搭建(CocoaPods私有库/公有库/索引库)