Files
yun-xue-tang-assistant/dev/README.md
T
void 8193326b70 refactor: 拆分 src/ 模块并接入 esbuild 构建
把单文件脚本拆成 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 改成构建期注入版本号。
2026-10-24 22:45:27 +08:00

58 lines
3.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 开发热加载(保存即生效)
目标:在编辑器里改 `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__`(登录组件),注入必须发生在主世界,不能走普通沙箱。
## 一次性安装
1. 双击 `dev/start-dev.cmd` 启动本地服务(保持窗口开着)。
2. 浏览器打开 <http://127.0.0.1:8899/>,点「安装 / 更新热加载器」,Tampermonkey 弹窗确认安装。
> 手动方式:Tampermonkey 面板 → 添加新脚本 → 粘贴 `dev/dev-loader.user.js` 全文 → 保存。
3. **停用或删除** Tampermonkey 里原来那份「云学堂助手」完整脚本。
(两份同时跑会出现两个面板、双份定时器,行为会乱。)
4. 打开 <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`,开机即后台常驻。