Files
yun-xue-tang-assistant/docs/evidence/headless-linux-evidence.txt
void c1e883d67f 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 通过)。
2026-10-25 23:21:59 +08:00

362 lines
24 KiB
Plaintext
Raw Permalink 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.
云学堂助手 · 无头运行(Linux 无图形化服务器)证据
==================================================
一、需求
- 用户诉求:「支持无头模式运行在linux无图形化服务器上」。
- 澄清后的范围:新增无头运行器 + 部署说明;常驻方式为手动前台跑(tmux/nohup,
不做 systemd / Docker);持久化 profile,掉登录时用环境变量账号自动重登。
二、方案
新增 `runner/`,不装 Tampermonkey、不装桌面环境、不需要 Xvfb:
| 文件 | 作用 |
| --- | --- |
| runner/headless.mjs | 入口(约 90 行):解析参数 → 预检 → 交给 supervisor |
| runner/config.mjs | 命令行参数与环境变量(--max / YUN_XUE_TANG_* 集中在此) |
| runner/preflight.mjs | 启动前检查:产物、Node 版本、凭据、浏览器、调试端口 |
| runner/log.mjs | 终端 + 文件日志(5MB 轮转) |
| runner/stop.mjs | SIGINT / SIGTERM 优雅退出(注册式收尾) |
| runner/browser.mjs | 浏览器探测(含 Linux/容器常见路径)、启动参数、陈旧 SingletonLock 清理 |
| runner/cdp.mjs | 极简 CDP 客户端(Node 22+ 原生 WebSocket + fetch,无第三方依赖) |
| runner/page.mjs | 注入后要调用的页面 JS 表达式 + page.evalJS/json/tryEval |
| runner/session.mjs | 单次会话:起浏览器 → 注入 → 自动重登 → 起批量 → 监控 → 收尾 |
| runner/selfcheck.mjs | --check 的只读环境自检 |
| runner/supervisor.mjs | 崩溃重启循环与退出码 |
依赖方向是单向的:headless → supervisor → session → page/selfcheck → cdp,无循环引用。
按需求不打包:node runner/headless.mjs 直接跑多文件 ESM,部署时整个 runner/ 目录一起带走。
改脚本内部 API(window.__yunXueTangAuto 上的方法)时只需要改 runner/page.mjs。
注入方式与 Tampermonkey 等价:用 `Runtime.evaluate` 把构建产物源码注入页面主世界
(脚本 `@grant none`,不需要沙箱隔离),因此每次整页跳转(新 document)都要重新注入,
运行器用 1.5 秒的看护循环检测 `window.__yunXueTangAuto` 是否存在并补注入。
三、Linux 无图形化环境的三个必踩坑(与代码对应)
1) 没有 DISPLAY:有界面模式直接报 `Missing X server or $DISPLAY` 并退出。
- `runner/browser.mjs:hasDisplay()` 判 `DISPLAY` / `WAYLAND_DISPLAY`;
- `runner/headless.mjs` 里 `VISIBLE = WANT_VISIBLE && hasDisplay()`,
即**即使传了 `--visible` 也会被强制无头并打警告**;
- `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`。
3) 容器 /dev/shm 只有 64MB:标签页会莫名崩溃(`Target closed`)。
- Linux 上恒加 `--disable-dev-shm-usage`。
另外补的稳定性参数:`--no-zygote`、`--disable-gpu`、`--mute-audio`、
`--autoplay-policy=no-user-gesture-required`(无人值守必须能自己起播)、
`--disable-background-timer-throttling` / `--disable-renderer-backgrounding` /
`--disable-backgrounding-occluded-windows`(后台标签页不节流,否则计时会停)。
实测(在 Windows 上把 process.platform 覆盖成 linux、getuid 覆盖成 0 验证分支取值):
safetyArgs() root ["--disable-dev-shm-usage","--no-sandbox","--disable-setuid-sandbox","--disable-gpu"]
hasDisplay() 无 DISPLAY false
hasDisplay() 有 DISPLAY true
关键参数(root 无头) ["--autoplay-policy=no-user-gesture-required","--mute-audio","--disable-dev-shm-usage",
"--disable-gpu","--no-zygote","--no-sandbox","--disable-setuid-sandbox","--headless=new"]
有界面+关沙箱 [] ← 非 Linux 不注入任何沙箱参数,保留本机 Chrome 沙箱
陈旧的 `SingletonLock`(上次被 kill -9 留下的符号链接指向已不存在的 pid)会被清理,
活跃的锁保留;清理后普通文件形式的 `SingletonCookie` 也一并删除(实测:lock=false, cookie=false)。
四、可观测能力与容错
- 持久化:profile 固定到 `./.run-profile`(`YUN_XUE_TANG_PROFILE_DIR` 可改),cookie / localStorage 都在里面;
删掉该目录 = 重置登录态 + 进度缓存。
- 自动重登:看护循环每 1.5 秒读一次 `isLoginPage()`,是登录页就填账号密码 + 勾协议 + 点登录;
20 秒限速、连续 5 次失败则退出码 3(多半是密码错或站点要验证码)。
- 崩溃自愈:CDP 断线 / 90 秒读不到脚本状态 → 抛错 → 外层等 15s、30s… 最多 120s 后重建浏览器,
进度由页面 localStorage(`yun-xue-tang-batch-v2`)接续。
- 无进展保护:课程/课时/进度/视频任一有变化即重置计时,连续 30 分钟(`YUN_XUE_TANG_IDLE_RESTART_MINUTES`)
没变化则判定卡死退出。
- 编解码自检:`--check` 会探测 `video/mp4; codecs="avc1.42E01E"`;运行中若
`video.error.code >= 3` 立刻告警「这个 Chromium 不带 H.264/AAC」。
- 优雅退出:SIGINT/SIGTERM → 页面内 `pauseAllMedia()` + `S.running=false` + `save()` → 关浏览器。
- 日志:终端 + `./run-logs/headless.log`,超 5MB 轮转成 `.1`。
- 端口占用:启动前先探 `/json/version`,被占时直接提示 `pkill -f "remote-debugging-port=9336"`
或换 `--port`(实测提示正确,exit 2)。
五、实跑验证(真实站点 kfmic.yunxuetang.cn,真实账号)
1) 环境自检 `npm run headless:check`(只读、不登录、不动进度):
PASS 页面可访问 → https://kfmic.yunxuetang.cn/login.html
PASS 脚本已注入 window.__yunXueTangAuto → object
PASS 面板渲染唯一 → {"面板数":1,"可见":true}
PASS 脚本版本可读 → "v2.7.0"
PASS 视频编解码 H.264 可用 → {"h264":"probably","aac":"probably","vp9":"probably"}
页面识别的路由:other 是否登录页:true
2) 真跑 `node runner/headless.mjs --max 1`(无头、自动登录、真实刷课):
浏览器就绪:Chrome/155.0.8059.85
已注入脚本(第 1 次):https://kfmic.yunxuetang.cn/login.html
登录页:自动登录(第 1 次尝试)
已注入脚本(第 2 次):https://kfmic.yunxuetang.cn/sparring/#/web/drillmate
已注入脚本(第 3 次):https://kfmic.yunxuetang.cn/kng/#/list?...
页面:优先短课程:共 5109 门待学,最短 2 分钟
页面:跳过:如何制定渠道战略(课程包含考试/测验章节)
页面:起点已对齐:第 1 节 视频如何读懂留存曲线?
页面:学习中:视频如何读懂留存曲线?
页面:课程完成: 如何读懂留存曲线? 第 1 门,返回列表选下一门
页面:本次已完成 1 门,已停止。
本次会话结束:已完成 1 门(达到 --max 上限) 用时 2 分 19 秒 本次完成 1 门,累计 1 门
=== 运行器退出 === (退出码 0)
3) 崩溃自愈(kill -F 掉浏览器主进程后):
会话异常:CDP 连接断开,重启浏览器
浏览器/连接异常,15 秒后重试(第 1 次)
--- 第 2 次尝试 ---
浏览器就绪:Chrome/ ...
登录页:自动登录(第 1 次尝试) ← profile 里的 cookie 过期后被站点踢回登录页,自动重登成功
已注入脚本(第 3 次):...#/list... ← 列表页新 document 重新注入
状态:进入课程(3 分钟):什么是增长黑客
页面:点击开始学习 继续学习
页面:学习中:视频什么是增长黑客?
4) 优雅退出(kill -TERM 运行器进程):
[浏览器] 进程退出 code=143 ← 浏览器被 SIGTERM 收掉
残留 chrome 进程数:0 ← 没有孤儿进程
5) 缺凭据时直接拒绝并给原因:`缺少环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD。`,退出码 2。
六、回归(改动没有破坏原有链路)
- `npm run check`:24 个文件逐个 `node --check` 全通过(新增 runner/*.mjs 与 dev/tests/real-run.mjs 也已纳入)。
- `npm run test:real:headless`(真机只读断言):**24/24 通过,失败 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**。
七、已知限制
- 无头环境无法完成滑块/拼图类验证码:需要先在有界面模式(本机或 `xvfb-run` + `x11vnc`)
人工登录一次,之后靠持久化 profile 的 cookie 免登录。
- 服务器上如果装的是 `chromium`(Debian/Ubuntu 的 Chromium 包),可能不带 H.264/AAC:
课程视频会一直 0 秒。`--check` 会直接给出提示,改装 `google-chrome-stable` 即可。
- 运行器是前台进程,进程管理交给 tmux / nohup / screen,不内置守护模式(按需求如此)。
八、拆分重构(单文件过长 → 模块化)与回归
------------------------------------------
用户反馈「单文件代码太多了,考虑拆分」。runner/headless.mjs 从 626 行拆成 11 个模块、
入口只剩 90 行(结构见第二节表格),**不引入打包步骤**(按用户选择:保持直接 import)。
同时把 package.json 的 check 从「一长串 node --check a && node --check b …」
改成 scripts/check.mjs 自动遍历 runner/、dev/、scripts/ 与 config/ —— 以前新增模块必须手改那行命令,
漏改就会静默不被检查。现在输出:语法检查:20/20 个文件通过。
拆分过程中发现并修掉 3 个真实缺陷(都是原单文件里藏着的):
1) 端口占用检查被自己的 try/catch 吞掉
- preflight 里 fail() 在 try 块内抛出,又被同一个 catch 接住,等于端口占用永不报警;
- 而 Chrome 起来后会拒绝启动,外层只是不断重试。现在只捕获探测本身的异常。
- 实测:假 CDP 服务占住 9336 → 退出码 2,三行提示(占用者、pkill 命令、换端口建议)。
2) 连续登录失败不会退出(最严重)
- 原代码在看护循环里 throw,但 setInterval 的 catch 把它当「看护循环异常」打印成警告,
主循环永远看不到这个错误:错误凭据下会无限刷日志、永不退出。
- 修法:致命错误寄存到 fatalError + 停掉定时器,主循环抛出;supervisor 据此返回退出码 3。
- 实测(故意错的账号密码):5 次尝试(每次 20 秒限速)→
会话异常:连续 5 次登录失败:请检查 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD,… → 退出码 3。
3) 会话抛错时浏览器没收干净
- 异常路径跳过了 disposeSession,浏览器进程残留会占住 CDP 端口,下一轮重启撞端口。
- 修法:session 暴露 disposeActiveSession()(幂等),supervisor 在 catch 里先调用它。
- 实测:退出码 3 之后残留 chrome 进程数 0。
回归(重构后全部重跑,真实站点、真实账号):
npm run check 语法检查:20/20 个文件通过(原 12 个,新增 8 个模块)
npm run headless:check 5/5 PASS,退出码 0
node runner/headless.mjs --max 1 真实完成 1 门,退出码 0(多次重跑:2 分 16 秒 / 3 分 39 秒)
kill 浏览器主进程 会话异常:CDP 连接断开 → 15 秒后第 2 次尝试 → 自动重登 → 继续刷课
SIGTERM 浏览器 code=143,残留 chrome 进程数 0
npm run test:real:headless 24/24 通过
node dev/tests/real-e2e.mjs --headless 12/12 通过
node dev/tests/real-run.mjs --headless --scan 3/3 通过
stop.mjs 的单元核查(一次性脚本,未入库):注册的收尾函数全部执行、已注销的不执行、
重复信号不重复执行、收尾后调用 onExit(0)。
stop.mjs 全部断言通过:{"order":["browser.kill","log.close"],"exited":0,"lines":["收到 SIGTERM,正在收尾…"]}
======================================================================
九、跨平台适配(追加 Windows / macOS 支持,实测于 Windows)
======================================================================
背景:无头运行器最初只按「Linux 无图形化服务器」设计,但项目主开发机是 Windows。
实际运行暴露了一批 Windows 专属问题(强杀后残留、锁文件名字不同、SIGTERM 收不到、
Session 0 没有桌面、spawn 会闪黑框),因此把平台差异从各模块里抽出来集中处理。
9.1 新增 runner/platform.mjs(平台差异唯一出口)
isWindows / isLinux / isMac / platformName
isRunningAsRoot() getuid()===0
hasDisplay() 有无图形会话;支持 YUN_XUE_TANG_HAS_DISPLAY=0/1 强制覆盖
Linux 看 DISPLAY/WAYLAND_DISPLAY
Windows 看 SESSIONNAME(Services = Session 0,无桌面)
noDisplayReason() 给日志用的人话原因
safetyArgs() 本平台需要的额外启动参数
Linux: --disable-dev-shm-usage(+ root: --no-sandbox 等)
Windows: 不注入 --no-sandbox;只加 --disable-session-crashed-bubble
--hide-crash-restore-bubble(避免无人值守时弹窗等人点)
killTree(child) 进程树收尾:POSIX SIGTERM→SIGKILL;Windows TerminateProcess
+ 兜底 taskkill /T /F
killProfileOrphans(profileDir) 按 --user-data-dir 找残留浏览器进程并杀掉(自愈)
Linux: ps -eo pid=,args=
Windows: Get-CimInstance Win32_Process + taskkill
portInUseHint(port) 按平台出排查命令
browserInstallHint() / residentHint() 按平台出安装与常驻建议
browser.mjs 转发 platform.mjs 的导出(safetyArgs / hasDisplay / isRunningAsRoot 等),
老的调用方(dev/tests/real-cdp.mjs、dev/tests/real-*.mjs)不需要改 import。
9.2 各模块的改动点
browser.mjs CANDIDATES 补 Windows 用户级安装(LOCALAPPDATA)与 Edge/Chromium 路径,
可执行名匹配改为 EXE_RE(认 .exe);
buildArgs 把 --disable-dev-shm-usage / --no-zygote 限定为非 Windows;
spawn 加 windowsHide(否则无人值守时闪黑框);
kill() 改为 platform.killTree();
cleanStaleSingleton 在 Windows 上额外清 lockfile(普通文件,无法反查 pid,
所以先 killProfileOrphans 再清)。
preflight.mjs 浏览器缺失提示、Node 升级提示、端口排查命令全部按平台出;
端口被占时先 killProfileOrphans 自愈一次,再判断是否真的失败。
stop.mjs 监听 SIGINT + SIGBREAK + SIGHUP(Windows 上 SIGTERM 根本收不到,
Ctrl+C 是 SIGINT,Ctrl+Break 是 SIGBREAK,关窗口是 SIGHUP)。
config.mjs VISIBLE = WANT_VISIBLE && hasDisplay(),导出 platformName / noDisplayReason。
supervisor.mjs 启动横幅打平台名;--visible 被忽略时用 noDisplayReason() 说原因。
headless.mjs 注释补 Windows 用法(set / $env:)与代码结构。
dev/tests/real-*.mjs spawn 补 windowsHide: true。
9.3 实测(Windows 11 / Chrome 155.0.8059.85 / Node v24.19.0)
平台判断
hasDisplay() → true(SESSIONNAME=Console)
safetyArgs() → ["--disable-session-crashed-bubble",
"--hide-crash-restore-bubble"]
buildArgs 平台相关参数 → --disable-gpu / --disable-session-crashed-bubble
/ --hide-crash-restore-bubble / --headless=new
(无 --no-sandbox / --disable-dev-shm-usage)
模拟 SESSIONNAME=Services → hasDisplay() false,--visible 被忽略
killTree(进程树收尾)
启动后同 profile chrome 进程数 10
b.kill() 返回用时 206ms
kill 后进程数 0 ✔ 无残留
killProfileOrphans(残留自愈)—— 用 detached 造出「父进程退出后仍活着」的浏览器
detached 浏览器进程数 10
端口 9358 可响应 true
killProfileOrphans 返回 10
清理后进程数 / 端口 9358 0 / false ✔
预检自愈(端到端)
先用残留浏览器占住默认端口 9336 端口可响应 true
node runner/headless.mjs --check
[预检] 已清理 11 个占用本 profile 的残留进程,重新检测端口…
PASS 页面可访问 / 脚本已注入 / 面板渲染唯一 / 版本可读 / H.264 可用
退出码 0 ✔ 自愈成功(不再误报退出码 2)
Windows 上的信号事实(一次性脚本核查,未入库)
process.kill(pid, 'SIGINT') 子进程被直接终止,SIGINT 处理函数不执行
process.kill(pid, 'SIGTERM') 报 ESRCH,不可用
taskkill /pid <pid>(不带 /F) 报「无法终止」;必须 /F,而 /F 是 TerminateProcess
→ 结论:Windows 上跨进程没有优雅信号,只有当前控制台的 Ctrl+C 能触发 SIGINT。
因此 stop.mjs 监听 SIGINT/SIGBREAK/SIGHUP,并把「强杀留下残局」交给 killProfileOrphans 兜底。
真实链路回归(真实站点 kfmic.yunxuetang.cn、真实账号)
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/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 额外交付
scripts/start-headless.cmd 一键启动(自动构建 / 检查 Node / 退出码说明 + pause)
README「无头运行」一节 改成 Linux / Windows 双栏,补「Windows 常驻三种方式」
与按平台分的「无图形环境常见坑」表
环境变量 YUN_XUE_TANG_HAS_DISPLAY 0/1 强制认定有无图形会话(自动判断不准时用)
9.5 buildArgs 参数去重(Linux 分支在 Windows 上模拟验证)
platform.mjs 在模块加载时就用 process.platform 定下了常量,因此模拟 Linux 必须在
import 之前改写(一次性脚本 .run-tmp/linux-sim.mjs,用 Object.defineProperty 覆盖
process.platform='linux'、process.getuid=()=>0、清掉 DISPLAY/WAYLAND_DISPLAY)。
hasDisplay() → false(无 DISPLAY)
noDisplayReason() → 当前环境没有图形显示(DISPLAY / WAYLAND_DISPLAY 都为空)
safetyArgs() → ["--disable-dev-shm-usage","--no-sandbox",
"--disable-setuid-sandbox","--disable-gpu"]
buildArgs(去重后) → --disable-gpu / --disable-dev-shm-usage / --no-zygote
/ --no-sandbox / --disable-setuid-sandbox / --headless=new
portInUseHint(9336) → ["ss -lptn \"sport = :9336\"", "pkill -f \"remote-debugging-port=9336\""]
发现并修掉:手写的 Linux 参数与 safetyArgs() 有重叠(--disable-dev-shm-usage /
--no-sandbox / --disable-setuid-sandbox 各出现两次),Chrome 收到重复开关没有意义,
改为 [...new Set(args)] 去重后再拼 extraArgs。Windows 侧核查重复项:无。
======================================================================
十、Windows 批处理启动脚本的编码陷阱(scripts/start-headless.cmd 报「不是内部或外部命令」)
======================================================================
10.1 现象
双击 scripts/start-headless.cmd,控制台输出:
'e' 不是内部或外部命令,也不是可运行的程序或批处理文件。
'鍏?npm' 不是内部或外部命令,也不是可运行的程序或批处理文件。
'rofile' 不是内部或外部命令,也不是可运行的程序或批处理文件。
'nner' 不是内部或外部命令,也不是可运行的程序或批处理文件。
'姝e父鏀跺熬' 不是内部或外部命令,也不是可运行的程序或批处理文件。
即:整行被拆成几段、中文乱码(UTF-8 字节被按 GBK 解释)、还丢了字符。
10.2 根因(两个独立问题叠加)
a) 行尾是裸 LF。cmd.exe 逐行读取批处理,但它只认 CRLF;只有 LF 时会漏掉换行,
把上一行的尾部当成下一行命令的一部分 —— 于是出现 'e' / 'rofile' / 'nner'
这种「从单词中间开始」的片段。
b) 文件里有非 ASCII 字符(中文)。cmd.exe 按当前代码页(中文 Windows 是 936/GBK)
逐字节读,UTF-8 编码的中文占 3 字节,被当成 3 个 GBK 字符,行读取指针随之错位,
后续命令也跟着被截断 —— 于是出现 '鍏?npm'(UTF-8 的「关」被读成 GBK 乱码,
连后面的空格和 npm 一起粘进来)和 '姝e父鏀跺熬'(「正常收尾」的乱码)。
对照实验(同一台机器,同一目录):
CRLF + chcp 65001 + 中文 → 输出「中文提示 CRLF」「second line」 ✔ 正常
LF + chcp 65001 + 中文 → '01' 不是内部或外部命令 / '文提示' 不是内部或外部命令 ✘ 错位
所以 chcp 65001 并不能救 UTF-8 中文 —— 偏移发生在解析阶段,而不是显示阶段。
GBK 编码 + 不 chcp 的方案虽然能执行,但显示是乱码(终端代码页不匹配),
且文件必须随系统区域设置改动,不适合入库。
10.3 采用方案:批处理只用 ASCII,中文交给 Node 输出
scripts/start-headless.cmd 与 scripts/start-dev.cmd 全部改写为纯 ASCII + CRLF:
- 注释里写明「本文件必须保持纯 ASCII」及原因,避免以后有人手改回去;
- 所有面向用户的提示(构建中 / 启动中 / 退出码含义 / 缺 Node)改用英文短句
(如 [build] / [run] / [exit] / [error]),中文提示由 Node 侧日志输出;
- 文件仍保留 chcp 65001,这样 Node 输出的 UTF-8 中文在控制台正常显示。
验证:
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 防回归:scripts/check.mjs 增加批处理检查
`npm run check` 原来只跑 node --check,对 .cmd 完全无感知(所以这个 bug 是双击才发现)。
现在 scripts/check.mjs 同时遍历 *.cmd / *.bat 并断言两件事:
1. 不含任何 >0x7F 的字节(报错时给出首次出现的偏移与上下文片段);
2. LF 与 CRLF 数量相等(存在裸 LF 就报错)。
自测(临时文件,验证完即删):
造一个 UTF-8 + LF 的坏文件 → FAIL,两条都被指出
造一个 ASCII + CRLF 的对照文件 → PASS
现在输出:静态检查:23/23 个文件通过(JS 21 · 批处理 2)
同时把这两条写进 README 的「无图形环境常见的坑」表(新增一行,症状列直接给出
'鍏?npm' / '01' / 'rofile' 这三个典型报错原文,方便以后按报错搜索)。