一、为什么要做迁移:手动集成的痛点
很多做苹果端开发的朋友,一开始写小项目的时候,都会选择手动集成依赖。比如要用到一个图片缓存的工具,就去官网下载它的源码包,解压后把对应的.h和.m文件拖进自己的项目,再设置各种路径、权限。一开始觉得挺方便,毕竟不用学新东西,但项目越做越大,麻烦就越来越多。
比如后来项目要加新功能,需要另一个依赖,这个依赖又依赖之前的图片缓存工具,版本还得是1.2.3以上的,手动改的时候才发现自己之前拖进来的是1.1.0,要么重下覆盖要么改源码适配,很容易出错。还有就是团队协作的时候,每个人的电脑环境不一样,有的同事拖依赖的时候漏了配置,编译就报错,找半天原因才发现是依赖的问题。另外,要是依赖有安全漏洞或者新功能,手动更新就得重新拖一遍,还得重新配置,太费时间。
所以迁移到CocoaPods管理,本质上就是把这些麻烦的手动操作,交给工具自动处理,让开发效率提上来。
二、迁移前的准备工作
在动手改之前,得先把环境搭好,不然中间卡壳更麻烦。首先得确认自己的电脑有没有装Ruby环境,因为CocoaPods是用Ruby写的。怎么确认呢?打开终端,输入下面的命令:
# 检查Ruby版本,只要不是太旧的版本都可以,比如2.3以上
ruby -v
如果输出类似ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-darwin19]这样的内容,说明Ruby环境没问题。如果没装的话,用Homebrew装就行,命令是brew install ruby,装完再确认一次版本。
接下来就是装CocoaPods本身,终端输入:
# 安装CocoaPods,可能需要输入电脑密码,因为要装到系统目录
sudo gem install cocoapods
装完之后也要确认一下:
# 检查CocoaPods版本,正常会输出类似1.12.1这样的版本号
pod --version
除了环境,还要整理一下现有项目的依赖清单。比如把之前手动加的所有依赖,都列出来,包括每个依赖的名字、版本号、用途。比如之前手动加的SDWebImage,版本是1.1.0,用途是图片缓存;还有AFNetworking,版本是3.0.0,用途是网络请求。整理这个清单的目的,是后面写Podfile的时候不会漏。
三、迁移的核心步骤
3.1 初始化Podfile
Podfile是CocoaPods的配置文件,就像一个购物清单,告诉CocoaPods要下载哪些依赖。首先要进入自己的项目目录,比如你的项目叫MyApp,路径是/Users/xxx/Projects/MyApp,那终端先cd到这个目录:
# 替换成自己的项目路径,比如我这里的路径是/Users/zhangsan/Projects/MyApp
cd /Users/zhangsan/Projects/MyApp
然后执行初始化命令:
# 初始化Podfile,会在项目目录下生成一个Podfile文件
pod init
初始化之后,打开Podfile,里面的内容大概是这样的:
# 这是Podfile的默认模板,我们可以根据自己的项目修改
platform :ios, '11.0' # 这里指定项目支持的最低iOS版本,要和自己项目的设置一致
target 'MyApp' do # 这里的MyApp是你的项目的主target名字,要和项目里的名字完全一样
# 在这里加依赖
end
比如我的项目支持的最低iOS版本是12.0,主target名字是MyApp,那我就把platform那行改成platform :ios, '12.0'。
3.2 编写依赖配置
接下来就是把之前整理的依赖清单,加到Podfile里。比如之前的SDWebImage和AFNetworking,就这么加:
platform :ios, '12.0'
target 'MyApp' do
# 第一个依赖:SDWebImage,指定版本1.1.0,和之前手动集成的版本一致
pod 'SDWebImage', '1.1.0'
# 第二个依赖:AFNetworking,指定版本3.0.0
pod 'AFNetworking', '3.0.0'
end
这里要注意,版本号一定要和之前手动的一致,不然可能会出现兼容问题。如果不确定之前的版本号,可以去项目里找依赖的源码,比如SDWebImage的源码里会有一个叫SDWebImage.podspec的文件,打开里面的s.version = '1.1.0'就是版本号。
3.3 安装依赖
写好Podfile之后,就可以安装依赖了,终端执行:
# 安装依赖,第一次执行会比较慢,因为要下载所有依赖
pod install
执行成功之后,项目目录下会多几个东西:一个叫Podfile.lock的文件,用来锁定每个依赖的具体版本,避免团队成员之间版本不一致;一个叫Pods的文件夹,里面是所有依赖的源码;还有一个叫MyApp.xcworkspace的文件,这个是之后要打开的项目文件,之前的MyApp.xcodeproj就不要再用了,因为所有的配置都在xcworkspace里。
3.4 清理手动集成的依赖
安装完之后,就要把之前手动加的依赖删掉了,不然会有冲突。比如之前拖进项目的SDWebImage的.h和.m文件,还有AFNetworking的源码,都要从项目里删掉。还要检查项目的Build Settings里的配置,比如之前手动加的头文件搜索路径、库搜索路径,都要删掉,因为CocoaPods会自动配置这些。
这里给个示例,比如我之前手动加SDWebImage的时候,在项目的Build Settings里加了头文件搜索路径$(PROJECT_DIR)/SDWebImage,现在要把这个路径删掉,不然编译的时候可能会重复引用。
四、验证迁移效果
清理完之后,要打开xcworkspace文件编译项目,看看能不能正常运行。编译的时候可能会出现一些问题,比如找不到头文件,这时候大概率是之前的配置没清干净,或者Podfile里的target名字写错了。
比如编译报错'SDWebImage/SDWebImage.h' file not found,先检查Podfile里的target名字是不是和项目里的一致,比如项目里的target名字是MyApp,Podfile里写的是Myapp(首字母小写),就会报错。再检查有没有打开xcworkspace,要是不小心打开了xcodeproj,也会找不到依赖。
编译通过之后,还要测试一下项目的功能,比如之前用SDWebImage加载图片的地方,能不能正常显示;用AFNetworking发请求的地方,能不能正常拿到数据。还要检查有没有内存泄漏、崩溃这些问题,确保迁移之后不影响项目的正常运行。
五、迁移的优化点
迁移的时候,还可以做一些优化,让后续的维护更方便。比如给依赖分组,把功能相关的依赖放在一起,方便管理。比如把网络相关的依赖放在一个组里,把UI相关的放在另一个组里。
示例的Podfile配置:
platform :ios, '12.0'
target 'MyApp' do
# 网络相关依赖
pod 'AFNetworking', '3.0.0'
pod 'Reachability', '3.2' # 用来检测网络状态的依赖
# UI相关依赖
pod 'SDWebImage', '1.1.0'
pod 'Masonry', '1.1.0' # 用来做自动布局的依赖
end
这样看起来更清晰,后面加新依赖的时候,也知道该放在哪个组里。
还有就是可以指定依赖的分支或者提交哈希,比如你用到的依赖是自己改了源码的,就可以指定从某个分支拉取,或者某个提交拉取。示例:
# 从自己的SDWebImage仓库的dev分支拉取依赖
pod 'SDWebImage', :git => 'https://github.com/your-username/SDWebImage.git', :branch => 'dev'
这样CocoaPods就会从指定的仓库拉取依赖,而不是官方的仓库。
六、迁移的应用场景、优缺点和注意事项
6.1 应用场景
迁移到CocoaPods的场景主要有这几种:一是项目规模变大,手动集成依赖越来越麻烦,比如依赖超过3个,或者团队有2个以上的开发人员;二是项目需要频繁更新依赖,比如依赖有安全漏洞或者新功能,手动更新效率太低;三是项目需要集成第三方的SDK,比如支付SDK、统计SDK,这些SDK通常都有CocoaPods的版本,用CocoaPods集成更方便;四是团队协作,避免每个开发人员的环境不一致,导致编译报错。
6.2 技术优缺点
优点方面,首先是自动管理依赖,不用手动下载、拖文件、配置,节省时间;其次是版本统一,团队成员用的依赖版本都一样,避免环境不一致的问题;第三是方便更新,要更新依赖的时候,只要改Podfile里的版本号,然后执行pod update就行;第四是自动配置,CocoaPods会自动配置头文件路径、库路径这些,不用手动改Build Settings;第五是依赖管理清晰,Podfile可以分组,方便查看项目用到了哪些依赖。
缺点方面,首先是有学习成本,对于从来没用过CocoaPods的开发人员,需要花时间学习怎么写Podfile、怎么执行命令;其次是依赖的稳定性,如果官方的依赖版本有问题,整个项目可能会编译失败;第三是第一次安装依赖的时候比较慢,尤其是依赖多的项目,下载时间可能会很长;第四是如果依赖的仓库在国外,可能会因为网络问题导致安装失败,需要换源。
6.3 注意事项
迁移的时候要注意这几点:第一,一定要备份项目,迁移之前先把项目拷贝一份,万一迁移失败,还能回到原来的状态;第二,版本号要一致,Podfile里的依赖版本要和之前手动集成的版本一致,避免兼容问题;第三,要清理干净手动集成的依赖,包括源码和配置,不然会有冲突;第四,一定要打开xcworkspace文件,不要用原来的xcodeproj;第五,要验证迁移效果,编译通过之后还要测试功能,确保没有问题;第六,要注意网络问题,如果安装依赖的时候很慢,可以换国内的源,比如把CocoaPods的源换成清华的源,命令是:
# 换清华的源,提高下载速度
pod repo add cocoapods https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git
pod repo update
七、文章总结
从手动集成依赖到CocoaPods管理的迁移,本质上是把重复、容易出错的手动操作,交给工具自动处理,从而提高开发效率,降低维护成本。整个流程的核心是先准备环境,然后初始化Podfile、编写依赖配置、安装依赖、清理手动依赖,最后验证效果。
迁移的时候要注意备份项目、版本一致、清理干净、打开正确的项目文件,还要验证效果。迁移之后,不仅依赖管理更清晰,团队协作也更顺畅,后续更新依赖也更方便。对于中小项目来说,迁移的成本很低,但带来的收益很大,所以如果你的项目还在手动集成依赖,不妨试试迁移到CocoaPods管理。
评论
围绕“CocoaPods项目迁移:从手动集成依赖到CocoaPods管理的流程优化”参与讨论