1. 为什么版本号管理是跨端开发的第一道坎做跨端开发尤其是用uni-app这种“一套代码发布到多个平台”的框架开发者很容易陷入一种错觉代码逻辑是统一的那么获取一些基础信息比如应用版本号也应该是统一的。但现实往往第一个巴掌就扇在这里。我接手过不少从其他开发者那里转过来的uni-app项目经常看到在App.vue的onLaunch里试图用一个uni.getSystemInfo就拿到所有端的版本号结果在H5和小程序上要么报错要么拿到的是浏览器或微信的版本根本不是自己应用的版本。这看似是个小问题却直接关系到应用的核心逻辑。版本号用来做什么用户端它展示在“关于我们”页面是基础信息开发端它是灰度发布、强制更新、AB测试、数据统计、问题回溯的基石。想象一个场景你发布了一个新版本App修复了某个紧急Bug同时在H5和小程序也更新了功能。如果没有准确获取各端自身版本号的能力你的更新提示逻辑就会乱套——可能App提示更新了H5却毫无反应或者反过来。用户在不同端看到的信息不一致体验会非常割裂。所以搞清楚如何在uni-app中分别获取原生App编译为apk/ipa、H5部署在服务器、微信小程序这三个主要终端的应用版本号是跨端项目稳健起步的必修课。这不是一个API能搞定的它需要你理解每个平台的运行机制和配置文件的差异。下面我就结合实际的踩坑经验把这三个平台的版本号获取方法、背后的原理以及那些官方文档没细说的“坑点”给你彻底讲明白。2. App端深入manifest.json与原生编译产物在uni-app项目中App端的版本号管理核心在于两个文件manifest.json和原生平台的特定配置文件。很多新手以为版本号只在打包时设置其实它在运行时的获取逻辑也值得深究。2.1 版本号的定义与优先级首先打开你项目根目录下的manifest.json文件。在app-plus节点下如果是Vue3项目也可能是app节点你会找到版本相关的配置app-plus: { versionName: 1.2.0, versionCode: 120, // ... 其他配置 }这里有两个关键字段versionName(版本名称)展示给用户看的字符串如“1.2.0”、“2.1.5-beta”。它遵循主版本号.次版本号.修订号的常见约定。versionCode(版本代码)一个整数用于内部比较版本新旧。每次发布新版本这个数字必须递增。Google Play 和国内安卓市场主要依据这个值来判断是否升级。注意versionName和versionCode在manifest.json中配置的是基准值。当你使用HBuilderX进行云打包或离线打包时最终生成的原生安装包APK/IPA的版本信息以打包时传入的参数或可视化界面中的设置为准。manifest.json中的值更像是默认值或模板。这是一个常见的混淆点。2.2 运行时获取plus.runtime.getProperty在App运行后我们需要在JavaScript代码中动态获取这些信息。这需要调用HTML5即5 Runtime的API。uni-app对这部分API进行了封装可以通过uni.getSystemInfo获取一些但获取应用自身版本号必须使用plus.runtime.getProperty。下面是一个在App.vue的onLaunch中安全获取版本信息的示例// 在 App.vue 中 export default { onLaunch: function() { // 判断平台仅App端执行 // #ifdef APP-PLUS const app this; // 等待plus环境ready这是一个关键细节 document.addEventListener(plusready, function() { const platform uni.getSystemInfoSync().platform; // 再次确认是App环境虽然已经在#ifdef里 if (platform android || platform ios) { plus.runtime.getProperty(plus.runtime.appid, function(inf) { console.log(App版本名称:, inf.version); // 对应 versionName console.log(App版本代码:, inf.versionCode); // 对应 versionCodeiOS上可能为undefined console.log(App标识:, inf.appid); // 将信息存入Vuex或全局变量供其他页面使用 app.$store.commit(setAppVersionInfo, { versionName: inf.version, versionCode: inf.versionCode || 0, // iOS处理 appid: inf.appid }); // 示例检查更新逻辑 app.checkAppUpdate(inf.version, inf.versionCode); }); } }); // #endif }, methods: { checkAppUpdate(currentVersionName, currentVersionCode) { // 这里实现你的检查更新逻辑比如请求服务器接口 uni.request({ url: https://your-api.com/check-update, data: { platform: uni.getSystemInfoSync().platform, version: currentVersionName, versionCode: currentVersionCode }, success: (res) { if (res.data.hasUpdate) { // 提示用户更新 uni.showModal({ title: 发现新版本, content: 新版本 ${res.data.newVersion} 已发布是否立即更新, success: (modalRes) { if (modalRes.confirm) { // Android通常直接下载apk安装iOS跳转App Store plus.runtime.openURL(res.data.downloadUrl); } } }); } } }); } } }关键点与避坑指南环境判断务必使用// #ifdef APP-PLUS条件编译将代码包裹因为plus对象只在App环境存在在H5或小程序环境直接调用会报错“plus is not defined”。等待plusreadyApp启动后5 Runtime环境需要一点时间初始化。在onLaunch中直接调用plus.runtime.getProperty可能失败。最稳妥的方式是监听document的plusready事件或者使用setTimeout进行简短延迟不推荐不优雅。iOS的versionCode在iOS平台plus.runtime.getProperty回调的inf对象中versionCode字段通常是undefined。因为iOS的CFBundleVersion构建版本号在WebView层不一定暴露。如果你需要iOS的构建号可能需要通过uni-app原生插件来获取或者依赖versionName对应CFBundleShortVersionString进行版本比较。热更新与版本号如果你使用了uni-app的wgt热更新请注意热更新包的版本号也需要在manifest.json中配置并且热更新不会改变原生安装包的versionCode。你的检查更新逻辑需要同时考虑整包更新和热更新两套规则。3. H5端从package.json到构建环境的变量注入H5端的版本号获取逻辑与App端截然不同。H5项目运行在浏览器中没有“安装包”的概念它的版本本质上就是你当前部署在服务器上的前端资源包的版本。3.1 版本信息的来源与管理最普遍的做法是将版本号定义在package.json文件中与你的npm包管理保持一致// 项目根目录/package.json { name: my-uni-app, version: 1.2.0, // ... 其他依赖和脚本 }但是package.json里的版本号是在Node.js环境中读取的浏览器中的JavaScript无法直接访问这个文件。因此我们需要在构建build过程中将这个版本号“注入”到前端代码可以访问的地方。3.2 构建时注入以Vue CLI模式为例如果你使用HBuilderX创建的项目它内部使用了webpack进行构建。我们需要通过配置将版本号作为一个全局变量或环境变量暴露出来。方法一使用DefinePlugin注入全局常量在项目根目录创建或修改vue.config.js文件如果不存在则创建// vue.config.js const packageJson require(./package.json); module.exports { // ... 其他配置 chainWebpack: (config) { // 向所有编译环节注入全局常量 config.plugin(define).tap((definitions) { definitions[0][process.env].VERSION JSON.stringify(packageJson.version); definitions[0][process.env].APP_NAME JSON.stringify(packageJson.name); return definitions; }); }, // 或者使用更直接的configureWebpack configureWebpack: { plugins: [ new (require(webpack).DefinePlugin)({ process.env.VERSION: JSON.stringify(packageJson.version), process.env.BUILD_TIME: JSON.stringify(new Date().toISOString().slice(0, 19).replace(T, )) }) ] } };方法二通过自定义公共文件注入创建一个专门用于存放版本信息的JavaScript模块文件在构建时由Node脚本生成。创建脚本scripts/inject-version.js:// scripts/inject-version.js const fs require(fs); const packageJson require(../package.json); const content // 此文件由构建脚本自动生成请勿手动修改 export const APP_VERSION ${packageJson.version}; export const APP_NAME ${packageJson.name}; export const BUILD_TIMESTAMP ${Date.now()}; ; fs.writeFileSync(./src/utils/version.js, content); console.log(版本信息已注入到 src/utils/version.js);在package.json的scripts中增加命令scripts: { inject-version: node scripts/inject-version.js, build:h5: npm run inject-version uni-build --platform h5 }在代码中引用// 在任何.vue或.js文件中 import { APP_VERSION, APP_NAME } from /utils/version.js; export default { data() { return { appVersion: APP_VERSION, appName: APP_NAME }; }, onLoad() { console.log(H5应用版本, this.appVersion); uni.setStorageSync(h5_version, this.appVersion); } };3.3 运行时获取与缓存策略对于H5版本号在每次构建部署后就固定了。一个高级技巧是结合本地存储和请求头来管理版本以处理缓存和强制刷新。// utils/version-helper.js import { APP_VERSION } from ./version.js; class VersionHelper { constructor() { this.currentVersion APP_VERSION; } // 检查是否需要刷新例如检测到新版本后清理缓存并重载 checkAndReload() { const storedVersion uni.getStorageSync(app_version); if (storedVersion storedVersion ! this.currentVersion) { // 版本不一致执行清理操作 console.log(检测到版本变更 (${storedVersion} - ${this.currentVersion})清理缓存...); // 可以清理特定的localStorage或IndexedDB数据 // uni.clearStorage(); // 谨慎使用会清空所有 uni.setStorageSync(app_version, this.currentVersion); // 提示用户或自动刷新谨慎使用自动刷新可能影响体验 uni.showToast({ title: 应用已更新, icon: success }); // setTimeout(() { location.reload(true); }, 1500); // 强制从服务器重新加载 } else if (!storedVersion) { // 首次访问存储版本号 uni.setStorageSync(app_version, this.currentVersion); } } // 在发起网络请求时将版本号加入请求头方便后端统计和做接口版本兼容 getRequestHeaders() { return { X-Client-Version: this.currentVersion, X-Platform: H5 }; } } export default new VersionHelper();然后在main.js或 App.vue 中初始化// main.js 或 App.vue import versionHelper from /utils/version-helper; // ... 其他代码 versionHelper.checkAndReload();H5版本的特别注意事项缓存问题H5资源极易被浏览器缓存。更新版本后用户可能仍看到旧页面。除了在构建时添加文件hashwebpack默认行为还可以通过上述版本检测逻辑提示用户刷新或配置服务器端的缓存控制策略如Cache-Control: no-cache。环境变量开发环境、测试环境、生产环境可能使用不同的版本号标识。建议将环境信息如process.env.NODE_ENV也一并注入与版本号结合使用。4. 微信小程序端解析app.json与wx.getAccountInfoSync微信小程序的环境最为封闭其版本号严格由微信开发者工具上传代码时指定的版本决定并记录在小程序的管理后台。我们需要在小程序代码内部获取这个由微信平台管理的版本号。4.1 版本号的存储位置app.json在小程序项目中uni-app编译到小程序平台后根目录下有一个app.json文件其中包含了version字段。这个字段非常重要它是你每次上传代码时在开发者工具中填写的版本号。// 小程序项目根目录/app.json (由uni-app编译生成) { pages: [...], window: {...}, version: 1.2.0, // 这是小程序的版本号 // ... 其他配置 }重要区别这个version字段是编译时由uni-app根据你在manifest.json-mp-weixin-version配置填充的。在uni-app源码的manifest.json中配置mp-weixin: { appid: 你的小程序AppID, version: 1.2.0, // 这里配置会编译到小程序的app.json // ... 小程序特有配置 }4.2 运行时获取wx.getAccountInfoSync在小程序运行时我们无法直接读取app.json文件它不在代码包的可访问范围内。微信官方提供了wx.getAccountInfoSync()API 来获取小程序账号信息其中就包含了版本号。// 在小程序页面或App中 // #ifdef MP-WEIXIN onLoad() { try { const accountInfo wx.getAccountInfoSync(); console.log(小程序账号信息:, accountInfo); // 关键版本号在这里 const miniProgramVersion accountInfo.miniProgram.version; console.log(微信小程序版本号:, miniProgramVersion); // 输出1.2.0 // 你也可以获取小程序appid const appId accountInfo.miniProgram.appId; this.setData({ version: miniProgramVersion, appId: appId }); // 同样可以用于检查更新 this.checkMiniProgramUpdate(miniProgramVersion); } catch (err) { console.error(获取小程序账号信息失败:, err); // 降级方案如果API失败可以尝试从全局变量或自己维护的配置中读取 this.setData({ version: require(/manifest.json).mp-weixin.version || 未知 }); } }, methods: { checkMiniProgramUpdate(currentVersion) { // 小程序有自带的更新机制但有时我们需要自己的逻辑 const updateManager wx.getUpdateManager(); updateManager.onCheckForUpdate(function (res) { // 请求完新版本信息的回调 console.log(是否有新版本:, res.hasUpdate); }); updateManager.onUpdateReady(function () { wx.showModal({ title: 更新提示, content: 新版本已经准备好是否重启应用, success: function (res) { if (res.confirm) { // 新的版本已经下载好调用 applyUpdate 应用新版本并重启 updateManager.applyUpdate(); } } }); }); // 你也可以向自己的服务器报告当前版本用于统计和兼容性处理 wx.request({ url: https://your-api.com/mini-program/version-report, data: { version: currentVersion }, // ... }); } } // #endif4.3 小程序版本管理的实践细节条件编译和App端一样获取小程序版本号的代码必须用// #ifdef MP-WEIXIN包裹避免在其他平台报错。API兼容性wx.getAccountInfoSync()是一个基础库版本要求较低的API通常无需担心兼容性。但出于稳健考虑可以在app.vue的onLaunch里调用并做好try-catch。开发版、体验版、正式版wx.getAccountInfoSync()获取到的是当前运行环境的版本号。在开发者工具上它返回的是你在项目配置中设置的版本在体验版或正式版返回的就是上传时对应的版本。你可以通过accountInfo.miniProgram.envVersion来区分当前是开发、体验还是正式环境。uni-app编译差异请注意uni-app编译到微信小程序时manifest.json中的version会直接拷贝到dist/dev/mp-weixin/app.json中。如果你需要动态版本号比如从CI/CD管道传入可能需要编写自定义的构建脚本在编译前修改manifest.json或直接修改生成的app.json。小程序后台版本管理在小程序管理后台你可以看到所有已上传的代码版本列表。wx.getAccountInfoSync()获取的版本号必须与后台某个已上传的版本号一致。这是小程序版本控制的核心。5. 统一封装与多端适配策略了解了各端的独立获取方法后在实际项目中我们肯定不希望在每个需要版本号的地方都写一堆条件编译。一个优雅的解决方案是创建一个统一的版本管理工具模块。5.1 创建版本管理工具类在src/utils目录下创建appVersion.js// src/utils/appVersion.js class AppVersion { constructor() { this.platform this._getPlatform(); this.versionInfo null; } // 私有方法获取精确平台 _getPlatform() { // uni-app 提供的平台判断 const systemInfo uni.getSystemInfoSync(); let platform systemInfo.platform ? systemInfo.platform.toLowerCase() : ; // 进一步细化App平台 // #ifdef APP-PLUS if (platform android || platform ios) { return app-${platform}; } // #endif // #ifdef H5 return h5; // #endif // #ifdef MP-WEIXIN return mp-weixin; // #endif // 其他平台... return platform; } // 异步获取版本信息推荐 async getVersionInfo() { if (this.versionInfo) { return this.versionInfo; } const info { platform: this.platform, versionName: 未知, versionCode: 0, appId: , fullInfo: {} }; try { // #ifdef APP-PLUS if (this.platform.startsWith(app-)) { await new Promise((resolve) { document.addEventListener(plusready, () { plus.runtime.getProperty(plus.runtime.appid, (inf) { info.versionName inf.version; info.versionCode inf.versionCode || 0; info.appId inf.appid; info.fullInfo inf; resolve(); }); }); }); } // #endif // #ifdef H5 if (this.platform h5) { // 假设通过构建注入存在全局变量或模块中 info.versionName process.env.VERSION || H5_DEV_VERSION; info.appId window.location.hostname; // H5用域名作为标识 info.fullInfo { env: process.env.NODE_ENV }; } // #endif // #ifdef MP-WEIXIN if (this.platform mp-weixin) { const accountInfo wx.getAccountInfoSync(); info.versionName accountInfo.miniProgram.version; info.appId accountInfo.miniProgram.appId; info.fullInfo accountInfo; } // #endif } catch (error) { console.error([AppVersion] 获取 ${this.platform} 版本信息失败:, error); // 降级处理从本地存储读取上次成功的记录 const fallback uni.getStorageSync(last_known_version); if (fallback) { Object.assign(info, fallback); } } this.versionInfo info; // 可选存储到本地供降级使用 uni.setStorageSync(last_known_version, info); return info; } // 同步获取版本号简易版可能不适用于App的异步场景 getVersionNameSync() { // #ifdef MP-WEIXIN try { return wx.getAccountInfoSync().miniProgram.version; } catch (e) { return 未知; } // #endif // #ifdef H5 return process.env.VERSION || H5_DEV_VERSION; // #endif // #ifdef APP-PLUS // App端无法真正同步获取这里返回一个占位或触发警告 console.warn(App端请使用异步方法 getVersionInfo()); return App版本(需异步获取); // #endif return 未知平台; } // 统一的检查更新入口策略模式 async checkUpdate() { const versionInfo await this.getVersionInfo(); switch (this.platform) { case app-android: case app-ios: return this._checkAppUpdate(versionInfo); case mp-weixin: return this._checkMiniProgramUpdate(); case h5: return this._checkH5Update(versionInfo); default: console.warn(平台 ${this.platform} 的更新检查未实现); } } // 各平台具体的更新检查逻辑内部方法 async _checkAppUpdate(info) { // 调用自己的后端接口判断是否需要整包更新或热更新 // 这里简化示例 const res await uni.request({ url: https://api.your-app.com/check-update/app, data: { platform: this.platform, versionName: info.versionName, versionCode: info.versionCode } }); return res.data; } _checkMiniProgramUpdate() { return new Promise((resolve) { const updateManager wx.getUpdateManager(); updateManager.onCheckForUpdate(resolve); }); } _checkH5Update(info) { // H5更新通常是资源更新可以检查一个服务器上的version.txt文件 // 或者通过Service Worker管理 return new Promise((resolve) { // 示例请求一个包含最新版本号的manifest文件 fetch(/version-manifest.json) .then(r r.json()) .then(serverInfo { resolve({ hasUpdate: serverInfo.version ! info.versionName, newVersion: serverInfo.version, description: serverInfo.description }); }) .catch(() resolve({ hasUpdate: false })); }); } } // 导出单例 export default new AppVersion();5.2 在项目中使用统一工具在App.vue中初始化并全局挂载// App.vue import appVersion from /utils/appVersion; export default { onLaunch() { // 异步获取并存储版本信息 appVersion.getVersionInfo().then(info { console.log(应用启动版本信息:, info); this.$store.commit(setVersionInfo, info); // 可以根据策略决定是否立即检查更新 if (info.platform mp-weixin) { // 小程序可以立即检查 appVersion.checkUpdate(); } else if (info.platform.startsWith(app-)) { // App可以延迟几秒检查避免影响启动速度 setTimeout(() appVersion.checkUpdate(), 3000); } }); } };在页面组件中方便地使用template view classabout-page text当前版本{{ versionInfo.versionName }}/text text平台{{ versionInfo.platform }}/text button clickcheckUpdate检查更新/button /view /template script import appVersion from /utils/appVersion; export default { data() { return { versionInfo: {} }; }, async onLoad() { this.versionInfo await appVersion.getVersionInfo(); }, methods: { async checkUpdate() { const result await appVersion.checkUpdate(); if (result result.hasUpdate) { uni.showModal({ title: 发现新版本, content: 是否更新到版本 ${result.newVersion}, // ... 处理更新逻辑 }); } else { uni.showToast({ title: 已是最新版本, icon: success }); } } } }; /script5.3 多端适配的进阶考量版本号对比逻辑不同平台的版本号格式可能不同如App有versionCode整数H5只有字符串。在设计后端接口或本地对比逻辑时需要针对不同平台制定对比规则。例如App端优先对比versionCodeH5和小程序则对比versionName字符串。灰度发布对于App可以根据versionName或versionCode在后端配置灰度规则。对于小程序可以利用微信的“灰度发布”功能。对于H5可以通过Cookie或URL参数来控制不同用户看到不同版本。错误监控与统计将获取到的版本号作为关键字段附加到所有的错误上报如Sentry和用户行为统计如友盟、Google Analytics中。这样当某个版本出现Bug时你可以快速定位受影响的用户范围。环境区分在开发、测试、生产环境中版本号的获取逻辑应保持一致但版本号的值可能不同。可以通过注入不同的环境变量如process.env.ENV来区分并在日志和上报中明确体现。通过这样一个统一的封装我们不仅解决了各端版本号获取方式不同的问题还将版本管理相关的逻辑获取、检查、更新集中到了一处大大提升了代码的可维护性和可扩展性。当需要增加新的平台如支付宝小程序、抖音小程序时只需要在这个工具类中添加对应的条件编译块和实现逻辑即可。
uni-app跨端开发：App、H5、小程序版本号统一获取与封装实践
发布时间：2026/7/30 4:51:40
1. 为什么版本号管理是跨端开发的第一道坎做跨端开发尤其是用uni-app这种“一套代码发布到多个平台”的框架开发者很容易陷入一种错觉代码逻辑是统一的那么获取一些基础信息比如应用版本号也应该是统一的。但现实往往第一个巴掌就扇在这里。我接手过不少从其他开发者那里转过来的uni-app项目经常看到在App.vue的onLaunch里试图用一个uni.getSystemInfo就拿到所有端的版本号结果在H5和小程序上要么报错要么拿到的是浏览器或微信的版本根本不是自己应用的版本。这看似是个小问题却直接关系到应用的核心逻辑。版本号用来做什么用户端它展示在“关于我们”页面是基础信息开发端它是灰度发布、强制更新、AB测试、数据统计、问题回溯的基石。想象一个场景你发布了一个新版本App修复了某个紧急Bug同时在H5和小程序也更新了功能。如果没有准确获取各端自身版本号的能力你的更新提示逻辑就会乱套——可能App提示更新了H5却毫无反应或者反过来。用户在不同端看到的信息不一致体验会非常割裂。所以搞清楚如何在uni-app中分别获取原生App编译为apk/ipa、H5部署在服务器、微信小程序这三个主要终端的应用版本号是跨端项目稳健起步的必修课。这不是一个API能搞定的它需要你理解每个平台的运行机制和配置文件的差异。下面我就结合实际的踩坑经验把这三个平台的版本号获取方法、背后的原理以及那些官方文档没细说的“坑点”给你彻底讲明白。2. App端深入manifest.json与原生编译产物在uni-app项目中App端的版本号管理核心在于两个文件manifest.json和原生平台的特定配置文件。很多新手以为版本号只在打包时设置其实它在运行时的获取逻辑也值得深究。2.1 版本号的定义与优先级首先打开你项目根目录下的manifest.json文件。在app-plus节点下如果是Vue3项目也可能是app节点你会找到版本相关的配置app-plus: { versionName: 1.2.0, versionCode: 120, // ... 其他配置 }这里有两个关键字段versionName(版本名称)展示给用户看的字符串如“1.2.0”、“2.1.5-beta”。它遵循主版本号.次版本号.修订号的常见约定。versionCode(版本代码)一个整数用于内部比较版本新旧。每次发布新版本这个数字必须递增。Google Play 和国内安卓市场主要依据这个值来判断是否升级。注意versionName和versionCode在manifest.json中配置的是基准值。当你使用HBuilderX进行云打包或离线打包时最终生成的原生安装包APK/IPA的版本信息以打包时传入的参数或可视化界面中的设置为准。manifest.json中的值更像是默认值或模板。这是一个常见的混淆点。2.2 运行时获取plus.runtime.getProperty在App运行后我们需要在JavaScript代码中动态获取这些信息。这需要调用HTML5即5 Runtime的API。uni-app对这部分API进行了封装可以通过uni.getSystemInfo获取一些但获取应用自身版本号必须使用plus.runtime.getProperty。下面是一个在App.vue的onLaunch中安全获取版本信息的示例// 在 App.vue 中 export default { onLaunch: function() { // 判断平台仅App端执行 // #ifdef APP-PLUS const app this; // 等待plus环境ready这是一个关键细节 document.addEventListener(plusready, function() { const platform uni.getSystemInfoSync().platform; // 再次确认是App环境虽然已经在#ifdef里 if (platform android || platform ios) { plus.runtime.getProperty(plus.runtime.appid, function(inf) { console.log(App版本名称:, inf.version); // 对应 versionName console.log(App版本代码:, inf.versionCode); // 对应 versionCodeiOS上可能为undefined console.log(App标识:, inf.appid); // 将信息存入Vuex或全局变量供其他页面使用 app.$store.commit(setAppVersionInfo, { versionName: inf.version, versionCode: inf.versionCode || 0, // iOS处理 appid: inf.appid }); // 示例检查更新逻辑 app.checkAppUpdate(inf.version, inf.versionCode); }); } }); // #endif }, methods: { checkAppUpdate(currentVersionName, currentVersionCode) { // 这里实现你的检查更新逻辑比如请求服务器接口 uni.request({ url: https://your-api.com/check-update, data: { platform: uni.getSystemInfoSync().platform, version: currentVersionName, versionCode: currentVersionCode }, success: (res) { if (res.data.hasUpdate) { // 提示用户更新 uni.showModal({ title: 发现新版本, content: 新版本 ${res.data.newVersion} 已发布是否立即更新, success: (modalRes) { if (modalRes.confirm) { // Android通常直接下载apk安装iOS跳转App Store plus.runtime.openURL(res.data.downloadUrl); } } }); } } }); } } }关键点与避坑指南环境判断务必使用// #ifdef APP-PLUS条件编译将代码包裹因为plus对象只在App环境存在在H5或小程序环境直接调用会报错“plus is not defined”。等待plusreadyApp启动后5 Runtime环境需要一点时间初始化。在onLaunch中直接调用plus.runtime.getProperty可能失败。最稳妥的方式是监听document的plusready事件或者使用setTimeout进行简短延迟不推荐不优雅。iOS的versionCode在iOS平台plus.runtime.getProperty回调的inf对象中versionCode字段通常是undefined。因为iOS的CFBundleVersion构建版本号在WebView层不一定暴露。如果你需要iOS的构建号可能需要通过uni-app原生插件来获取或者依赖versionName对应CFBundleShortVersionString进行版本比较。热更新与版本号如果你使用了uni-app的wgt热更新请注意热更新包的版本号也需要在manifest.json中配置并且热更新不会改变原生安装包的versionCode。你的检查更新逻辑需要同时考虑整包更新和热更新两套规则。3. H5端从package.json到构建环境的变量注入H5端的版本号获取逻辑与App端截然不同。H5项目运行在浏览器中没有“安装包”的概念它的版本本质上就是你当前部署在服务器上的前端资源包的版本。3.1 版本信息的来源与管理最普遍的做法是将版本号定义在package.json文件中与你的npm包管理保持一致// 项目根目录/package.json { name: my-uni-app, version: 1.2.0, // ... 其他依赖和脚本 }但是package.json里的版本号是在Node.js环境中读取的浏览器中的JavaScript无法直接访问这个文件。因此我们需要在构建build过程中将这个版本号“注入”到前端代码可以访问的地方。3.2 构建时注入以Vue CLI模式为例如果你使用HBuilderX创建的项目它内部使用了webpack进行构建。我们需要通过配置将版本号作为一个全局变量或环境变量暴露出来。方法一使用DefinePlugin注入全局常量在项目根目录创建或修改vue.config.js文件如果不存在则创建// vue.config.js const packageJson require(./package.json); module.exports { // ... 其他配置 chainWebpack: (config) { // 向所有编译环节注入全局常量 config.plugin(define).tap((definitions) { definitions[0][process.env].VERSION JSON.stringify(packageJson.version); definitions[0][process.env].APP_NAME JSON.stringify(packageJson.name); return definitions; }); }, // 或者使用更直接的configureWebpack configureWebpack: { plugins: [ new (require(webpack).DefinePlugin)({ process.env.VERSION: JSON.stringify(packageJson.version), process.env.BUILD_TIME: JSON.stringify(new Date().toISOString().slice(0, 19).replace(T, )) }) ] } };方法二通过自定义公共文件注入创建一个专门用于存放版本信息的JavaScript模块文件在构建时由Node脚本生成。创建脚本scripts/inject-version.js:// scripts/inject-version.js const fs require(fs); const packageJson require(../package.json); const content // 此文件由构建脚本自动生成请勿手动修改 export const APP_VERSION ${packageJson.version}; export const APP_NAME ${packageJson.name}; export const BUILD_TIMESTAMP ${Date.now()}; ; fs.writeFileSync(./src/utils/version.js, content); console.log(版本信息已注入到 src/utils/version.js);在package.json的scripts中增加命令scripts: { inject-version: node scripts/inject-version.js, build:h5: npm run inject-version uni-build --platform h5 }在代码中引用// 在任何.vue或.js文件中 import { APP_VERSION, APP_NAME } from /utils/version.js; export default { data() { return { appVersion: APP_VERSION, appName: APP_NAME }; }, onLoad() { console.log(H5应用版本, this.appVersion); uni.setStorageSync(h5_version, this.appVersion); } };3.3 运行时获取与缓存策略对于H5版本号在每次构建部署后就固定了。一个高级技巧是结合本地存储和请求头来管理版本以处理缓存和强制刷新。// utils/version-helper.js import { APP_VERSION } from ./version.js; class VersionHelper { constructor() { this.currentVersion APP_VERSION; } // 检查是否需要刷新例如检测到新版本后清理缓存并重载 checkAndReload() { const storedVersion uni.getStorageSync(app_version); if (storedVersion storedVersion ! this.currentVersion) { // 版本不一致执行清理操作 console.log(检测到版本变更 (${storedVersion} - ${this.currentVersion})清理缓存...); // 可以清理特定的localStorage或IndexedDB数据 // uni.clearStorage(); // 谨慎使用会清空所有 uni.setStorageSync(app_version, this.currentVersion); // 提示用户或自动刷新谨慎使用自动刷新可能影响体验 uni.showToast({ title: 应用已更新, icon: success }); // setTimeout(() { location.reload(true); }, 1500); // 强制从服务器重新加载 } else if (!storedVersion) { // 首次访问存储版本号 uni.setStorageSync(app_version, this.currentVersion); } } // 在发起网络请求时将版本号加入请求头方便后端统计和做接口版本兼容 getRequestHeaders() { return { X-Client-Version: this.currentVersion, X-Platform: H5 }; } } export default new VersionHelper();然后在main.js或 App.vue 中初始化// main.js 或 App.vue import versionHelper from /utils/version-helper; // ... 其他代码 versionHelper.checkAndReload();H5版本的特别注意事项缓存问题H5资源极易被浏览器缓存。更新版本后用户可能仍看到旧页面。除了在构建时添加文件hashwebpack默认行为还可以通过上述版本检测逻辑提示用户刷新或配置服务器端的缓存控制策略如Cache-Control: no-cache。环境变量开发环境、测试环境、生产环境可能使用不同的版本号标识。建议将环境信息如process.env.NODE_ENV也一并注入与版本号结合使用。4. 微信小程序端解析app.json与wx.getAccountInfoSync微信小程序的环境最为封闭其版本号严格由微信开发者工具上传代码时指定的版本决定并记录在小程序的管理后台。我们需要在小程序代码内部获取这个由微信平台管理的版本号。4.1 版本号的存储位置app.json在小程序项目中uni-app编译到小程序平台后根目录下有一个app.json文件其中包含了version字段。这个字段非常重要它是你每次上传代码时在开发者工具中填写的版本号。// 小程序项目根目录/app.json (由uni-app编译生成) { pages: [...], window: {...}, version: 1.2.0, // 这是小程序的版本号 // ... 其他配置 }重要区别这个version字段是编译时由uni-app根据你在manifest.json-mp-weixin-version配置填充的。在uni-app源码的manifest.json中配置mp-weixin: { appid: 你的小程序AppID, version: 1.2.0, // 这里配置会编译到小程序的app.json // ... 小程序特有配置 }4.2 运行时获取wx.getAccountInfoSync在小程序运行时我们无法直接读取app.json文件它不在代码包的可访问范围内。微信官方提供了wx.getAccountInfoSync()API 来获取小程序账号信息其中就包含了版本号。// 在小程序页面或App中 // #ifdef MP-WEIXIN onLoad() { try { const accountInfo wx.getAccountInfoSync(); console.log(小程序账号信息:, accountInfo); // 关键版本号在这里 const miniProgramVersion accountInfo.miniProgram.version; console.log(微信小程序版本号:, miniProgramVersion); // 输出1.2.0 // 你也可以获取小程序appid const appId accountInfo.miniProgram.appId; this.setData({ version: miniProgramVersion, appId: appId }); // 同样可以用于检查更新 this.checkMiniProgramUpdate(miniProgramVersion); } catch (err) { console.error(获取小程序账号信息失败:, err); // 降级方案如果API失败可以尝试从全局变量或自己维护的配置中读取 this.setData({ version: require(/manifest.json).mp-weixin.version || 未知 }); } }, methods: { checkMiniProgramUpdate(currentVersion) { // 小程序有自带的更新机制但有时我们需要自己的逻辑 const updateManager wx.getUpdateManager(); updateManager.onCheckForUpdate(function (res) { // 请求完新版本信息的回调 console.log(是否有新版本:, res.hasUpdate); }); updateManager.onUpdateReady(function () { wx.showModal({ title: 更新提示, content: 新版本已经准备好是否重启应用, success: function (res) { if (res.confirm) { // 新的版本已经下载好调用 applyUpdate 应用新版本并重启 updateManager.applyUpdate(); } } }); }); // 你也可以向自己的服务器报告当前版本用于统计和兼容性处理 wx.request({ url: https://your-api.com/mini-program/version-report, data: { version: currentVersion }, // ... }); } } // #endif4.3 小程序版本管理的实践细节条件编译和App端一样获取小程序版本号的代码必须用// #ifdef MP-WEIXIN包裹避免在其他平台报错。API兼容性wx.getAccountInfoSync()是一个基础库版本要求较低的API通常无需担心兼容性。但出于稳健考虑可以在app.vue的onLaunch里调用并做好try-catch。开发版、体验版、正式版wx.getAccountInfoSync()获取到的是当前运行环境的版本号。在开发者工具上它返回的是你在项目配置中设置的版本在体验版或正式版返回的就是上传时对应的版本。你可以通过accountInfo.miniProgram.envVersion来区分当前是开发、体验还是正式环境。uni-app编译差异请注意uni-app编译到微信小程序时manifest.json中的version会直接拷贝到dist/dev/mp-weixin/app.json中。如果你需要动态版本号比如从CI/CD管道传入可能需要编写自定义的构建脚本在编译前修改manifest.json或直接修改生成的app.json。小程序后台版本管理在小程序管理后台你可以看到所有已上传的代码版本列表。wx.getAccountInfoSync()获取的版本号必须与后台某个已上传的版本号一致。这是小程序版本控制的核心。5. 统一封装与多端适配策略了解了各端的独立获取方法后在实际项目中我们肯定不希望在每个需要版本号的地方都写一堆条件编译。一个优雅的解决方案是创建一个统一的版本管理工具模块。5.1 创建版本管理工具类在src/utils目录下创建appVersion.js// src/utils/appVersion.js class AppVersion { constructor() { this.platform this._getPlatform(); this.versionInfo null; } // 私有方法获取精确平台 _getPlatform() { // uni-app 提供的平台判断 const systemInfo uni.getSystemInfoSync(); let platform systemInfo.platform ? systemInfo.platform.toLowerCase() : ; // 进一步细化App平台 // #ifdef APP-PLUS if (platform android || platform ios) { return app-${platform}; } // #endif // #ifdef H5 return h5; // #endif // #ifdef MP-WEIXIN return mp-weixin; // #endif // 其他平台... return platform; } // 异步获取版本信息推荐 async getVersionInfo() { if (this.versionInfo) { return this.versionInfo; } const info { platform: this.platform, versionName: 未知, versionCode: 0, appId: , fullInfo: {} }; try { // #ifdef APP-PLUS if (this.platform.startsWith(app-)) { await new Promise((resolve) { document.addEventListener(plusready, () { plus.runtime.getProperty(plus.runtime.appid, (inf) { info.versionName inf.version; info.versionCode inf.versionCode || 0; info.appId inf.appid; info.fullInfo inf; resolve(); }); }); }); } // #endif // #ifdef H5 if (this.platform h5) { // 假设通过构建注入存在全局变量或模块中 info.versionName process.env.VERSION || H5_DEV_VERSION; info.appId window.location.hostname; // H5用域名作为标识 info.fullInfo { env: process.env.NODE_ENV }; } // #endif // #ifdef MP-WEIXIN if (this.platform mp-weixin) { const accountInfo wx.getAccountInfoSync(); info.versionName accountInfo.miniProgram.version; info.appId accountInfo.miniProgram.appId; info.fullInfo accountInfo; } // #endif } catch (error) { console.error([AppVersion] 获取 ${this.platform} 版本信息失败:, error); // 降级处理从本地存储读取上次成功的记录 const fallback uni.getStorageSync(last_known_version); if (fallback) { Object.assign(info, fallback); } } this.versionInfo info; // 可选存储到本地供降级使用 uni.setStorageSync(last_known_version, info); return info; } // 同步获取版本号简易版可能不适用于App的异步场景 getVersionNameSync() { // #ifdef MP-WEIXIN try { return wx.getAccountInfoSync().miniProgram.version; } catch (e) { return 未知; } // #endif // #ifdef H5 return process.env.VERSION || H5_DEV_VERSION; // #endif // #ifdef APP-PLUS // App端无法真正同步获取这里返回一个占位或触发警告 console.warn(App端请使用异步方法 getVersionInfo()); return App版本(需异步获取); // #endif return 未知平台; } // 统一的检查更新入口策略模式 async checkUpdate() { const versionInfo await this.getVersionInfo(); switch (this.platform) { case app-android: case app-ios: return this._checkAppUpdate(versionInfo); case mp-weixin: return this._checkMiniProgramUpdate(); case h5: return this._checkH5Update(versionInfo); default: console.warn(平台 ${this.platform} 的更新检查未实现); } } // 各平台具体的更新检查逻辑内部方法 async _checkAppUpdate(info) { // 调用自己的后端接口判断是否需要整包更新或热更新 // 这里简化示例 const res await uni.request({ url: https://api.your-app.com/check-update/app, data: { platform: this.platform, versionName: info.versionName, versionCode: info.versionCode } }); return res.data; } _checkMiniProgramUpdate() { return new Promise((resolve) { const updateManager wx.getUpdateManager(); updateManager.onCheckForUpdate(resolve); }); } _checkH5Update(info) { // H5更新通常是资源更新可以检查一个服务器上的version.txt文件 // 或者通过Service Worker管理 return new Promise((resolve) { // 示例请求一个包含最新版本号的manifest文件 fetch(/version-manifest.json) .then(r r.json()) .then(serverInfo { resolve({ hasUpdate: serverInfo.version ! info.versionName, newVersion: serverInfo.version, description: serverInfo.description }); }) .catch(() resolve({ hasUpdate: false })); }); } } // 导出单例 export default new AppVersion();5.2 在项目中使用统一工具在App.vue中初始化并全局挂载// App.vue import appVersion from /utils/appVersion; export default { onLaunch() { // 异步获取并存储版本信息 appVersion.getVersionInfo().then(info { console.log(应用启动版本信息:, info); this.$store.commit(setVersionInfo, info); // 可以根据策略决定是否立即检查更新 if (info.platform mp-weixin) { // 小程序可以立即检查 appVersion.checkUpdate(); } else if (info.platform.startsWith(app-)) { // App可以延迟几秒检查避免影响启动速度 setTimeout(() appVersion.checkUpdate(), 3000); } }); } };在页面组件中方便地使用template view classabout-page text当前版本{{ versionInfo.versionName }}/text text平台{{ versionInfo.platform }}/text button clickcheckUpdate检查更新/button /view /template script import appVersion from /utils/appVersion; export default { data() { return { versionInfo: {} }; }, async onLoad() { this.versionInfo await appVersion.getVersionInfo(); }, methods: { async checkUpdate() { const result await appVersion.checkUpdate(); if (result result.hasUpdate) { uni.showModal({ title: 发现新版本, content: 是否更新到版本 ${result.newVersion}, // ... 处理更新逻辑 }); } else { uni.showToast({ title: 已是最新版本, icon: success }); } } } }; /script5.3 多端适配的进阶考量版本号对比逻辑不同平台的版本号格式可能不同如App有versionCode整数H5只有字符串。在设计后端接口或本地对比逻辑时需要针对不同平台制定对比规则。例如App端优先对比versionCodeH5和小程序则对比versionName字符串。灰度发布对于App可以根据versionName或versionCode在后端配置灰度规则。对于小程序可以利用微信的“灰度发布”功能。对于H5可以通过Cookie或URL参数来控制不同用户看到不同版本。错误监控与统计将获取到的版本号作为关键字段附加到所有的错误上报如Sentry和用户行为统计如友盟、Google Analytics中。这样当某个版本出现Bug时你可以快速定位受影响的用户范围。环境区分在开发、测试、生产环境中版本号的获取逻辑应保持一致但版本号的值可能不同。可以通过注入不同的环境变量如process.env.ENV来区分并在日志和上报中明确体现。通过这样一个统一的封装我们不仅解决了各端版本号获取方式不同的问题还将版本管理相关的逻辑获取、检查、更新集中到了一处大大提升了代码的可维护性和可扩展性。当需要增加新的平台如支付宝小程序、抖音小程序时只需要在这个工具类中添加对应的条件编译块和实现逻辑即可。
)
