---
url: https://open-wxa.github.io/hot-reload.md
description: >-
  wxa-runner 的热更新：修改 WXSS、WXML 和页面、组件的 JS 后不刷新页面，data、页面栈和 globalData
  尽量保留；其他改动整页刷新并恢复页面栈。
---

# 热更新

保存文件后不刷新整个模拟器，`data`、页面栈、`globalData` 尽量保留。

| 改动 | 效果 |
| --- | --- |
| `.wxss`（含 `app.wxss` 和被 `@import` 的文件），开启编译插件时的 `.less` / `.scss` / `.sass` | 样式立即生效，不重新渲染。页面栈里的其他页面也一起更新 |
| 页面、组件自己的 `.wxml` | 新模板立即生效，用当前 `data` 重新渲染 |
| `Page()` 构造的页面 `.js` | 方法换成新代码，下次交互执行新逻辑。已有 `data` 不变，新字段补上，`onLoad` 不重跑；新打开的页面用新代码 |
| `Component()` 构造的页面和组件 `.js`（uni-app、Taro 编译出的页面也是） | 只重新挂载这个页面或组件，它自己的状态回到初始值（和 Vite 里改 Vue 组件的 `<script>` 一样）；页面栈、其他页面和 `globalData`、Pinia 等全局状态保留 |
| 其他（`app.js`、`.json`、`utils` 等普通模块、被引用的模板和 wxs、新增或删除文件） | 整页刷新，恢复整个页面栈（每页的路径和参数），能照常返回；页面内的数据不保留 |

## 需要手动刷新的情况

和 React Fast Refresh 一样，这些改动要手动刷新才能看到：

* 改了 `onLoad` 等只在打开页面时执行的生命周期
* 改了 `data` 的初始值（已有字段以当前状态为准）
* 更新前已经注册出去的回调（`setTimeout`、`wx.onXxx`）仍是旧函数

## 细节

* 按文件内容判断改动：uni-app 等框架的监听构建每次保存都会重写全部产物，只有内容真正变化的文件才参与判断
* 热更新完成后控制台打印 `[wxa-runner] 热更新完成`。无法热更新时（如新代码执行出错）自动退回整页刷新，同样恢复整个页面栈
* 手动刷新浏览器只恢复当前页面
* 热更新依赖基础库为开发者工具准备的接口，只在监听文件变化时开启。`--no-watch`（如跑测试）时运行环境与真机一致
