# uni版本说明

本文梳理了DCloud的HBuilderX、uni-app、uniCloud等产品的版本概念。这里的uni-app包含了uni-app x。

HBuilderX有正式版、alpha版、dev版。

dev版仅限受邀内测,对外开放的版本仅包含alpha和release正式版。

DCloud在每次更新发版时,随着HBuilderX的升级,会一起发布uni-app的本地运行插件、uniCloud的本地运行插件。并且会同时升级app的云打包机。

默认情况下,它们的版本号是一样的。

# 版本命名方式

在HBuilderX 3.9以前,采用的是3段式版本号规则,大版本、小版本、补丁版本,如3.8.12。

这个版本号,在uni-app中使用uni.getSystemInfo可以获得。具体属性是uniRuntimeVersionuniCompileVersion,类型是字符串。

在HBuilderX界面显示时,还会在末尾再增加一段发版日期,如3.8.12.20230817。上述api不会返回末段日期。

但是这种多段式字符串类型的版本号,不方便做比较。获取到uniRuntimeVersion后,需要再分割三段后分别比较。

并且字符串3段式中,3.9的下一个版本可以是3.10。这个情况又容易被误解,因为3.10很可能被误解为3.1,它和3.9到底谁大就容易混淆。

所以从HBuilderX 3.9起,取消了字符串三段式版本,改为了数字方式,如3.91。具体规则:

  • 小数点后面保留2位。
  • 小数点之前代表大版本。小数点后第1位小数代表小版本,第2位小数代表补丁版本。
  • 补丁版本可能不存在,即第2位小数是0,此时可以简写,去掉数字末尾的0。比如3.90就是3.9。
  • 数字逢十进一,不存在某位数大于9的情况。比如3.99之后,还想发一个补丁版本,只能发成4.0。

基于向下兼容的考虑,uniRuntimeVersionuniCompileVersion仍然是字符串。

但在uni-app x的uni.getAppBaseInfouni.getSystemInfo中, 返回值新增了2个属性,uniCompilerVersionCodeuniRuntimeVersionCode,这2个是数字类型,可以直接用于比较。

另外,从HBuilderX 3.9起,条件编译也可以按版本号来编译,比如低版本编译成这样、高版本编译成另一个样子。这种条件编译也可以直接使用比较运算符来比较了。详见

# 编译器、运行时、打包机的版本差异

uni-app有编译器和运行时,它们之前的版本在某些情况可能不一样,所以有uniCompileVersionuniRuntimeVersion的区别,分别表示编译器版本和运行时版本。

如果正常使用HBuilderX 最新版进行云打包,不会出现不一致的情况。但开发者的需求较多,比如cli创建项目、在其他ide中开发、离线打包,就会造成DCloud无法控制的版本差异。

比如用3.91的编译器编译代码后运行在3.92的运行时上。

DCloud无法保障这些交叉版本互相之间的兼容性,虽然有可能正常使用,但DCloud采取的策略是:"发现编译器和运行时版本不匹配,就会弹框报警"。

发生告警不代表一定不能运行,只不过需要开发者自行对稳定性做保障。只要开发者自测后发现你的应用可以正常使用,就可以在manifest里配置关闭告警。详见

还有一个经常遇到的误报是:“我的HBuilderX已经是最新版了,升级日志里提到的已解决问题,为什么没有仍然存在?”,其实有的是因为cli项目下编译器是旧的、有的是因为本地打包的sdk是旧的,有的是因为自定义基座的版本是旧的。

那么何时会产生差异?

# cli方式创建项目造成的差异

当使用HBuilderX创建项目时,uni-app的编译器在HBuilderX目录的plugin下,跟随HBuilderX升级而同步,并且对所有HBuilderX创建的项目生效。

当使用cli创建项目时,uni-app的编译器在项目下。cli是否升级,是开发者自主决定的。

即便是ide仍然使用HBuilderX,HBuilderX不管怎么升级都不会影响编译器版本。你需要在项目下手动npm update来升级编译器。

以及如果你想要安装less、scss等预编译器,也需要自己npm安装在项目下,而不是在HBuilderX的插件管理里安装。

# wgt热更新造成的差异

wgt升级意味着编译wgt的HBuilderX版本和手机端已经存在的包的版本可能不匹配。

比如你使用HBuilderX 3.91 开发了第一版应用,并把安装包推给了你的手机用户,那么这些包的uniRuntimeVersion就是3.91。

后续你升级HBuilderX 为3.92,编译了下一版的wgt和apk,那么

  • 编译为apk时,新的apk里uniCompileVersionuniRuntimeVersion都是3.92
  • 编译为wgt时,此时不存在客户端,仅有前端资源包,wgt的uniCompileVersion是3.92

如果要把uniCompileVersion是3.92的wgt包,热更新给uniRuntimeVersion为3.91的老用户,这些用户的客户端引擎没有升级,仅仅是前端资源热更新,就会因为3.92和3.91不匹配,默认就会弹框报警。

此时需要你提前测好新的wgt在老版客户端引擎上的兼容性,测试没问题时才能热更新,并在manifest里配置取消弹框。

如果测试有问题,且在前端层面无法处理,那就不能使用wgt更新,需要整包更新。或者回退HBuilderX版本,使用老版来编译wgt。

# 离线打包造成的差异

离线sdk是独立于HBuilderX的下载的,每个sdk都有版本号。其实就是uniRuntimeVersion

而HBuilderX的版本决定了uniCompileVersion,如果HBuilderX编译的wgt和离线sdk的这2个版本不匹配,也会弹框报警。

解决方案同上,或者保持版本一致性,或者自己测试发现兼容性没有问题,然后在manifest配置忽略报警。

# 自定义基座造成的差异

如果你使用自定义基座,该基座的apk是在项目下的unpackage目录中的。每次升级HBuilderX时,之前制作的自定义基座是不会跟随HBuilderX升级的,升级HBuilderX后你需要重新制作新版自定义基座。

# 云打包机的引擎版本说明

HBuilderX已经有几百个版本了,因资源有限,不可能都每个版本都提供云打包机。

自HBuilderX 3.9起,云打包机版本保留了多个可用的版本,具体可用的云端打包版本参考下方的版本对应表。 打包时,服务端会根据用户使用的HBuilderX或cli版本去匹配最合适的打包版本,规则如下(匹配优先级从高到低):

  1. HBuilderX或cli版本与云端版本完全一致;
  2. HBuilderX或cli版本的大版本(如3.9x,4.0x, 4.1x等)与云端一致时,使用该大版本的最新版本;如打包机上有[3.92, 3.93, 3.99, 4.01, 4.10],则HBuilderX3.91使用3.99云端打包版本。
  3. 当以上规则无法匹配时,使用云端最新版本。

举个例子: 当云打包机有以下版本[3.7.11, 3.8.12, 3.92, 3.93, 3.99, 4.01, 4.15]可用时:

  • 如果HBuilderX使用3.7.11, 3.8.12, 3.92, 3.93, 3.99, 4.08, 4.15这些版本时,版本号完全匹配,直接使用同版本号打包机;
  • 如果HBuilderX使用3.7.3,则云端打包机使用3.7.11版本;HBuilderX使用3.91,则云端打包机使用3.99版本;HBuilderX使用4.01版本,则云端打包机使用4.08版本;
  • 如果HBuilderX使用3.7以下的版本,则云端打包机使用最新版本4.15。

# 版本列表

下面提供 uni-app 开发中各产品的版本对应表:

想避免版本兼容问题,还是推荐使用HBuilderX完成一切工作,包括创建项目、运行编译、云打包app。 因为在这套体系里,官方会对很多常见的问题做出提醒和引导,减少问题的概率。随着HBuilderX的升级,uni-app编译器、真机运行基座、云打包引擎都会升级。