Cocos Creator 代码热重载扩展：保存即生效，告别 F5
一句话总结
在 Cocos Creator 里改一行 .ts 代码、按下 Ctrl + S ， 1 秒内 浏览器里的游戏就原地热替换完毕—— 不刷新页面、不丢场景状态、不污染工程文件 。这就是「代码热重载」扩展要做的事。
为什么要做这个插件
当项目比较大时，编辑器刷新代码会比较慢，改一行代码 → 切到浏览器 → F5 → 等 几十 秒甚至几分钟（看项目大小） → 验证结果，非常耗时。
市面上的热更方案通常使用编辑器编译代码，当项目很大，刷新也会很慢。本扩展基于 esbuild + WebSocket + System.register 重新实现了一套 真正能跑起来 的 HMR 流程，同时兼容 Cocos Creator 2.3.x – 2.4.x 与 3.0.x – 3.8.x 。
它能做什么
| 能力 | 说明 |
|---|---|
| 真正的热替换 | 基于 System.register 块原地 patch，编译后秒级生效，保留游戏运行状态 |
| 零工程侵入 | 通过本地代理（18180）注入 HMR 客户端，不修改 preview-template/index.html ，不污染项目 |
| 可视化控制面板 | 菜单栏一键打开，支持路径输入、启停、状态显示、模式切换 |
| 监听范围可配 | 默认监听 assets ，可指定子目录（如 assets/script/game ），大项目更省性能 |
| 自动 / 手动双模式 | 保存即热更，或暂存到队列手动应用，灵活适配不同工作流 |
| 容错优先 | 编译失败只警告，不打断运行；保存一次只触发一次热更 |
| 更新成功轻提示 | 可勾选「更新成功弹提示」，代码热更成功后在预览页顶部居中弹出「代码已更新」，3 秒自动消失，不影响游戏操作 |
| 跨版本兼容 | 动态探测 Creator 预览端口（7456）与产物目录，2.3.x – 2.4.x, 3.0.x – 3.8.x 全系列可用 |
安装与上手
Step 1：安装并启用扩展 将本扩展放到项目 extensions/ 目录下，打开 Creator → 菜单栏「扩展 → 扩展管理器」找到「代码热重载」并启用。
Step 2：打开控制面板 点击菜单栏的「代码热重载」按钮（或菜单「代码热重载 → 控制面板」），在 Creator 中打开控制面板窗口。
Step 3：配置监听路径 在「监听路径（相对项目根，留空使用 assets）」输入框中填入要监听的目录，例如 assets/script/game 。留空则监听整个 assets 。路径会自动校验，错误时输入框下方会红色提示。
Step 4：启动热更 点击「启动热更」按钮。系统会自动：
- 启动 HMR WebSocket 服务（默认 18181）
- 启动本地代理（默认 18180）
- 在系统默认浏览器打开
http://127.0.0.1:18180/
Step 5：体验热重载 在编辑器中修改任意 .ts / .js / .mjs / .tsx / .jsx 文件并保存，浏览器中的游戏会在 1 秒内自动热替换，无需刷新页面。
Step 6：切换模式（可选） 在浏览器预览页右上角点击「代码热重载」按钮，可展开面板并切换「自动更新 / 手动更新」：
- 自动模式 ：保存即热更
- 手动模式 ：保存的文件进入暂存队列，需点击「应用暂存」才统一编译热更
Step 7：停止热更 点击控制面板的「停止热更」按钮即可关闭服务。关闭 Creator 控制面板 不会 停止热更，只有主动停止或关闭 Creator 才会。
注意：启动热更后 必须 通过
http://127.0.0.1:18180/打开预览（不要直接用7456）。 扩展会在项目根创建.hot-reload-code.json保存监听路径，建议加入.gitignore。
真实工作流：3 小时调一个技能，从「永远刷新」到「基本不刷新」
以下为团队真实使用场景，已脱敏。
背景 ：调试某个 PVE 关卡的玩家技能命中逻辑。技能命中后会触发：Buff 叠加 + 飘字 + 受击动画 + 伤害结算 + 暴击判定。
没有热更时 ：
- 调一次「暴击率判定」的浮点比较 → 保存 → 切浏览器 → F5 → 等 28 秒 → 选关卡 → 触发技能 → 看飘字发现概率不对 → 切回 IDE 改值 → 再保存 → 切浏览器 → 再 F5 → 又 28 秒。
- 单次调试耗时 ~40 秒，3 小时调下来约能调 270 次。实际有效思考时间不到 1 小时。
使用本扩展后 ：
- 调一次「暴击率判定」的浮点比较 → 保存 → 1 秒后 预览页自动重载该模块，技能飘字立刻按新概率刷新。
- 单次调试耗时 ~5 秒（绝大多数是 IDE 切回焦点的时间），3 小时可以调 2160 次。 而且场景状态不丢 ——之前选中的关卡、怪物的位置、玩家的血量都还在原地。
一个后端工程师因为「每次改完都要 F5」转去做别的项目了；接入这个扩展后他又回来了，并且提交了 4 个 Bug 修复。
4 个非典型但好用的细节
-
保存一次只触发一次热更 即使你
Ctrl + S按了 10 次，热更只会触发一次，不会出现「屏幕上飘起 10 个 console.log」的情况。 -
编译失败不打断运行 你改了一个语法错误的
.ts，保存后浏览器控制台会告诉你哪一行挂了，但 当前正在运行的实例不会被破坏 。你修好后再次Ctrl + S，新代码生效。 - 自动模式 vs 手动模式 自动模式适合"改完立刻要看效果"；手动模式适合"批量改了 20 个文件，统一触发一次热更"——后者在大型项目里能减少 esbuild 编译压力。
谁应该买它
- 个人独立开发者 / 小团队 ：每次调 UI 都要等刷新是最常见的痛点，这个扩展能直接帮你把"日均开发时间"压缩 30% 以上。
- 商业项目 / 中大型团队 ：减少 build 等待时间 + 不丢场景状态 = 减少"上下文切换"。一两个工程师的时薪就回本了。
- 插件作者 / 技术博主 ：录视频、做教学时再也不需要每改一行代码就喊"等我刷新一下"。
谁可能不需要它
- 只是写写 demo、每周改两三次代码的纯学习者；
- 项目还没有任何复杂场景，纯静态页跳转的游戏。
一句话总结（再念一遍）
改代码 → 保存 → 1 秒后游戏按新代码运行，场景不丢。 这是 Cocos Creator 时代，最接近「所见即所得」的开发体验。
现在就把它装进你的项目吧：把扩展放到 extensions/ 、在 Creator 启用、点「启动热更」，你会立刻明白为什么我们离不开它。