uni-app各环节版本兼容性说明

发布于 1周前 作者 sinazl 来自 Uni-App

uni-app各环节版本兼容性说明

此文档停止维护，最新的文档见：uni版本说明

uni-app是一个跨度很大的产品，支持多种开发ide、HBuilderX有正式版和alpha版、支持cli和普通项目、支持很多端、有云打包app和本地打包app、编译器模式支持老的模板模式和新的自定义组件模式。

它们都会升级，如果出现一个升级、另一个未升级的情况，可能会运行异常。

正常情况，HBuilderX升级后，其自带的app运行基座、uni-app编译器、云打包配套引擎会同步升级。但在开发者使用cli创建项目、使用自定义基座、使用5+sdk离线打包时，就需要手动维护版本更新。

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

  • 如果你使用cli创建项目（即项目根目录是package.json），不管用什么ide，即便是用HBuilderX，切记cli项目的编译器是在项目下的，HBuilderX不管怎么升级都不会影响编译器版本。你需要手动npm update来升级编译器。以及如果你想要安装less、scss等预编译器，也需要自己npm安装在项目下，而不是在HBuilderX的插件管理里安装。

  • 如果你使用离线打包，请注意HBuilderX升级后，真机运行基座和云打包对应引擎跟随HBuilderX升级，而你的sdk需要手动升级。sdk的版本升级一般滞后HBuilderX正式版升级一两天。在这里下载最新版

  • 如果你使用自定义基座，之前制作的自定义基座是不会跟随HBuilderX升级的，升级HBuilderX后你应该重新制作新版自定义基座。

  • 如果你使用wgt升级，新版HBuilderX编译的wgt，运行到之前的runtime上，一定要先测试好，看有没有兼容性问题。如果有问题，就不要wgt升级，整包升级。

  • 考虑到向下兼容，uni-app编译器在升级为新的自定义组件模式后，同时保留了对老编译模式的向下兼容。 在HBuilderX alpha版中，App端一定会使用新编译器，不理会manifest配置。 在HBuilderX 正式版中，新创建的项目会使用新编译器，老项目不会强制使用，而是开发者自己在manifest里配置开启。

  • 如果你使用其他ide开发uni-app，会经常因为拼错单词而运行失败，因为经过webpack编译一道，很多错误反应的不够直观，排错时间很长，不如从开始就依赖有良好提示的HBuilderX，避免敲错单词。

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

  1. HBuilderX或cli版本与云端版本完全一致；
  2. HBuilderX或cli版本的大版本号与云端一致时，使用该大版本的最新版本；如打包机上有[3.92, 3.93, 3.99, 4.01, 4.10]，则3.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。

很多人在报问题时不说清自己的情况，导致别人给出错误的回答。 很多人在搜问题时没注意看条件，导致使用了并不适用于自己的错误方案。

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

版本列表

产品 版本
uni-app编译器 版本列表
真机运行基座 版本列表
云打包引擎 版本列表

Harmonyos Next教程
1 回复

在开发uni-app应用时，确保各环节版本兼容性至关重要。以下是一个简要的代码案例和说明，旨在帮助开发者理解和处理uni-app在不同环节（如开发环境、编译环境、运行时环境等）的版本兼容性。

1. 开发环境版本兼容性

确保你的开发环境（如HBuilderX、Node.js等）与uni-app支持的版本相匹配。

示例：检查HBuilderX版本

// 示例代码：在命令行中检查HBuilderX版本（假设已安装并配置环境变量）
const { exec } = require('child_process');

exec('hbuilderx --version', (error, stdout, stderr) => {
  if (error) {
    console.error(`执行出错: ${error}`);
    return;
  }
  console.log(`HBuilderX 版本: ${stdout.trim()}`);
  // 可以在此处添加版本兼容性判断逻辑
});

2. 编译环境版本兼容性

uni-app支持多种编译目标（如小程序、H5、App等），确保你的编译配置与目标平台的版本要求相匹配。

示例：配置编译目标

// pages.json 中的编译配置示例
{
  "globalStyle": {
    "navigationBarTextStyle": "white",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#000000",
    "backgroundColor": "#ffffff"
  },
  "condition": { // 模式配置，仅开发时生效
    "current": 0, // 当前激活的模式（list 的索引项）
    "list": [
      {
        "name": "test", // 模式名称
        "path": "pages/index/index", // 启动页面，必需
        "query": "interval=4000&autoplay=false" // 启动参数，可选
      }
    ]
  },
  "mp-weixin": { // 微信小程序特有配置
    "appid": "xxxxxxxxx", // 必填，小程序的appid
    "setting": {
      "urlCheck": false
    }
  }
}

3. 运行时环境版本兼容性

确保你的应用在不同平台（如iOS、Android、微信小程序等）的运行时环境中能够正确运行。

示例：条件编译处理不同平台

// 在JavaScript中根据平台做条件编译
if (process.env.PLATFORM === 'h5') {
  // H5平台特有代码
  console.log('运行在H5平台');
} else if (process.env.PLATFORM === 'mp-weixin') {
  // 微信小程序特有代码
  console.log('运行在微信小程序平台');
}

// 在Vue组件中使用平台特有样式或功能
<template>
  <view>
    <text v-if="$mp.system.platform === 'ios'">iOS平台特有内容</text>
    <text v-else>其他平台内容</text>
  </view>
</template>

通过上述代码示例，开发者可以更好地理解和处理uni-app在不同环节中的版本兼容性。确保开发、编译和运行时环境的版本匹配，是构建稳定、可靠应用的关键。

回到顶部