在 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)系管理員宇整。