在 uts 插件中使用 CocoaPods 依賴
在 uts 插件中使用 CocoaPods 依賴庫诵盼，需要在 config.json 中 dependencies-pods 節(jié)點做相應(yīng)配置惠豺，下面是配置示例：
{
"deploymentTarget": "9.0", // 可選，插件支持的最低 iOS 版本 默認：9.0"
"dependencies-pods": [ // 可選, 需要依賴的 CocoaPods 庫, HBuilderX 3.8.5+ 版本支持
{
"name": "WechatOpenSDK",
"version": "2.0.2"
}, {
"name": "Alamofire",
"version": "5.7.3", //配置 repo 時可不指定 version
"repo": { // 可選风宁，配置 pod 庫為指定倉庫洁墙，配置repo時，應(yīng)至少指定 git戒财。 （HBuilder X 3.8.10+ 版本新增支持）
"git": "https://github.com/test/Alamofire.git", //指定 pod 庫的倉庫地址
"tag": "5.7.3", // 指定該 pod 庫倉庫的 tag
"branch": "dev", // 指定該 pod 庫倉庫的分支
"commit": "b309714f3aa5091f1ce8d932094b7594ed7acad9" // 指定該 pod 庫倉庫的某次commit
}
}]
}
注意：拷貝以上代碼時請手動刪除注釋热监，實際項目中config.json中不能包含注釋信息
配置說明：
- deploymentTarget：插件支持的最低 iOS 版本號，此節(jié)點為可選項饮寞，默認設(shè)置為 9.0.
- 插件支持的最低版本號應(yīng)該設(shè)置為所有依賴的三方庫（包含 framework .a pod ）中最低支持版本號中的最高的一個孝扛。
- pod 庫的最低支持系統(tǒng)版本號可在 pod 庫的 spec 文件或者 readme 中查看。
- dependencies-pods：插件需要依賴的 pod 庫, HBuilderX3.8.5+ 版本新增支持
- 把需要依賴的 pod 庫相關(guān)信息配置在 dependencies-pods 節(jié)點下幽崩，需要明確指定每個 pod 庫的名字 (name)苦始。 按需指定版本號 version 或者 repo （至少應(yīng)配置 version 或 repo 中的一個，repo 優(yōu)先級高于 version， 配置 repo 時 version 不再生效），可同時配置多個 pod 依賴庫公般。目前不支持通過 podfile 文件直接設(shè)置，也不支持 podfile 文件中除了 name 彬呻、 version 、pod 特定倉庫之外的其他配置項。
- 為了保證插件的穩(wěn)定性，避免因未指定 pod 庫版本臼勉，執(zhí)行 pod install 之后 pod 庫最新版本造成的代碼不兼容問題邻吭，在未配置 repo 時需要明確指定 pod 庫的具體版本餐弱。此時 version 字段不可省略，不可為空字符串。 建議將 version 配置為
"9.7.0"這種明確的數(shù)字版本號膏蚓，不建議使用~>, >, >=, <, <=等帶符號的配置瓢谢。 - repo: 自定義 pod 庫倉庫地址信息, HBuilderX3.8.10+ 版本新增支持
- 如果你需要自己指定 pod 庫的倉庫地址: git, tag, branch, commit 等信息，可以通過repo字段配置驮瞧。請注意： repo 是一個對象氓扛，其中至少應(yīng)包含 git 字段（用來指定 pod 庫的倉庫地址）。當你同時指定 tag论笔、 branch采郎、 commit 時，CocoaPods 會默認使用 commit狂魔，通乘饴瘢可以根據(jù)需要指定 tag / branch / commit 中的一個。當正確配置 repo 時 version 不再生效最楷，此時可以省略 version 的配置整份。
- 使用 CocoaPods 官方默認地址 (source 'https://cdn.cocoapods.org/'), 暫不接受 source 配置。
CocoaPods 環(huán)境配置
在Mac系統(tǒng)上使用標準基座真機運行時才需要配置 CocoaPods 環(huán)境籽孙， 使用自定義調(diào)試基座提交云端打包則可以不配置 CocoaPods 環(huán)境烈评。 在Windows系統(tǒng)上不支持 CocoaPods 環(huán)境，只能提交云端打包使用自定義調(diào)試基座犯建。
CocoaPods安裝
正常安裝 CocoaPods 需要在終端執(zhí)行下述命令
gem install cocoapods
CocoaPods 安裝成功
這會耗費一段時間讲冠，完成后可查看 cocoapods 的版本號
pod --version
如： 1.12.1
也可以查看 pod 的安裝位置
which pod
如：/Users/dcloud/.rvm/rubies/ruby-3.0.0/bin/pod
至此 CocoaPods 已經(jīng)安裝完成，可以嘗試 Search 下一 pod 庫：
pod search Alamofire
如果執(zhí)行 pod search 失敗适瓦，說明當前網(wǎng)絡(luò)不能正常訪問 github 或者 cdn, 更多信息詳見無法訪問 github , CDN錯誤沟启。
CocoaPods 安裝失敗
- 如果執(zhí)行 gem install cocoapods 之后報下面的錯誤：
ERROR: Error installing cocoapods:
The last version of activesupport (>= 5.0, < 8) to support your Ruby & RubyGems was 6.1.7.3\. Try installing it with `gem install activesupport -v 6.1.7.3` and then running the current command again
activesupport requires Ruby version >= 2.7.0\. The current ruby version is 2.6.10.210.
說明缺少activesupport插件，在終端執(zhí)行以下命令
sudo gem install activesupport -v 6.1.7.3
插件安裝成功后再次執(zhí)行 sudo gem install cocoapods 安裝 CocoaPods.
- 如果報錯如下犹菇，說明需要升級 gem 和 ruby
Building native extensions. This could take a while...
ERROR: Error installing cocoapods:
ERROR: Failed to build gem native extension.
current directory: /Library/Ruby/Gems/2.6.0/gems/ffi-1.15.5/ext/ffi c
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby-I/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0-r./siteconf20230612-9566-nht0td.rbextconf.rb
mkmf.rb can't find header files for ruby at /System/Library/Frameworks/Ruby.framework/Versions/2.6/us/lib/ruby/include/ruby.h
You might have to install separate package for the ruby development environment, ruby-dev or ruby-devel for example.
extconf failed, exit code 1
Gem files will remain installed in /Library/Ruby/Gems/2.6.0/gems/ffi-1.15.5 for inspection.
Results logged to /Library/Ruby/Gems/2.6.0/extensions/universal-darwin-22/2.6.0/ffi-1.15.5/gem make.out
下面是升級 Gem 和 Ruby 的方法
升級 Gem
Gem 是管理 Ruby 標準包,如果 Gem 版本過低可能造成無法安裝 CocoaPods,升級 Gem 使用下述命令
gem -v //查看當前gem版本
sudo gem update --system //升級gem
升級 Ruby
MacOS 會自帶 Ruby德迹，但可能系統(tǒng)的Ruby版本過低，導(dǎo)致無法安裝 CocoaPods, 可通過以下方式更新 Ruby
- 如果沒有安裝 Homebrew揭芍，可以先在終端中輸入以下命令安裝 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Ruby 的升級有以下兩種常見的方式胳搞，可根據(jù)自己的需要任選其中一種：
通過 RVM 升級 Ruby
- 安裝 RVM：在終端中輸入以下命令安裝 RVM：
curl -sSL https://get.rvm.io | bash -s stable
這個命令會從 RVM 官網(wǎng)下載安裝腳本并運行。安裝完成后称杨，需要在終端中執(zhí)行以下命令以便讓 RVM 生效：
source ~/.rvm/scripts/rvm
- 查看 rvm 版本
rvm -v
- 查看可安裝的 ruby 版本列表
rvm list known
- 安裝指定 ruby 版本（eg:安裝 ruby 3.0.0版本）
rvm install ruby-3.0.0
- 切換 Ruby 使用版本（eg:指定使用3.0.0版本）
rvm use ruby-3.0.0
通過 Homebrew 升級 Ruby
在終端執(zhí)行如下命令
brew install ruby
安裝完成后肌毅，ruby 默認使用的是系統(tǒng)自帶的版本
- 查看版本號
ruby -v
- 查看 ruby 安裝路徑
which ruby
- 配置環(huán)境變量
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
- 配置完成后重啟終端，再次查看 Ruby 版本號姑原，校驗是否為安裝的 Ruby版本
升級完 Gem 和 Ruby 后悬而，在終端重新輸入如下命令安裝 CocoaPods。
sudo gem install cocoapods
安裝完成后锭汛，可如上文所示笨奠，查看 CocoaPods 版本號袭蝗。
常見問題
MAC 環(huán)境真機運行 uts 插件時未安裝 CocoaPods
錯誤信息：uni_module xxxx (iOS) 存在pod三方依賴庫，請先安裝 CocoaPods般婆！ 說明：出現(xiàn)此錯誤是因為當前環(huán)境沒有安裝 CocoaPods 處理方法： 請參照上述章節(jié)描述的方式安裝 CocoaPods 工具到腥。
找不到指定版本的 pod 庫，或者找不到指定依賴
錯誤信息：CocoaPods could not find compatible versions for pod "xxx" 或者 None of your spec sources contain a spec satisfying the dependency: 報錯示例：
'Analyzing dependencies\n' +
'[!] CocoaPods could not find compatible versions for pod "HandyJSON":\n' +
' In Podfile:\n' +
' HandyJSON (= 2.0.2)\n' +
'\n' +
'None of your spec sources contain a spec satisfying the dependency: `HandyJSON (= 2.0.2)`.\n' +
'\n' +
'You have either:\n' +
' * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.\n' +
' * mistyped the name or version.\n' +
' * not added the source repo that hosts the Podspec to your Podfile.\n',
說明：出現(xiàn)此錯誤是因為執(zhí)行 pod install 時找不到指定依賴蔚袍。
處理方法：
請首先確保配置的 pod 庫 name 正確乡范，配置的 version 不高于 pod 庫發(fā)行的最高版本號。
確保未使用存放在私有倉庫的 pod 庫啤咽。
真機運行時在確保配置正確的前提下觸發(fā)重新編譯晋辆。
云打包時請重新打包，或者聯(lián)系管理員宇整。
