把单文件脚本拆成 src/ 下 13 个 ES 模块,用 esbuild 打回同名 .user.js, 产物文件名不变,dev/ 热加载链路无需改动。 - build.mjs:esbuild 打包(--watch / --minify),版本号只从 package.json 读取,同时替换 meta.js 的 @version 与 config.js 的 VERSION - 统一版本号来源,消除 package.json / meta.js / config.js 三处手写 - 补回 'use strict'(esbuild IIFE 默认不带,属真实行为回归) - 清理重复实现:pauseAllMedia、listData、shortQuery、drain、clearPending、 cbAuto 模块级引用、共用 cssText - 去掉搬代码时残留的 IIFE 缩进、死字段、二次兜底默认值、过期注释 - README / dev/README 同步构建流程与目录结构 行为无变化,仅 src/config.js 的 CFG 改成构建期注入版本号。
开发热加载(保存即生效)
目标:在编辑器里改 src/ 下的源码模块,保存后自动重新打包,浏览器里的脚本自动换成新版本,
不用复制粘贴、不用重装、不用刷新页面。
结构
| 文件 | 作用 |
|---|---|
src/ |
业务脚本源码(拆成多个模块,改这里) |
build.mjs |
用 esbuild 把 src/ 打包成单文件 .user.js(产物文件名与原脚本一致,热加载链路无需改动) |
../yun-xue-tang-assistant.user.js |
构建产物(不要手改,改 src/ 后 npm run build) |
serve.mjs |
本地 HTTP 服务,向浏览器提供源码与版本哈希(127.0.0.1:8899) |
dev-loader.user.js |
Tampermonkey 里的薄加载器,轮询版本、释放旧实例、注入新实例 |
start-dev.cmd |
双击启动服务 |
原理:加载器每 1 秒请求 /version,发现哈希变化就调用旧实例暴露的
window.__ytDispose()(清定时器 / 监听器 / 面板),再把新源码以 <script> 形式注入页面主世界。
因为脚本依赖页面里的 __vue__(登录组件),注入必须发生在主世界,不能走普通沙箱。
一次性安装
- 双击
dev/start-dev.cmd启动本地服务(保持窗口开着)。 - 浏览器打开 http://127.0.0.1:8899/,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。
手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴
dev/dev-loader.user.js全文 → 保存。 - 停用或删除 Tampermonkey 里原来那份「云学堂助手」完整脚本。 (两份同时跑会出现两个面板、双份定时器,行为会乱。)
- 打开 https://kfmic.yunxuetang.cn/login.html,F12 控制台应看到:
[云学堂·热加载] 已注入 xxxxx 字节源码。
日常使用
- 改完
src/下的模块保存 →npm run build:watch自动重新打包,约 1 秒内页面控制台打印[云学堂·热加载] 热更新 → <新哈希>,面板会重建,视频播放不中断。 - 批量刷课的进度存在
localStorage(yt-batch-v2),热替换 / 刷新都不会丢。 - 改坏了(语法错误):构建失败,加载器会拒绝注入并弹出左下角红条提示,旧版本继续运行,修好再保存即可。
- 想完全回到「手动刷新才生效」:把加载器里的
MODE改成'reload'。
常见问题
| 现象 | 处理 |
|---|---|
| 左下角红条「未连上本地开发服务」 | 服务没启动,或端口被占用;运行 dev/start-dev.cmd |
| 改完没反应 | 看控制台是否有 热更新 日志;确认 npm run build:watch 在跑,改的是 src/ 下的模块 |
| 页面出现两个面板 | 旧完整脚本没停用,去 Tampermonkey 停用它 |
| 端口冲突 | node dev/serve.mjs 8900,同时把加载器里的 SERVER 常量改成对应端口 |
| 服务没开也想用 | 加载器回退到上次缓存的源码(GM_getValue('yt-dev-src')) |
关闭开发模式
停用热加载器 + 重新安装一次完整脚本(把构建产出的 .user.js 全文粘进 Tampermonkey)即可。
脚本本身不依赖任何本地服务,@grant none,可独立运行。
开机自启(可选)
把 dev/start-dev.cmd 的快捷方式放进
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup,开机即后台常驻。