根目录原来平铺了构建脚本、运行器配置、两个 .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 通过)。
362 lines
24 KiB
Plaintext
362 lines
24 KiB
Plaintext
云学堂助手 · 无头运行(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' 这三个典型报错原文,方便以后按报错搜索)。
|