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

# 热更新

保存文件后不刷新整个模拟器，已有的状态（`data`、页面栈、`globalData`）尽量保留。

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

## 细节

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

## 需要手动刷新的情况

与 React Fast Refresh 一致，以下改动要手动刷新才能看到效果：

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