跨平台应用开发进阶 (十四) ：uni-app 实现 IOS 原生 APP- 本地打包集成极光推送 (JG-JPUSH) 详细教程

一、前言

在前期博文《跨平台应用开发进阶(十一) ：uni-app 实现 IOS 原生 APP-云打包集成极光推送(JG-JPUSH)详细教程》中讲解了 uni-app 在集成极光过程中如何实现 IOS 原生 APP 云打包。

此篇博文主要讲解 uni-app 在集成极光过程中如何实现 IOS 原生 APP 本地打包。

iOS 离线打包分为三部分：

1. 下载离线打包 SDK 资源;

2. 配置离线打包工程（证书、文件、图标、app 名字等）;

3. 配置模块（例如 Geolocation、push 模块等）;

二、打包前准备工作

• HBuilderX 版本：3.4.7.20220422

• iOS 离线 SDK 版本：3.4.7.20220422

注意⚠️：务必确保 HBuilderX 版本与 iOS 离线 SDK 版本保持一致。

2.1 基本工程配置

1. 点击下载 uniapp ios 离线 sdk。

2. 解压刚刚下载的离线 sdk，可以看到下面这些文件：

用 xcode 打开 HBuilder-Hello 这个项目。

3. 使用 Hbuilderx 生成本地打包 APP 资源。

本地打包代码生成好后，把生成的"__UNI__C1B4407"这个文件夹拷贝到 Xcode 项目目录下的 Pandora -> apps 路径下，替换掉原来的目录。

4. 打开 Xcode 工程 Supporting Files 目录下的 control.xml 文件修改 appid 值，改成和 manifest.json 里面的 appid 一样。

5. 在 dcloud 开发者中心生成 appkey。

appkey 生成方法点击查看。

6. 打开 Hbuilder-Hello-Info.plist 修改 dcloud_appkey，改为上一步申请的 appkey。

点击左侧应用工程根目录，选中 TARGETS 下的 HBuilder 打开工程属性界面，在"Signing & CapaBilities"选项卡下，设置以下几点。

实现 IOS 原生 APP 本地打包，需要在 Xcode 中完成。作为苹果开发者，P12 证书与描述文件必不可少，需要提前准备。

2.2 项目配置

本地打包前，需要以下项目配置项：

• 配置应用标识(Bundle Identifier)

• 配置应用名称

• 配置应用版本名称

• 配置应用版本号

• 配置应用图标

• 配置应用启动界面

• 配置国际化

2.2.1 配置应用标识(Bundle Identifier)

选择左侧应用工程根目录，选中 TARGETS 下的 HBuilder 打开工程属性界面，在 General 下修改 Identity 的值：

其中,

• Bundle Identifier 为苹果的 AppID，必须与应用发布时配置的 Profile 关联的 AppID 一致；

• Version 为应用版本号，在 App Store 中显示的版本号，推荐与 manifest.json 中 version 下的 name 值一致；

• Build 为编译版本号，App Store 判断升级使用，推荐与 manifest.json 中 version 下的 code 值一致。

2.2.2 配置应用名称

1、在打开的原生工程中，点击工程的 targets 和点开 manifest 文件，然后将 manifest 文件里的“name”字段的内容和原生工程里的 Display Name 写成一样。

注意⚠️：manifest 文件里的”name“ 对应的是 HBuilderX 打开的工程里的“基础配置”里的应用名称。如下图红色框所示：

2.2.3 配置应用版本名称

在打开的原生工程中，点击工程的 targets 和点开 manifest 文件，然后将 manifest 文件里的“version”字段里的“name”的内容 和原生工程里的 Version 的写成一样。注意，manifest 文件里的“version”字段里的“name” 对应的是 HBuilderX 打开的工程里的“基础配置”里的应用版本名称。

2.2.4 配置应用版本号

在打开的原生工程中，点击工程的 targets 和点开工程里的 manifest 文件，然后将 manifest 文件里的“version”字段里的“code”内容和原生工程里的 Build 写成一样。

注意⚠️：manifest 文件里“version”字段“code” 对应的是 HBuilderX 打开的工程里的“基础配置”里的应用版本号。如下图红色框所示：

2.2.5 配置应用图标

点击 project->target->General->App Icons and Launch Images->App Icons Source 项右侧小箭头。

在新开页面根据提示将对应尺寸的应用图标拖入到虚线框中即可。

2.2.6 配置应用启动界面

1. 按下图方法配置 Launch Screen File，这样配置之后启动界面就会是设置的 LaunchScreen.storyboard。

2. 使用官方已经制作好的 storyboard，官方提供了 2 个 storyboard，一个是图标、名称在上方的；另外一个是图标、名称在下方的(这种的 LaunchScreen.storyboard 主要是适配用户配置广告后，使其启动时不会有视觉上的跳跃感，增加用户体验)。

注意⚠️：在使用 Launch Screen File 方式作为启动界面时，需要把一张或几张清晰的图标拷贝到工程的根文件夹下并引入到工程中，用来给启动界面加载图标。如果拷贝过去的图标不清晰，会导致启动界面上出现图标不清晰、模糊的现象。

3. 制作 LaunchScreen.storyboard(这个 storyboard 的名称是可以自定义的)，如果想自定义 LaunchScreen.storyboard， 这需要你会原生知识，知道怎样创建 Launch Screen File，知道怎样在 storyboard 中布局视图，设置约束等。

注意⚠️：

这里的 storyboard，不是普通的 storyboard；

配置了广告之后，如果自定义的 LaunchScreen.storyboard 约束没设置好，会有启动页到广告页跳跃的视觉效果。

2.2.7 配置国际化

2.2.7.1 内容相关的国际化

离线打包时如果弹出提示框且内容为：“HTML5+ Rumtime D”时，需要在打包的原生工程里配置国际化如何配置。

2.2.7.2 Info.plist 的国际化

新建一个 .strings 文件，叫做 InfoPlist.strings（文件名必须是这个）然后点击右侧的 localized， 再在工程导航界面，选择 InfoPlist.strings 文件，比如添加 key 为 CFBundleDisplayName，值为应用名字（HBuilder 你好），InfoPlist.strings(English)为英文系统,Simplified 为中文简体系统。

另外，对 HBuilderX，manifest.json 文件里，“模块权限配置”项中的“iOS 隐私信息访问的许可描述”栏下的隐私权限描述国际化，可以这样配置，如下：

1. 将 manifest.json 页面切换到“模块权限配置”项，在“iOS 隐私信息访问的许可描述”栏下配置应用需要使用到的隐私描述信息：

2. 

3. 输入完成后切换到代码视图，uni-app 项目在"app-plus"->“distribute”->“ios”->"privacyDescription"节点下可看到输入的内容：

3. 将"privacyDescription"节点下的 key（NSPhotoLibraryUsageDescription）和值按下图的方式拷贝到 InfoPlist.strings 下对应的语言文件里去。

三、打包

以上项目配置工作完成后，就可以开展本地打包了。

3.1 证书导入

1. 导入 iOS 证书 p12 到钥匙串，双击 p12 文件，登录，导入证书。

编译设备选择 Generic iOS Device 或者 Any iOS Device。

注意⚠️：选择其他模拟器是不能 Archive 的。

2. Xcode 工具条 Product 下点击 Archive。

3. 如果弹出下面框，输入本机密码，始终允许。

4. 点击 Export。

5. 本地联调选择点击 Ad Hoc。

点击 Next。

选择证书,点击 Next。

最后点击导出，选择指定位置即可。

四、如何用离线打包工程制作自定义调试基座

自定义调试基座是使用开发者申请的第三方 SDK 配置生成的基座应用，用于 HBuilder/HBuilderX 开发应用时实时在真机/模拟器上查看运行效果。

1. 在打包原生工程里找到 control.xml 文件，在 HBuilder 节点里查看是否有这 2 个： debug="true" syncDebug="true" 配置(注意-打 AppStore 包的时候，这个配置需要去掉，否则会导致热更新失败！)，没有的话增加上，然后保存。

2. 确保 Xcode 工程的 Bundle identifier 不为 io.dcloud.HBuidler。

3. 在原生工程里找到 info.plist 文件并增加一项，如下图：

4. 确保原生工程里 Pandora 文件夹下的 apps 文件夹里只有一个文件夹（文件夹的名称和里面的 manifest 的 id 值相同）;

5. 确保 control.xml 文件里的 appid 的值和 apps 目录下的第一个文件夹的名称一致;

6. 确保 HBuilderX 里要调试的代码的 appid 和 control.xml 的 appid 值一致;

7. 使用 Xcode 的 Product 下的 archive 打包，然后生成 ipa，并把 ipa 名称命名为：iOS_debug.ipa;

在 js 工程里主目录下新建一个名称为 unpackage 的文件夹（如果有不用新建），再在 unpackage 文件夹下新建一个名称为 debug 文件夹，并把生成的 iOS_debug.ipa 包放入 debug 文件夹下。

在 HBuilderX 里，找到之前 appid 相同的 js 工程准备调试，点击“运行” --“运行到手机或模拟器“--“使用自定义基座运行（iOS）”，等待连接成功之后就可以了。

运行

连接手机，编译运行，如果 App 成功跑起来了，说明原生工程配置完成。

注意⚠️：iOS 仅支持真机运行自定义基座，不能使用 xcode 模拟器运行自定义基座！

五、遇到的问题及解决措施

5.1 IOS 签名证书 p12 无法导入

未复现，待复现后再给出解决方案。

5.2 描述文件不包含当前设备

Xcode 本地离线打包，选择描述文件后，报如下错误信息：

Provisioning profile "****" doesn't include the currently selected device "huaqiang 的 MacBook Air" (identifier 00008103-000964343AD2001E).

被此问题折腾了 2 天，后来细心阅读文档，认真操作后发现是选择目标编译设备是默认选择了 Mac 设备导致，正确的选项应该是 Any iOS Device!

5.3 “HBuilder” requires a provisioning profile. Select a provisioning profile in the Signing & Capabilities editor.

出现以上问题是由于 Signing(Release)部分需要导入描述文件。

5.4 ‘PDRCore.h’ file not fond

出现以上问题是由于 HBuilderX 版本与 iOS 离线打包 SDK 版本不一致造成的，一定要确保 HBuilderX 版本与 iOS 离线打包 SDK 版本保持一致。

5.5 请确保自定义基座的 iOS 证书已添加 iOS 设备的 UDID

出现以上问题的原因是 Devices 中未添加联调设备 UDID。

解决方案，使用开发者账号登陆 app developer。增加设备的 UDID 到 Devices 中。

如何查看设备的 udid?

Unique Device Identifier (识别码)，使用 safari 浏览器打开https://www.pgyer.com/tools/udid，下载描述文件，然后去设置里面点击已下载描述文件安装，就可以看到自己的 udid。

增加之后下载新的 Provisioning Profiles。

在 xcode 中导入新的 Provisioning Profiles，ok，不报错了，可以放心的打包了。

介绍一下 Provisioning Profiles 文件：

Provisioning Profiles，该文件将 appID，开发者证书，硬件 Device 绑定到一块儿，在开发者中心配置好后可以添加到 Xcode 上，也可以直接在 Xcode 上连接开发者中心生成，真机调试时需要在 PP 文件中添加真机的 udid。