开发者工具热更新

vpt 为微信小程序提供基于 Vite、Rolldown 和 React Refresh 的热模块替换。修改项目代码后，当前页面会直接更新，并保留 React 组件状态。

默认无需配置

create-vite-taro 模板已经启用热更新，可以直接启动微信开发模式：

npm

npm run dev:wx

pnpm

pnpm dev:wx

bun

bun run dev:wx

等待初始构建完成，然后在微信开发者工具中打开终端提示的 dist/wx。开发期间需要保持 Vite 进程运行。

从其他项目迁移时，请确认微信项目配置包含：

projectConfigJson: {
    setting: {
        compileHotReLoad: true,
        urlCheck: false,
        skylineRenderEnable: false
    }
},
projectPrivateConfigJson: {
    setting: {
        urlCheck: false
    }
}

• compileHotReLoad 启用开发者工具的页面 JavaScript 热重载。
• urlCheck: false 允许小程序访问本机 Vite 服务的状态接口。
• 开发者工具自身的 Skyline 调试暂不支持热更新，因此日常开发时保持 skylineRenderEnable: false。

更新时保留的状态

状态	行为
App 与 globalData	App 不重启，现有数据继续保留。
React 函数组件	React Refresh 边界兼容时保留 Hook 状态。
当前页面	保留页面路径、参数和现有 React 树。
原生输入	页面树保留时，输入内容继续存在。
页面生命周期	更新产生的 onUnload、onLoad 和 onShow 不会重复调用业务处理函数。
正常页面导航	返回、跳转、关闭和重新进入仍执行正常 Taro 生命周期。

修改 JSX 结构、文案或事件实现通常会保留组件状态。改变 Hook 顺序、组件类型或导出结构时，React Refresh 可能重新挂载对应组件。

JavaScript 更新与完整构建

一次成功的 JavaScript HMR 只会改写：

dist/wx/hmr/patches.js

普通应用文件保持不变，所以微信开发者工具不会重启 App。可执行更新不会通过 HTTP 传输；本机 Vite 接口只接收构建标识、补丁序号和完整构建请求。

以下变化会执行完整构建并重置应用状态：

• Rolldown 无法生成安全的模块补丁。
• 已执行模块找不到 HMR 接受边界。
• 模块传播遇到循环路径。
• 补丁缺失、执行失败或被 React Refresh 判定失效。
• WXML、JSON、项目配置或其他原生输出需要重新生成。

重启行为

操作	行为
修改项目代码	应用补丁并保留页面与 React 状态。
点击开发者工具“编译”	重新创建小程序运行环境，所有运行时状态重置。
关闭并重新打开开发者工具	冷启动 dist/wx；Vite 服务可以继续运行。
重启 dev:wx	重新生成完整输出和构建标识；开发者工具无需重新导入项目。
修改配置导致 Vite 重启	与重启 dev:wx 相同。

排查问题

保存后没有更新

确认：

1. 当前运行的是 dev:wx。
2. 微信开发者工具打开的是当前项目的 dist/wx。
3. compileHotReLoad 已开启，urlCheck 已关闭。
4. Vite 进程没有构建错误。
5. 开发者工具没有开启 Skyline 渲染调试。

App 状态被重置

终端出现完整构建提示时，App 状态会重置。常见原因包括配置变化、模块边界失效和补丁执行失败。

React 组件状态被重置

检查 Hook 顺序、组件类型和导出结构是否变化。React Refresh 只有在边界兼容时才保留组件状态。

本机状态请求失败

确认 urlCheck 为 false，并检查代理或防火墙是否阻止微信开发者工具访问 Vite 打印的本机地址。

需要了解物理文件边界、模块传播、React Refresh 适配和 Taro 页面重新绑定时，请阅读 HMR 实现原理。

样式热更新

将在后续版本支持。