YonBuilder移动开发基础教程—

1 使用场景

在项目开发中，我们经常会遇到一种场景，对于一些已经上架应用市场对外发布的应用，我们需要修改其中部分页面的部分内容样式或功能逻辑，通常的做法是我们修改后，重新编译一个新的版本，然后提交应用市场去发布一个更新的版本。但是有些时候，我们可能会遇到以下的场景，不适合正常的发版操作：

场景1：项目内需要修改的这个问题比较小（比如出现了错别字），不值得去单独发布一个新的版本，但是不改的话，又让人看着很别扭很难受；
场景2：项目产生一个突发的恶性Bug，需要马上修复避免产生重大损失（比如支付订单有漏洞，随时可能会被人薅羊毛），此时发新版本需要应用市场审核，时间上来不及，晚一点都有可能造成重大损失；

遇到上面的场景，我们就可以使用「云修复」功能来处理解决问题了。云修复的具体功能，就是将你需要修改的页面，编辑修改好后，提交一个widget修复包到云端平台。已经安装在用户手机上的APP应用，通过引擎内置的云修复机制，就可以自动获取并下载你提交的云修复包，自行进行页面内容的修复替换，从而实现不发版的解决应用内Bug的修改。

云修复功能在具体的运营项目中非常实用，我们开发者一定要了解和掌握该功能的具体操作使用。

2 操作流程

云修复需要两个产物和一个操作，两个产物具体就是待修复正式版APP和修复补丁的zip文件，一个操作就是在云平台的「运营管理」- 「版本管理」-「云修复」页面，提交补丁文件并发布。下面我们来进行具体的操作流程演示及说明讲解。

2.1 配置开启云修复

访问云端开发者中心 -> 登录进入「工作台」-> 在「移动应用开发」版块的应用列表选择具体应用进入应用详情页 -> 切换到端设置面板页，将该页面内「云修复」配置选项设置为开启。

这个配置是云修复功能的前提条件，如果不开启，则待修复的APP将不会收到云修复的消息通知。

在这里插入图片描述

PS: 原本的开发流程是在应用项目代码的 config.xml 文件中，通过修改 smartUpdate参数来开启或关闭云修复。不过平台更新后，云端工作台的这个设置优先级要高于 config.xml 中的配置，也就是说一旦两者设置的有冲突，是以网站工作台的设置为准的。所以开发者特别是之前已经习惯了旧的开发流程的开发者一定要注意。

在这里插入图片描述

关于 config 配置参数的更多介绍，可以点击config.xml应用配置说明查看

注意！！！：这个云修复的配置修改后，是需要重新编译新版本才会生效的。也就是说如果你之前发布的版本在编译时云修复是关闭的，那么及时现在你开启了云修复功能，那个旧版本的APP也是无法收到云修复通知的，只有重新编译新的版本才可以。

2.2 编译用于演示的正式版

本步骤主要用于生成一个用于测试的新版本APP，在实际场景中，对应的就是那个存在问题，需要去修复的已发布APP版本。

具体编译操作，在应用详情页切换到「移动打包」面板页，选择对应的版本进行编译即可。编译完成后，在手机端安装该版本的应用。

在这里插入图片描述

注意！！！：这里需要提醒一下，云修复功能只会在正式版本生效，所以我们需要编译正式版才行。

2.3 创建云修复补丁文件

2.3.1 云修复原理简述

这里先简单说一下云修复的底层实现逻辑，方便开发者快速的理解该功能的实现原理。

在APP启动后，引擎会请求云修复的相关api接口，查询当前APP版本是否存在云修复补丁，如果存在则引擎会进行更新下载修复补丁文件。下载完成后，引擎会将补丁文件解压，并替换到原本项目中同路径位置的同名文件（这里的替换操作不是简单的覆盖，不过最终实现的效果差不多，所以大家这样理解就可以）。这样就实现了同名文件的替换，从而完成了类似热修复效果的云端修复功能。

这里需要注意和APP重新启动有关的两点，即云修复的触发和生效，具体如下：

触发：云修复的查询只有在APP启动后才会触发，在APP运行期间，引擎不会频率的轮询查询云修复更新补丁，所以想测试云修复功能的触发，一定要重新启动APP才可以；
生效：云修复成功后，因为当前旧的文件已经被运行中的APP占用，所以需要等待APP重新启动后，新的替换文件才会生效。也就是说云修复完成后，必须重启新的补丁文件才会生效；

2.3.2 云修复补丁文件结构说明

云修复补丁文件，是一个包含 widget 文件夹的zip压缩包。它的结构的最外层是名称为 widget 的文件夹，里面存放的就是具体需要修复的补丁文件。这里需要说明的是，补丁文件在 widget 文件夹里的路径位置一定要与APP源码的文件位置保持一致，并且文件名称相同，才能实现替换修复，否则即使云修复操作完成了，引擎也无法实现补丁文件的修复。

为了方便理解，下面展示一下项目源文件结构和云修复补丁的文件结构示意图（假设准备修改项目中html文件夹下的main.html文件内容）

在这里插入图片描述

再次画一下重点：

最外层的文件夹名称固定为 widget；
widget 文件夹内部待修复的文件结构要与原编译版本的源码结构保持一致，及文件路径和文件名都要保持一致。比如上图，虽然修改的是 main.html 文件，但是 html 文件夹也是需要创建出来的；
上图是指展示了一个单独文件的云修复，多个文件的云修复也是如此，将修改后的文件按原文件结构路径放置在 widget 文件夹内对应的位置；
压缩文件时，包含 widget 文件夹整体压缩，不要只压缩文件夹内部的文件。

2.3.3 关于stml文件的特殊处理规则

stml 文件是 avm 框架的专属文件格式，该文件在编译APP版本前，内部会有一个 build 的编译过程，最终安装到用户手机的APP里时，并不存在扩展名为 stml 格式的文件，所以对于stml的文件，我们需要单独特殊处理。

具体处理方法如下：

修改项目文件：在 YonStudio 开发工具里，修改文件内容并保存；
编译项目文件：在顶部菜单「项目」的下拉菜单中选择「编译项目」；
复制编译后的目标文件：编译完成后，在项目文件夹下会有一个.bin的隐藏文件夹（如下图），里面已经将stml文件都编译成了同名的js文件。我们只需要将需要修复的stml文件的同名js文件复制，并粘贴到widget修复补丁文件夹内的对应位置即可。

在这里插入图片描述

举例说明：假如我们准备修复 pages/main/main.stml 文件，则编译项目文件后，复制 .bin/main/main.js 文件到 widget文件夹内的 pages/main 目录内，最终该文件在云修复补丁文件的位置路径是： widget/pages/main/mian.js

2.3.4 模拟制作一个云修复补丁

1.打开 YonStudio 开发工具，导入项目代码（新项目可以直接通过顶部菜单的项目-导入项目-云端检出）
2.修改需要云修复的目标文件内容，这里我们修改一下 html文件夹下的 main.html 文件,例如我们把页面内30行的 label 标签内的内容文字“Hello APP”修改成“Hello, world! 云修复测试成功！”

```
<body>
    <label>Hello, world! 云修复测试成功！</label>
    <div id='sys-info'></div>
</body>
```

3.保存文件

4.创建一个空的 widget 文件夹，并在 widget 文件夹内再创建一个空的 html 文件夹，然后将我们修改后的 main.html 文件，COPY到新的 widget/html 文件路径内。

在这里插入图片描述

5.将 widget 文件夹压缩为名称为 widget.zip 的压缩文件（macOS系统直接右键 widget 文件夹，就有压缩操作的命令；windows可以使用第三方的压缩软件完成压缩）

在这里插入图片描述

至此，我们已经完成了云修复补丁压缩文件的制作。

2.4 发布云修复

完成了云修复补丁的制作后，就到了最终的发布云修复环节，具体发布流程如下：

登录开发者中心工作台，进入应用详情页，切换到「运营管理」-「版本管理」-「云修复」面板页
按页面内容要求填写相关的参数值，点击「更新」按钮，及完成了云修复补丁的发布。

注意：这里为了方便查看验证云修复是否生效，我们选择「修复方式」为「提示修复」，正常在生产环境中，我们通常都是进行一些Bug类微小问题修改，为了避免引起用户的反感，通常建议选择「静默修复」。

2.5 验证云修复结果

真机验证：在手机端重新启动上面新安装的APP，如果顺利的话，APP启动后，页面内会弹出云修复更新的提示弹窗。
在云端的应用详情页，切换到「运营管理」-「版本管理」-「云修复」面板页，在底部的修复记录列表中，可以通过「修复数」字段查看当前版本已经成功修复的客户端数量。

3 注意事项

1.开发者需要根据自己的业务逻辑需要，认真考虑自己的项目是否需要开启云修复功能。因为在某些应用平台是禁止使用类似云修复的这类远程热修复效果的功能的，特别是iOS，如果开启了云修复功能，有可能商家审核时被拒。所以建议在应用上架的第一个版本，轻易不要开启云修复，如果有需要，以后的升级迭代版本再开启。

2.云修复功能的主要目的是进行微小功能代码的修复，所以应尽量避免widget修复补丁包过大，否则可能会引起APP静默下载失败，导致整个云更新执行失败。

3.尽可能的降低云修复的使用频率，非必要不使用。如果频繁的使用云修复，在某些平台上容易被封号。

4.云修复生效的前提条件，当怀疑云修复未生效时，可以参考这些条件进行分析排查：

如果修复的目标版本存在可升级版本，即更高级别的已发布版本（就是通过云端-「运营管理」-「版本管理」-「版本更新」发布了新的版本），无论你这个版本是不是强制更新，版本更新是开启还是关闭，针对当前低版本的云修复都不会生效；
云端发布的widget.zip压缩包的下载链接必须有效，如果用户自己填写的是第三方平台的下载地址，可以使用浏览器测试下是否可以下载；
云端发布云修复补丁后，对应的用户手机端需要重启启动后，才会执行云修复更新检测，如果用户当天没有启动过手机或者是在发布云修复之前已经启动了APP，那么是不会触发云修复更新的，所以开发者发布云修复后，不要着急马上看效果，需要让「子弹飞一会」；
云修复特别是选择了静默修复时，不光用户无感，我们开发者也是没法判断修复是否成功的。因为静默更新是没有任何提示，同时执行静默更新时，客户端APP的引擎需要一定的时间去下载云修复补丁的压缩文件（这个下载过程时间的长短，会受手机环境当时的网速和手机性能的影响变化），如果在下载的过程中用户关闭了APP（或者断网了），则云修复失败，那么就需要等待下次用户再重新启动APP，才会触发新一轮的云修复更新流程。
用户的APP底层更新完云修复文件后，需要用户关闭APP，重新启动后，新的补丁文件才会生效。
由于静默更新，很难判断更新内容是否成功，所以为了加强判断，如果是修复文件样式这类需要一定规则才会生效的功能代码时，建议在一个不起眼的地方修改一点点文字内容，用于当云修复不生效时，我们去判断到底是云修复操作未生效，还是写的样式代码有问题导致的修复未生效。（别小看这一小点，在一些场景下会很实用）