Files
yun-xue-tang-assistant/runner/browser.mjs
T
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

272 lines
11 KiB
JavaScript
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.
// 浏览器探测与启动:Linux 无图形化服务器(含 root / 容器)与 Windows 无人值守都适配。
//
// 关键点:
// - 无显示环境下必须 --headless=new(或回退 --headless),否则 Chrome 起不来;
// - 以 root 运行时 Chromium 拒绝启动,必须 --no-sandbox;
// - 容器里 /dev/shm 通常只有 64MB,必须 --disable-dev-shm-usage,否则标签页会崩;
// - 服务器上没有 GPU/音频设备,关闭相关初始化可减少噪声与卡顿;
// - user-data-dir 固定到可配置目录(持久化 cookie),并清理上次被强杀留下的残局:
// Linux 的 SingletonLock 符号链接、Windows 的 lockfile,以及两个平台上
// 「被任务管理器/ kill -9 杀掉后留下来占着端口的孤儿浏览器进程」。
//
// 平台相关的判断(有无图形会话、沙箱参数、进程树怎么收)全部在 platform.mjs,
// 这里只负责「探测路径 + 拼参数 + 启动 + 等端口就绪」。
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { spawn } from 'node:child_process';
import { httpJson, sleep } from './cdp.mjs';
import {
isWindows, isLinux, isRunningAsRoot, safetyArgs, killTree, killProfileOrphans,
} from './platform.mjs';
// 由本模块统一再导出,老的调用方(dev/tests/real-cdp.mjs 等)不用改
// (hasDisplay / safetyArgs 只在这里转发,本模块内部不直接用)
export {
hasDisplay, safetyArgs, isRunningAsRoot, platformName, noDisplayReason,
} from './platform.mjs';
// 各平台常见的 Chrome / Chromium 安装位置(按优先级)
const CANDIDATES = [
process.env.YUN_XUE_TANG_CHROME_BIN,
process.env.YUN_XUE_TANG_CHROME,
// Linux(发行版包管理器)
'/usr/bin/google-chrome',
'/usr/bin/google-chrome-stable',
'/usr/bin/chromium',
'/usr/bin/chromium-browser',
'/snap/bin/chromium',
'/opt/google/chrome/chrome',
// 常见容器镜像(playwright / puppeteer 预装)
'/root/.cache/ms-playwright/chromium-latest-linux/chrome-linux/chrome',
'/ms-playwright/chromium-*/chrome-linux/chrome',
'/usr/lib/chromium/chromium',
'/usr/lib/chromium-browser/chromium-browser',
// Windows:Chrome / Edge / Chromium 的常见安装位置(含按用户安装的 LOCALAPPDATA)
process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe'),
process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Chromium/Application/chrome.exe'),
process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe'),
process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Google/Chrome/Application/chrome.exe'),
process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, 'Microsoft/Edge/Application/msedge.exe'),
process.env['PROGRAMFILES(X86)'] && path.join(process.env['PROGRAMFILES(X86)'], 'Microsoft/Edge/Application/msedge.exe'),
'C:/Program Files/Google/Chrome/Application/chrome.exe',
'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
// macOS
'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
'/Applications/Chromium.app/Contents/MacOS/Chromium',
].filter(Boolean);
// 运行时的可执行名(Windows 上文件名带 .exe,Linux 上可执行名不带扩展名)
const EXE_RE = /(^|[\/])(chrome|chromium|msedge)(\.exe)?$/i;
function isFile(p) {
try { return fs.statSync(p).isFile(); } catch (e) { return false; }
}
// 通配符路径(例如 playwright 缓存目录带哈希后缀)逐个展开
function expandGlob(patterns) {
const out = [];
const seen = new Set();
const walk = function (dir, depth) {
if (depth > 6) return;
let entries;
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
for (const en of entries) {
const full = path.join(dir, en.name);
if (en.isFile() && EXE_RE.test(full) && isFile(full)) {
if (!seen.has(full)) { seen.add(full); out.push(full); }
} else if (en.isDirectory()) {
walk(full, depth + 1);
}
}
};
for (const p of patterns) {
if (p.indexOf('*') < 0) continue;
const base = p.slice(0, p.indexOf('*'));
walk(base.endsWith('/') ? base : base.slice(0, base.lastIndexOf('/') + 1), 0);
}
return out;
}
export function resolveBrowser() {
const globbed = expandGlob(CANDIDATES);
const all = CANDIDATES.concat(globbed);
for (const p of all) {
if (p && p.indexOf('*') < 0 && isFile(p)) return p;
}
return null;
}
export function listCandidatePaths() {
return CANDIDATES.concat(expandGlob(CANDIDATES));
}
// 上次进程被强杀(kill -9 / 任务管理器「结束任务」)时,profile 目录会留下锁文件,
// Chrome 可能因此拒绝启动或一直弹「配置文件正在使用中」。
//
// 两套锁的名字不同:
// POSIX SingletonLock / SingletonSocket / SingletonCookie,lock 是指向 hostname-pid 的符号链接,
// 目标 pid 不存在即视为陈旧(还存在就说明真有浏览器在跑,不能动)。
// Windows 用普通的空文件 lockfile;Windows 上没法从文件反查 pid,
// 所以由调用方先用 killProfileOrphans() 把残留进程收掉,再清文件。
export function cleanStaleSingleton(profileDir) {
const names = isWindows
? ['lockfile', 'SingletonLock', 'SingletonSocket', 'SingletonCookie']
: ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
for (const name of names) {
const p = path.join(profileDir, name);
let st;
try { st = fs.lstatSync(p); } catch (e) { continue; }
try {
if (st.isSymbolicLink()) {
const target = fs.readlinkSync(p);
const m = /-(\d+)$/.exec(target);
const pid = m ? Number(m[1]) : 0;
let alive = false;
if (pid > 0) {
try { process.kill(pid, 0); alive = true; } catch (e) { alive = false; }
}
if (alive) continue; // 真的有浏览器在跑,别动
fs.unlinkSync(p);
} else {
fs.unlinkSync(p);
}
} catch (e) { /* ignore */ }
}
}
export function buildArgs({
profileDir, port, headless, noSandbox, windowSize = '1360,940', extraArgs = [],
}) {
const args = [
`--remote-debugging-port=${port}`,
`--remote-debugging-address=127.0.0.1`,
`--user-data-dir=${profileDir}`,
'--no-first-run',
'--no-default-browser-check',
'--disable-sync',
'--disable-background-networking',
'--disable-component-update',
'--disable-features=Translate,MediaRouter,OptimizationHints',
// 后台标签页/最小化时不要把定时器与视频节流,否则「持续听课」测不准
'--disable-background-timer-throttling',
'--disable-renderer-backgrounding',
'--disable-backgrounding-occluded-windows',
// 无人值守必须自己能起播,不能等用户手势
'--autoplay-policy=no-user-gesture-required',
'--mute-audio',
// 服务器 / 无人值守机器上没有可用的 GPU 加速,关掉能少一类崩溃与噪声
'--disable-gpu',
'--window-size=' + windowSize,
];
// 下面这些都是 POSIX 概念,Windows 上不认(加了也无害,但没必要)
if (!isWindows) {
args.push(
// 容器里 /dev/shm 通常只有 64MB,不加会随机崩标签页
'--disable-dev-shm-usage',
// 部分发行版 / 容器里 zygote 起不来
'--no-zygote',
);
}
if (noSandbox && (isLinux || isRunningAsRoot())) {
// Linux 服务器常见两种情况都需要它:以 root 运行、容器内 namespace 受限
args.push('--no-sandbox', '--disable-setuid-sandbox');
}
// 本平台额外需要的稳定性参数(Windows:不弹崩溃恢复气泡,免得无人值守时卡在等点击)
args.push(...safetyArgs());
if (headless) args.push('--headless=new', '--hide-scrollbars');
// 去重:上面手写的 Linux 参数和 safetyArgs() 有重叠,同一个开关重复传给 Chrome 没意义
// (但 --disable-features 这类「后面的覆盖前面的」要注意,所以按首次出现保留并合并)
return [...new Set(args)].concat(extraArgs, ['about:blank']);
}
// 启动浏览器并等 CDP 端口就绪。失败时回退到老的无头开关(老版本 Chromium 不认 --headless=new)。
export async function launchBrowser(opts) {
const {
binary, profileDir, port, headless = true, noSandbox = true,
extraArgs = [], timeoutMs = 45000, log = () => {},
} = opts;
fs.mkdirSync(profileDir, { recursive: true });
// 先收残留进程(被强杀后留下的孤儿会一直占着 CDP 端口),再清锁文件
const orphans = await killProfileOrphans(profileDir, { log });
if (orphans) log('[浏览器] 已清理 ' + orphans + ' 个残留浏览器进程');
cleanStaleSingleton(profileDir);
// headless=true 先试 --headless=new,起不来再试 --headless
const modes = headless ? [true, 'old'] : [false];
let lastErr = null;
for (const mode of modes) {
const isNew = mode === true || mode === 'old';
let args = buildArgs({
profileDir, port, headless: isNew, noSandbox, extraArgs,
});
if (mode === 'old') {
args = args.map((a) => (a === '--headless=new' ? '--headless' : a));
}
log('[浏览器] 启动:' + binary + ' ' + (isNew ? (mode === 'old' ? '(headless 旧模式)' : '(headless=new)') : '(有界面)'));
// windowsHide:Windows 上不加会闪一个黑色控制台窗口,无人值守时必须隐藏
const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
let stderrTail = '';
child.stderr.on('data', (b) => { stderrTail = (stderrTail + String(b)).slice(-4000); });
child.stdout.on('data', () => {});
let exited = false;
child.on('exit', (code, signal) => {
exited = true;
if (code !== 0 && code !== null) log('[浏览器] 进程退出 code=' + code + ' signal=' + signal);
});
const started = Date.now();
let version = null;
while (Date.now() - started < timeoutMs) {
if (exited) break;
try {
const v = await httpJson(`http://127.0.0.1:${port}/json/version`);
if (v && v.webSocketDebuggerUrl) { version = v; break; }
} catch (e) { /* 还没起来 */ }
await sleep(300);
}
if (version) {
return {
child, version, args,
headless: isNew,
kill: function () {
// 跨平台收进程树(Windows 走 TerminateProcess + taskkill /T,POSIX 走 SIGTERM→SIGKILL)
return killTree(child, { log });
},
};
}
await killTree(child, { log, timeoutMs: 3000 });
await sleep(500);
lastErr = new Error('CDP 端口未就绪(' + port + ')');
if (stderrTail.trim()) {
lastErr.message += '\n浏览器 stderr(尾部):\n' + stderrTail.trim().split('\n').slice(-12).join('\n');
}
// 只有 headless 才需要回退,非 headless 直接报错
if (!headless) break;
}
throw lastErr || new Error('浏览器启动失败');
}
// 建议的持久化 profile 目录:默认放项目内的 .run-profile(可用 YUN_XUE_TANG_PROFILE_DIR 覆盖)
export function defaultProfileDir(root) {
if (process.env.YUN_XUE_TANG_PROFILE_DIR) return path.resolve(process.env.YUN_XUE_TANG_PROFILE_DIR);
return path.join(root, '.run-profile');
}
export function tmpProfileDir(prefix = 'yun-xue-tang-headless-') {
return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
}