1. 为什么放着reLaunch不用非要动“冷重启”的手先说结论uni.reLaunch和“冷重启”看着像治的病完全不一样。做过一段时间 uniapp 的都知道uni.reLaunch能关掉所有页面、重新打开某个页面页面栈会被清干净。但“页面栈清了”不等于“应用状态干净了”。globalData里的用户信息、内存里缓存的基类实例、插件模块里存着的 socket 连接、甚至是某几个第三方 SDK 在原生层留下的回调状态reLaunch全都管不了。也就是说你只是把舞台上的道具撤了后台的灯还亮着演员还没退场。冷重启是另一套逻辑把整个 JS 引擎状态、原生层模块状态、页面栈、全局变量、各插件持有的内存对象全部推倒重来。用 uniapp 官方接口来操作就是plus.runtime.restart()它会让应用回到“刚启动”的状态重新走一遍生命周期重新加载App.vue。这个功能真正用得上的场景往往不是日常跳转而是这种硬核时刻切换账号当前用户退出登录下一个用户要登录为了不让上一个账号的 data、uni.getStorageSync里残留的页面级状态、以及第三方统计 SDK 里的 userId 串号最好的办法不是一个个清而是直接重启。切换语言/换主题多语言切换后页面文本全部要刷新虽然理论上可以触发视图重渲染但一旦用了原生 tabbar、nvue 页面、或第三方 UI 库的文案缓存你就会发现漏网之鱼特别多。冷启动一次所有东西老老实实重新读配置。权限变更后用户同意或撤回某个隐私权限某些原生 SDK 只在启动时读取权限状态运行中改是无效的。测试/演示环境快速验证自动化测试跑完一个用例需要让 App 回到干净的初始状态冷重启是最省心的方案。所以这篇不是教你怎么在正常业务流程里玩“重启大法”而是把冷重启这个能力吃透怎么调、调了之后状态怎么控制、哪些平台会失效、怎么把参数带进重启后的“新世界”。这些细节都是我在实际项目里一个个踩出来的。2. plus.runtime.restart()冷重启的唯一硬核入口这一节先把方案本身讲透。plus.runtime.restart()是 HTML5 提供的原生方法在 uniapp 的 App 端可以直接通过plus.runtime.restart()调用。调用的效果杀掉当前 WebView 和 JS 引擎实例重新创建原生 WebView 并加载应用入口。2.1 最基础的用法// 页面中某个按钮的点击事件 function handleRestart() { plus.runtime.restart() }就这么简单。但注意这段代码只能跑在 App 端也就是经过 HBuilderX 打包后的真机 App、模拟器 App 上。小程序端没有plus对象H5 端默认也没有跨端项目必须做条件编译。2.2 带参数的冷重启先存后取既然重启会销毁内存中所有状态那么想“重启后带着某个信息进入新世界”最常见也最可靠的做法是先把参数写进 Storage再重启。function restartWithParams(params) { uni.setStorageSync(restart_params, params) // 可以加个延迟确保 Storage 写入完成再重启 setTimeout(() { plus.runtime.restart() }, 300) }等应用重新启动后在App.vue的onLaunch或某个启动页的onLoad里读取// App.vue 或者入口页面 onLaunch() { const params uni.getStorageSync(restart_params) if (params) { // 比如存储的是 { path: /pages/user/login, mode: switchAccount } // 可在这处理启动跳转逻辑 uni.removeStorageSync(restart_params) } }提示plus.runtime.restart()是异步的但调用后整个应用会在极短时间内被杀掉重建所以一般不用等待回调函数。倒是“写入 Storage 后再重启”这个动作有可能因为时序问题失败稳妥做法就是加 200ms-500ms 的延迟给 Storage 操作留出落盘时间。2.3 和“重新编译 API 方案”的对比很多人会问uniapp 的文档里不是有“重新编译 API”吗uni.restart()之类的是什么情况这就要理清一个概念plus.runtime.restart()是 App 原生层的“重启应用”。有些方案叫“重新编译”比如 uni-app 编译器提供的内置 API实质上是对当前应用进行 JS 层的重新加载。uni.reLaunch()只是页面栈的重置不是冷启动。我在项目里验证过重新编译 API把整个应用 JS 重新执行一遍页面会重新创建但原生层的一些模块状态是否彻底重置取决于各模块实现。可靠性比plus.runtime.restart()差。plus.runtime.restart()App 回到系统桌面级重启相当于用户手动划掉 App 再打开可靠性最高。uni.reLaunch()只是当前 WebView 的场景切换和冷重启完全是两码事。如果你正在做的是纯 App 项目切账号、清状态这种事首选plus.runtime.restart()。如果是多端项目我后面有一节专门讲各端的替代方案。2.4 冷重启 vs 热更新的边界有的项目里把“冷重启”和“热更新”混在一起聊这里顺带做个区分热更新wgt 资源包更新更新的是前端资源通过plus.runtime.applyUpdate()安装新资源包。安装完成后需要重启才能让新资源生效。冷重启不管你有没有新资源直接把应用清干净重启。所以热更新流程的最后一步通常也会调一次plus.runtime.restart()来加载新资源。这里有个小坑applyUpdate()成功后部分 Android 机型不会立刻让新资源完全生效需要隔一点时间再重启或者用plus.runtime.restart()连续调用两次。我在生产环境踩到过一次后面“踩坑实录”里会细讲。3. 冷重启前的“清场动作”别再让旧状态阴魂不散冷重启看起来很彻底但它不等于“失忆”。Storage 里的东西不会自己消失系统剪贴板里的内容不会自己清掉第三方 SDK 写在原生沙盒里的缓存文件也不会无端被删。所以做冷重启之前先想清楚你希望重启后哪部分是“恢复出厂”哪部分是“保留现场”3.1 该清的、该留的列一张清单拿“切换账号后冷重启”举例这是最常见的场景。我把要处理的项列出来数据项处理方式原因旧用户 token必须清除否则新用户可能拿到旧身份本地用户资料缓存必须清除避免界面显示上一个用户的头像昵称购物车、订单列表等页面级缓存建议清除防止串号埋点上报队列建议保留切换账号前产生的埋点还要上报环境配置API 地址、主题色必须保留这是应用本身的配置与用户无关设备唯一标识必须保留SDK 权限校验依赖它我在项目里写过一个clearBeforeRestart方法专门处理这类逻辑function clearBeforeRestart(options {}) { const { keepKeys [], clearKeys [] } options // 保留需要保留的 const keepMap {} keepKeys.forEach(key { keepMap[key] uni.getStorageSync(key) }) // 拿到所有 storage key // 注意uni.getStorageInfoSync 返回的 keys 只有一级 key嵌套对象里的字段不受影响 const { keys } uni.getStorageInfoSync() keys.forEach(key { if (!keepKeys.includes(key) !clearKeys.includes(key)) { // 默认清掉 uni.removeStorageSync(key) } }) // 写回保留项 Object.keys(keepMap).forEach(key { uni.setStorageSync(key, keepMap[key]) }) }这个方法的思路是“白名单制”不传参数时默认清空所有 Storage传入keepKeys就保住指定的 key。比“黑名单制”安全不容易漏掉不该留的东西。提示uni.removeStorageSync对不存在的 key 不会报错可以放心循环调用。3.2 别只盯着 Storage第三方模块的状态也要管冷重启会把内存里的第三方模块状态清掉但原生层某些持久化状态不会自动清。最典型的是推送模块如果用的是个推、极光这类推送 SDK切换账号前要把旧账号的别名、标签解绑否则新设备上会收到属于老账号的推送。IM 模块融云、环信这类即时通讯 SDK内部有本地数据库缓存和历史消息切换账号前要做 logout 操作否则重启后 SDK 可能还认为自己是登录态。定位模块某些定位 SDK 会缓存最近定位结果权限变更场景下需要手动清除定位缓存。做法是在调用冷重启之前先执行第三方模块的清理方法等这些异步操作全部完成后再调plus.runtime.restart()。我一般用 Promise 把清理流程串起来async function beforeRestart() { // 1. 清除业务数据 clearBeforeRestart({ keepKeys: [deviceId, envConfig] }) // 2. 解绑推送别名 await new Promise(resolve { pushModule.unbindAlias({ success: resolve, fail: resolve }) }) // 3. IM 登出并清缓存 await imModule.logout() // 4. 全部完成后再重启 plus.runtime.restart() }这里有个细节success和fail都调resolve是为了保证清理流程不会因为某个 SDK 的失败回调而中断。冷重启本来就是最后的兜底手段前面任何一步失败都不应该阻塞重启本身。3.3 防止无限重启打一个“标记位”冷重启最恐怖的问题不是重启本身而是重启后又被某个逻辑触发重启然后无限循环。真机上一旦出现这种情况App 会在启动动画里反复横跳用户只能卸载重装。触发无限重启的常见原因App.vue的onLaunch里有判断逻辑某个条件不满足就调用了plus.runtime.restart()冷重启后读取旧 Storage发现状态不对再次触发“重置”逻辑第三方 SDK 初始化失败后的自愈逻辑也调了restart()我的习惯是加一个“重启标记位”// 在重启前写入 function safeRestart() { uni.setStorageSync(is_restarting, true) plus.runtime.restart() } // App.vue 的 onLaunch 里 onLaunch() { const isRestarting uni.getStorageSync(is_restarting) if (isRestarting) { // 说明这次启动是由重启触发的 uni.removeStorageSync(is_restarting) // 在这里做恢复现场、跳转逻辑绝不再调 restart() return } // 正常启动的逻辑 }这样只有“正常启动”和“业务主动触发重启”两种路径能调到restart()重启后产生的isRestarting标记位会拦掉第二轮重启。4. 要重启就带“口令”进去冷启动参数传递的三种姿势冷重启之后整个应用从零开始。如果你希望新启动的应用“知道”自己是因为什么被重启的就得在重启前把“口信”留下来。这个需求太常见了切完账号要直接跳首页清完缓存要回登录页换完语言要回到当前页面这些都要靠参数传递。4.1 姿势一全局变量 定时器不推荐但要说清为什么最直觉的做法是重启前把参数塞进globalData或某个全局变量然后重启重启后读取。// 错误示例 getApp().globalData.restartReason logout plus.runtime.restart()这个做法在大部分 Android 机上可能“碰巧能用”因为plus.runtime.restart()在某些版本里并没有真正销毁原 JS 引擎。但它本质是在赌“重启器”不会清内存。iOS 上内存管理更严格冷启动后globalData大概率是全新的你存的值会被丢掉。所以我的结论是不能全局变量传参因为重启就是要清内存你偏要反向依赖内存逻辑上就自相矛盾。4.2 姿势二Storage 传参最稳定推荐把参数写进 Storage这是我自己项目主要用的方式。核心逻辑前面已经写过了这里补充几个注意点参数别太复杂Storage 只存{ reason: logout, target: /pages/login/index }这类简单 JSON不要存大对象。冷重启后 App 要重新加载parse 大 JSON 会拖慢首屏。读取之后要清理在App.vue的onLaunch里读完参数后立刻removeStorageSync防止下次启动“误食”旧参数。跨页面读取如果你的参数要在业务页面里才能决定跳转比如登录页要读“是否刚从退出登录状态过来”可以在onLaunch里把参数存到globalData这样页面启动时globalData已经是完整可读的了。4.3 姿势三URL Scheme / 推送消息传参适合外部唤醒场景有些冷重启不是用户在 App 内点按钮触发的而是 App 被系统杀掉了用户点了推送消息或扫码系统重新拉起应用。这时候要从外部带参数进应用走的是 uniapp 的onLaunch的options// App.vue onLaunch(options) { // options.path 是启动页面路径 // options.query 是启动参数 if (options options.query) { const { scene, target } options.query // scene 可以区分是扫码、推送还是其他方式进入 } }这个机制和plus.runtime.restart()本身没有直接关系但很多时候你会把“冷重启”和“外部冷启动”搞混。外部冷启动由系统决定你唯一能做的就是在onLaunch里接住参数做好路由分发。我见过不少团队把“外部冷启动”也封装成重启逻辑结果推送来了没法正常跳转排查半天才发现是启动链路里混进了一个restart()。4.4 一个完整的“切账号冷重启”示例把上面几个点串起来就是一个完整的方案// 在退出登录页面 function handleLogout() { uni.showModal({ title: 提示, content: 退出登录后应用将重启是否继续, success: async (res) { if (!res.confirm) return // 1. 清业务数据 clearBeforeRestart({ keepKeys: [deviceId] }) // 2. 写重启参数先于 restart 执行 uni.setStorageSync(restart_params, { reason: logout, needLogin: true }) // 3. 打标记位防止无限重启 uni.setStorageSync(is_restarting, true) // 4. 延迟后重启 setTimeout(() { plus.runtime.restart() }, 300) } }) }重启后启动页读取参数并做跳转// pages/index/index.vue 或某个启动页 onLoad() { const params uni.getStorageSync(restart_params) if (params params.reason logout params.needLogin) { uni.removeStorageSync(restart_params) uni.reLaunch({ url: /pages/user/login }) } }提醒不要直接在App.vue的onLaunch里做uni.reLaunch因为App.vue生命周期执行时页面栈尚未就绪跳转有时会失败或出现奇怪的白屏。放到启动页的onLoad里做跳转最稳。5. 跨端适配小程序和 H5 没有 plus怎么实现“伪冷启动”uniapp 的生态里“App 端”是主场景但项目经常要同时跑小程序和 H5。plus.runtime.restart()在非 App 端直接调代码会报错plus is not defined。这时候你得想别的办法。5.1 小程序端用 reLaunch 清栈 手动重置全局状态小程序没有“重启应用”这个能力。最接近冷启动的方案是uni.reLaunch到首页并且在小程序入口文件App.vue的onLaunch里做一轮防御性状态重置。// 条件编译只有非 App 端编译这段代码 // #ifndef APP-PLUS function pseudoRestart() { // 清空 Storage 中需要清理的 key clearBeforeRestart({ keepKeys: [deviceId] }) // 重置 globalData const app getApp() if (app) { app.globalData {} } // 关掉所有页面回到首页 uni.reLaunch({ url: /pages/index/index }) } // #endif小程序重启动画是没法控制的reLaunch会闪一下再进首页体验上比“杀了重开”还生硬。但功能上能覆盖大多数场景页面栈清零、JS 对象状态会被销毁。唯一没法模拟的是原生层缓存。小程序没有原生层概念所以问题不大。小程序的 Storage 是通过wx.setStorageSync管理的clearBeforeRestart方法对它同样有效。5.2 H5 端location.reload sessionStorage 传参H5 端的“冷重启”本质上就是刷新页面。window.location.reload()会把当前页面的所有 JS 状态清空重新加载整个 SPA。// #ifdef H5 function h5Restart() { // H5 端冷启动参数用 sessionStorage 存不用 localStorage避免“永生参数” sessionStorage.setItem(restart_params, JSON.stringify({ reason: logout })) window.location.reload() } // #endif注意H5 端刷新后onLaunch里的参数要从sessionStorage读而不是uni.getStorageSync。我还习惯在刷新前用sessionStorage.removeItem先清理一次确保旧参数不会在下下次刷新时再次出现。5.3 多端统一封装对外只暴露一个接口如果你的项目是多端共用一套代码最简单的做法是封装一个通用的appRestart方法内部通过条件编译分流。这样业务层调用时不用关心当前是什么端代码可读性也高。export function appRestart(params {}) { // 先存参数各端都能用 uni.setStorageSync(restart_params, params) // #ifdef APP-PLUS uni.setStorageSync(is_restarting, true) setTimeout(() { plus.runtime.restart() }, 300) // #endif // #ifdef H5 sessionStorage.setItem(restart_params, JSON.stringify(params)) window.location.reload() // #endif // #ifndef APP-PLUS || H5 // 小程序端 clearBeforeRestart({ keepKeys: [deviceId] }) const app getApp() if (app) app.globalData {} uni.reLaunch({ url: /pages/index/index }) // #endif }提示#ifndef APP-PLUS || H5的写法要注意编译优先级如果你用的是 vue-cli 创建的项目条件编译写法和 HBuilderX 创建的略有差异建议统一用#ifndef APP-PLUS嵌套判断来避免歧义。5.4 各端方案对比端方案是否真正“冷”页面栈全局状态StorageAppplus.runtime.restart()是JS 引擎重建全部清空全部清空保留小程序uni.reLaunch 手动清 globalData否只是页面栈重置全部清空手动重置保留H5window.location.reload()是浏览器刷新全部清空浏览器自主决定Session 保留Local 保留需要说明的是H5 刷新后globalData会全部丢失所以如果你在 H5 端要保留一些环境配置要么放localStorage要么放服务端下发。这就回到了“冷启动前要规划好哪些保留、哪些清掉”的话题。6. 冷重启的坑我替你踩过了经验与教训冷重启这个功能原理只有一行代码真正的问题都藏在细节里。这一节分享几个真实踩坑每一条都对应一个实际线上问题。6.1 坑一Storage 写入后立刻就 restart参数丢了之前有次切账号后重启完发现新用户登录页没能拿到“该去登录”的参数排查很久定位到问题出在时序上。uni.setStorageSync是同步方法看起来写完立刻就能读。但在 Android 部分机型上可能是异步 I/O 缓冲的原因进程被restart()杀掉时Storage 的磁盘写入还没真正落盘导致重启后读不到。解决办法也很简单setStorageSync之后加一个小延迟200ms~500ms再调restart()让数据落盘。我在生产环境验证过不加延迟大概有 3%-5% 的概率参数会丢加了 300ms 延迟后这个问题基本绝迹。6.2 坑二Android 上重启后偶现白屏查了三天发现是生命周期顺序App 端的冷重启流程是调用restart()→ 原生层杀掉 WebView → 重新创建 WebView → 重新加载 bundle → 执行App.vue的onLaunch→ 渲染pages/index/index.vue。我遇到的情况是在App.vue的onLaunch里做了uni.reLaunch跳转到某个业务页结果这个跳转动作和首页onLoad的执行顺序产生了竞争偶发出现白屏。后来把跳转动作全部移到首页的onLoad里做白屏问题不再出现。规律是App.vue生命周期里只做数据准备不做页面跳转页面跳转一律放到页面级onLoad里执行。6.3 坑三热更新后直接 restart新资源没生效在“热更新 重启”这个组合里官方推荐plus.runtime.applyUpdate()后会触发一次自动重启但我在部分 Android 机上发现新资源并没有完全生效App.vue甚至还是旧版本。后来做法改成applyUpdate成功后延迟 1s再调一次plus.runtime.restart()。这个方法不依赖官方的“自动重启”逻辑可靠性更高。plus.runtime.applyUpdate({ success: function() { setTimeout(() { plus.runtime.restart() }, 1000) }, fail: function() { // 更新失败提示用户 } })6.4 坑四iOS 上重启后 getApp() 可能拿到的是旧实例这个坑比较隐蔽。iOS App 冷启动时getApp()有极小概率返回旧的 App 实例内存还没完全清理导致你后续调用的getApp().globalData是你“以为已经重置”的那份旧数据。我的应对方式是在App.vue的onLaunch里主动重置globalData不依赖系统层面的“全新实例”假设onLaunch() { const isRestarting uni.getStorageSync(is_restarting) this.globalData { restarting: isRestarting, // ...其他默认值 } if (isRestarting) { uni.removeStorageSync(is_restarting) } }6.5 坑五重启后首屏广告/启动图异常有些项目的首屏是一张倒计时广告页冷重启后会重新走启动流程。如果重启参数里带了reason: logout但启动页的广告逻辑没有判断“这是重启启动”用户会再次被广告拦住几秒钟体验很差。建议在启动页判断is_restarting标记或restart_params如果是从重启来的就跳过广告倒计时直接进目标页。6.6 坑六把冷重启当万能药滥用后出现“状态丢失”事故最后这条其实不算“坑”是心态问题。有的同事遇到页面状态不对第一反应就是“重启一下”。但冷重启会丢掉用户在页面里还没提交的输入内容、临时选择项、甚至当前浏览位置体验伤害极大。我内部定的规矩是只在应用级状态异常时用冷重启页面级异常先查代码。调冷重启前先弹确认框告诉用户“需要重新启动应用完成操作”别默默重启。每次冷重启都带上 reason 参数方便线上日志排查是哪条业务触发的重启。7. 从冷重启到整套状态管理方案我个人的兜底思路写到这里把冷重启的“术”基本讲完了。但如果你只记住了plus.runtime.restart()这一行代码这篇文的价值就打折了。作为一个在 uniapp 项目里被各种状态问题折磨过的开发者我的核心体会是冷重启是一剂猛药不是保健品。日常最该做的还是把状态管理做细globalData可控、Storage 分级、页面间通信走 uni 官方事件或 Vuex/Pinia。冷重启更像是一个“紧急停机闸”只有在常规手段确实解决不了问题时才拉响。我现在的项目实践里冷重启兜底方案是这么搭配的restart_params统一管理冷启动参数is_restarting标记位防止无限重启启动页onLoad做跳转分发每次重启都上报一条日志带上 reason、时间戳、当前版本号方便出问题后还原现场线上跑了半年冷重启触发的频次不高但每次触发都能帮助用户从“坏状态”回到“干净状态”团队内部已经把它当成一套比较可靠的保底机制了。如果你也准备在自己的 uniapp 项目里上冷重启建议先拿测试包把各个平台的restart()调一遍确认没有白屏和参数丢失问题再谈上线。真到了线上才暴雷那可就真要被用户“冷启动”了。