refactor: 重组目录结构,脚本收进 scripts/,配置独立成 config/
根目录原来平铺了构建脚本、运行器配置、两个 .cmd 启动器和一份中文名的 实跑报告,四类东西混在一起,新人分不清哪个是源码、哪个是产物。这次按 职责分层重排: - 构建与检查脚本收进 scripts/:build.mjs、check.mjs - 一键启动器收进 scripts/:start-headless.cmd、start-dev.cmd - 运行器配置独立成 config/runner.config.mjs(日常调参不用重新 build) - 真机测试收进 dev/tests/:real-cdp / real-test / real-e2e / real-run - 运行报告改成 ASCII 名并移入 docs/reports/run-report-v203.md - v2.0.x 时期的 7 份原始抓取片段归档到 docs/archive/v2.0-snapshots/, docs/evidence/ 只留当前版本的有效证据 - 测试每次重新生成的 3 张截图(e2e-01-after-login、e2e-02-playing、 real-chrome-login)移出仓库并加入 .gitignore,改写到 .run-tmp/screenshots/; docs/screenshots/ 只保留手工挑选的 5 张展示图 路径修正:build.mjs 的 ROOT 上跳一级;dev/tests/ 四个脚本 ROOT 上跳两级、 对 runner/browser.mjs 的引用改 ../../;runner/config.mjs 默认配置文件路径改 config/runner.config.mjs;两个 .cmd 的 cd 改为仓库根、start-dev.cmd 指向 dev/serve.mjs;package.json 全部 npm scripts 同步;README、dev/README、证据 文件与源码注释里的路径一并更新。 顺带修掉测试里硬编码的 v2.7.0 断言:版本号改为从 package.json 读取。 验证:npm run build(104798 字节 / 102.3 KB)、npm run check(24/24)、 npm run test:real:headless(24/24 通过)。
This commit is contained in:
1 parent
ae117222df
commit
c1e883d67f
32 files changed
+148
-125
No files matched your search
@@ -38,7 +38,7 @@
|
||||
- `runner/browser.mjs:hasDisplay()` 判 `DISPLAY` / `WAYLAND_DISPLAY`;
|
||||
- `runner/headless.mjs` 里 `VISIBLE = WANT_VISIBLE && hasDisplay()`,
|
||||
即**即使传了 `--visible` 也会被强制无头并打警告**;
|
||||
- `dev/real-cdp.mjs:forceHeadless()` 让三个真机测试脚本同样自动无头。
|
||||
- `dev/tests/real-cdp.mjs:forceHeadless()` 让三个真机测试脚本同样自动无头。
|
||||
2) root 运行:Chromium 拒绝启动(`Running as root without --no-sandbox is not supported`)。
|
||||
- `safetyArgs()` 在 `process.getuid()===0` 时补 `--no-sandbox --disable-setuid-sandbox --disable-gpu`;
|
||||
- `buildArgs()` 在 Linux 上恒加 `--no-sandbox --disable-setuid-sandbox`。
|
||||
@@ -125,10 +125,10 @@
|
||||
|
||||
|
||||
六、回归(改动没有破坏原有链路)
|
||||
- `npm run check`:12 个文件逐个 `node --check` 全通过(新增 runner/*.mjs 与 dev/real-run.mjs 也已纳入)。
|
||||
- `npm run check`:24 个文件逐个 `node --check` 全通过(新增 runner/*.mjs 与 dev/tests/real-run.mjs 也已纳入)。
|
||||
- `npm run test:real:headless`(真机只读断言):**24/24 通过,失败 0**。
|
||||
- `node dev/real-e2e.mjs --headless`:**12/12 通过,失败 0**(真实登录 → 新 document → 列表 16 张卡片 / 322 页)。
|
||||
- `node dev/real-run.mjs --headless --scan`:**3/3 通过,失败 0**。
|
||||
- `node dev/tests/real-e2e.mjs --headless`:**12/12 通过,失败 0**(真实登录 → 新 document → 列表 16 张卡片 / 322 页)。
|
||||
- `node dev/tests/real-run.mjs --headless --scan`:**3/3 通过,失败 0**。
|
||||
|
||||
|
||||
七、已知限制
|
||||
@@ -145,7 +145,7 @@
|
||||
入口只剩 90 行(结构见第二节表格),**不引入打包步骤**(按用户选择:保持直接 import)。
|
||||
|
||||
同时把 package.json 的 check 从「一长串 node --check a && node --check b …」
|
||||
改成 dev/check.mjs 自动遍历 runner/、dev/ 与顶层文件 —— 以前新增模块必须手改那行命令,
|
||||
改成 scripts/check.mjs 自动遍历 runner/、dev/、scripts/ 与 config/ —— 以前新增模块必须手改那行命令,
|
||||
漏改就会静默不被检查。现在输出:语法检查:20/20 个文件通过。
|
||||
|
||||
拆分过程中发现并修掉 3 个真实缺陷(都是原单文件里藏着的):
|
||||
@@ -175,8 +175,8 @@
|
||||
kill 浏览器主进程 会话异常:CDP 连接断开 → 15 秒后第 2 次尝试 → 自动重登 → 继续刷课
|
||||
SIGTERM 浏览器 code=143,残留 chrome 进程数 0
|
||||
npm run test:real:headless 24/24 通过
|
||||
node dev/real-e2e.mjs --headless 12/12 通过
|
||||
node dev/real-run.mjs --headless --scan 3/3 通过
|
||||
node dev/tests/real-e2e.mjs --headless 12/12 通过
|
||||
node dev/tests/real-run.mjs --headless --scan 3/3 通过
|
||||
|
||||
stop.mjs 的单元核查(一次性脚本,未入库):注册的收尾函数全部执行、已注销的不执行、
|
||||
重复信号不重复执行、收尾后调用 onExit(0)。
|
||||
@@ -211,7 +211,7 @@ Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模
|
||||
browserInstallHint() / residentHint() 按平台出安装与常驻建议
|
||||
|
||||
browser.mjs 转发 platform.mjs 的导出(safetyArgs / hasDisplay / isRunningAsRoot 等),
|
||||
老的调用方(dev/real-cdp.mjs、dev/real-*.mjs)不需要改 import。
|
||||
老的调用方(dev/tests/real-cdp.mjs、dev/tests/real-*.mjs)不需要改 import。
|
||||
|
||||
9.2 各模块的改动点
|
||||
|
||||
@@ -229,7 +229,7 @@ Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模
|
||||
config.mjs VISIBLE = WANT_VISIBLE && hasDisplay(),导出 platformName / noDisplayReason。
|
||||
supervisor.mjs 启动横幅打平台名;--visible 被忽略时用 noDisplayReason() 说原因。
|
||||
headless.mjs 注释补 Windows 用法(set / $env:)与代码结构。
|
||||
dev/real-*.mjs spawn 补 windowsHide: true。
|
||||
dev/tests/real-*.mjs spawn 补 windowsHide: true。
|
||||
|
||||
9.3 实测(Windows 11 / Chrome 155.0.8059.85 / Node v24.19.0)
|
||||
|
||||
@@ -271,13 +271,13 @@ Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模
|
||||
npm run headless:check 5/5 PASS,退出码 0
|
||||
node runner/headless.mjs --max 1 已完成 1 门(用时 3 分 9 秒),退出码 0
|
||||
npm run test:real:headless 24/24 通过
|
||||
node dev/real-e2e.mjs --headless 12/12 通过
|
||||
node dev/real-run.mjs --headless --scan 3/3 通过
|
||||
npm run check(dev/check.mjs) 21/21 个文件通过
|
||||
node dev/tests/real-e2e.mjs --headless 12/12 通过
|
||||
node dev/tests/real-run.mjs --headless --scan 3/3 通过
|
||||
npm run check(scripts/check.mjs) 24/24 个文件通过
|
||||
|
||||
9.4 Windows 额外交付
|
||||
|
||||
start-headless.cmd 一键启动(自动构建 / 检查 Node / 退出码说明 + pause)
|
||||
scripts/start-headless.cmd 一键启动(自动构建 / 检查 Node / 退出码说明 + pause)
|
||||
README「无头运行」一节 改成 Linux / Windows 双栏,补「Windows 常驻三种方式」
|
||||
与按平台分的「无图形环境常见坑」表
|
||||
环境变量 YUN_XUE_TANG_HAS_DISPLAY 0/1 强制认定有无图形会话(自动判断不准时用)
|
||||
@@ -301,12 +301,12 @@ Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模
|
||||
改为 [...new Set(args)] 去重后再拼 extraArgs。Windows 侧核查重复项:无。
|
||||
|
||||
======================================================================
|
||||
十、Windows 批处理启动脚本的编码陷阱(start-headless.cmd 报「不是内部或外部命令」)
|
||||
十、Windows 批处理启动脚本的编码陷阱(scripts/start-headless.cmd 报「不是内部或外部命令」)
|
||||
======================================================================
|
||||
|
||||
10.1 现象
|
||||
|
||||
双击 start-headless.cmd,控制台输出:
|
||||
双击 scripts/start-headless.cmd,控制台输出:
|
||||
'e' 不是内部或外部命令,也不是可运行的程序或批处理文件。
|
||||
'鍏?npm' 不是内部或外部命令,也不是可运行的程序或批处理文件。
|
||||
'rofile' 不是内部或外部命令,也不是可运行的程序或批处理文件。
|
||||
@@ -334,22 +334,22 @@ Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模
|
||||
|
||||
10.3 采用方案:批处理只用 ASCII,中文交给 Node 输出
|
||||
|
||||
start-headless.cmd 与 dev/start-dev.cmd 全部改写为纯 ASCII + CRLF:
|
||||
scripts/start-headless.cmd 与 scripts/start-dev.cmd 全部改写为纯 ASCII + CRLF:
|
||||
- 注释里写明「本文件必须保持纯 ASCII」及原因,避免以后有人手改回去;
|
||||
- 所有面向用户的提示(构建中 / 启动中 / 退出码含义 / 缺 Node)改用英文短句
|
||||
(如 [build] / [run] / [exit] / [error]),中文提示由 Node 侧日志输出;
|
||||
- 文件仍保留 chcp 65001,这样 Node 输出的 UTF-8 中文在控制台正常显示。
|
||||
|
||||
验证:
|
||||
file start-headless.cmd → DOS batch file, ASCII text, with CRLF line terminators
|
||||
非 ASCII 字节数 → 0(dev/start-dev.cmd 同样为 0,原为 50)
|
||||
cmd /c start-headless.cmd --check → 5/5 PASS,退出码 0
|
||||
cmd /c start-headless.cmd(错误凭据) → 连续 5 次登录失败 → [exit] code 3 → pause
|
||||
file scripts/start-headless.cmd → DOS batch file, ASCII text, with CRLF line terminators
|
||||
非 ASCII 字节数 → 0(scripts/start-dev.cmd 同样为 0,原为 50)
|
||||
cmd /c scripts\start-headless.cmd --check → 5/5 PASS,退出码 0
|
||||
cmd /c scripts\start-headless.cmd(错误凭据)→ 连续 5 次登录失败 → [exit] code 3 → pause
|
||||
|
||||
10.4 防回归:dev/check.mjs 增加批处理检查
|
||||
10.4 防回归:scripts/check.mjs 增加批处理检查
|
||||
|
||||
`npm run check` 原来只跑 node --check,对 .cmd 完全无感知(所以这个 bug 是双击才发现)。
|
||||
现在 dev/check.mjs 同时遍历 *.cmd / *.bat 并断言两件事:
|
||||
现在 scripts/check.mjs 同时遍历 *.cmd / *.bat 并断言两件事:
|
||||
1. 不含任何 >0x7F 的字节(报错时给出首次出现的偏移与上下文片段);
|
||||
2. LF 与 CRLF 数量相等(存在裸 LF 就报错)。
|
||||
自测(临时文件,验证完即删):
|
||||
|
||||
Reference in new issue
Block a user