Windows 上的安卓应用运行器:双击 APK 即装,应用以独立窗口与桌面图标运行,自持 QEMU 运行时
'use strict';
/**
* Emulator 引擎:驱动 Google 官方 Android Emulator 作为 ApkStart 的运行时。
*
* 与旧版最大的不同:这里不再假设「一套参数在所有电脑上都能跑」。
* 1. 用 doctor.chooseProfile() 按内存/CPU/磁盘/加速状态/引擎版本自动推导参数;
* 2. 启动失败时按 planVariants() 自动降级重试(GPU 后端 → 软件模拟 → 最小内存冷启动);
* 3. 动态挑空闲端口、清 AVD 锁、中文路径转短路径、镜像变更后自动作废快照;
* 4. quickboot 快照 + 小数据分区,做到「像容器一样」共享只读基础层、秒级恢复。
*
* probe 回调由上层(Runtime)提供,用于判断 Android 是否真正就绪。
*/
const { spawn, spawnSync, execFile } = require('child_process');
const fs = require('fs');
const path = require('path');
const store = require('./store');
const { Provisioner } = require('./provision');
const doctor = require('./doctor');
const userdata = require('./userdata');
const AVD_NAME = 'apkstart';
const SNAPSHOT_NAME = 'apkstart';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
/**
* Windows 上把 emulator/qemu 的退出码翻译成人话。
* 0xC0000005(3221225477)是崩溃里最常见的那个:访问冲突,实测多由
* 显卡驱动 / Vulkan 后端在 guest 启动瞬间崩掉引起,换软件渲染即可绕过。
*/
function describeExitCode(code) {
// 被信号结束时 code 是 null(Windows 上走 taskkill / adb emu kill 都会这样),
// 不能当成 0 报「正常退出」,但也谈不上异常,返回空串让调用方原样显示。
if (code == null) return '';
switch (Number(code)) {
case 0: return '正常退出';
case 1: return '启动参数或环境错误';
case 3221225477: return '0xC0000005 访问冲突,渲染后端崩溃';
case 3221225725: return '0xC00000FD 栈溢出';
case 3221225781: return '0xC0000135 缺少 DLL(VC++ 运行库 / 运行时组件被杀毒删除)';
case 3221225506: return '0xC0000022 拒绝访问(驱动或权限问题)';
case 3221225595: return '0xC000007B 镜像位数不匹配或 DLL 损坏';
default: return '';
}
}
class EmulatorEngine {
constructor(appRoot) {
this.appRoot = appRoot;
this.provisioner = new Provisioner(appRoot);
this.proc = null;
this._log = [];
this.port = 5554;
this.adbPort = Number(process.env.ANDROID_ADB_SERVER_PORT) || 5044;
this.profile = null;
this.attempts = [];
this.lastDiagnosis = null;
this.lastExitCode = null;
// 快照的 ram.bin ≈ 分配给虚拟机的内存(2-4GB)。
// 冷启动本来就快的机器不该为它付出几个 GB 的磁盘,只在「真慢」时才保存。
this.snapshotWorthSaving = null;
}
log(line) {
this._log.push({ t: Date.now(), line });
if (this._log.length > 600) this._log.shift();
}
get settings() { return store.getSettings(); }
/**
* 把「最后一次启动失败」落盘。
* 旧版只放在内存里(this.attempts),用户重启 ApkStart 后再导出诊断报告,
* 报告里就是 attempts: []、bootLog: [] 一片空白,只能在日志里翻 —— 这也是
* issue #20/#25 里「附了报告却看不出原因」的直接原因。
*/
_persistFailure(extra = {}) {
try {
const dir = path.join(store.DATA_DIR, 'logs');
fs.mkdirSync(dir, { recursive: true });
const data = {
at: new Date().toISOString(),
exitCode: this.lastExitCode,
exitMeaning: describeExitCode(this.lastExitCode),
diagnosis: this.lastDiagnosis,
attempts: this.attempts,
...extra,
};
fs.writeFileSync(path.join(dir, 'last-failure.json'), JSON.stringify(data, null, 2), 'utf8');
} catch (_) { /* 落盘失败不影响主流程 */ }
}
/** 读回上一次失败记录(诊断报告 / 开机前提示用) */
lastFailure() {
try {
return JSON.parse(fs.readFileSync(path.join(store.DATA_DIR, 'logs', 'last-failure.json'), 'utf8'));
} catch (_) { return null; }
}
_clearFailure() {
try { fs.rmSync(path.join(store.DATA_DIR, 'logs', 'last-failure.json'), { force: true }); } catch (_) { /* ignore */ }
}
get serial() { return `emulator-${this.port}`; }
/** emulator.exe 与系统镜像目录(优先用户运行时目录,回退到仓库内 engine/) */
locate() {
const p = this.provisioner.paths();
const emuCandidates = [p.emulatorExe, path.join(this.appRoot, 'engine', 'emulator', 'emulator.exe')];
const emulatorExe = emuCandidates.find((c) => fs.existsSync(c)) || '';
const img = this.provisioner.systemImageInfo();
return { emulatorExe, sysImgDir: img.dir, sysImgOk: img.ok, root: emulatorExe ? path.dirname(path.dirname(emulatorExe)) : p.root };
}
/** 选镜像:有通用镜像(API 34 Play)就用它,不再让用户切「兼容模式」 */
imageChoice() {
const play = this.provisioner.playImageInfo();
const base = this.provisioner.systemImageInfo();
if (play.ok) {
return { compat: true, api: play.api, tag: play.tag, dir: play.dir, abi: 'x86_64' };
}
return { compat: false, api: base.api, tag: base.tag, dir: base.dir, abi: base.abi || this.provisioner.paths().sysAbi };
}
/**
* 作废 quickboot 快照。
* 快照同时保存内存和磁盘镜像,装完新应用/清了数据后如果还加载旧快照,
* 用户会看到「刚刚装好的应用重启后又不见了」。
*/
invalidateSnapshot() {
this.cancelSnapshotSave();
this._snapSaved = false;
try {
const snapDir = path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`, 'snapshots');
fs.rmSync(snapDir, { recursive: true, force: true });
return true;
} catch (_) {
return false;
}
}
/**
* 清掉上次异常退出留下的锁。
* 注意 hardware-qemu.ini.lock 是**目录**不是文件,bsdtar 式的 rmSync(force) 删不掉它,
* 于是模拟器会一直报 "Running multiple emulators with the same AVD" 起不来
* (被强杀过一次就会这样),必须递归删。
*/
clearLocks(avdDir) {
try {
for (const f of fs.readdirSync(avdDir)) {
if (!/\.lock$/i.test(f)) continue;
try {
fs.rmSync(path.join(avdDir, f), { recursive: true, force: true });
} catch (_) { /* 被占用就跳过,下次再清 */ }
}
} catch (_) { /* ignore */ }
}
/**
* AVD 目录里是否真的有一份**完整**的 quickboot 快照。
* 只判断「目录非空」是不够的:保存被中断时会留下一个只有 12 字节 snapshot.pb 的空壳,
* emulator 会尝试加载、失败(日志 "does not have the requested snapshot")再回退冷启动,
* 白等几秒。这里按文件大小校验,顺手清掉空壳和旧版遗留的 default_boot(单个 3GB)。
*/
hasSnapshot() {
const base = path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`, 'snapshots', SNAPSHOT_NAME);
const size = (p) => { try { return fs.statSync(p).size; } catch (_) { return 0; } };
const pb = size(path.join(base, 'snapshot.pb'));
// 新版 emulator(37.x)写的是 ram.bin,老版本写 ram.img。
// 只认 ram.img 的后果非常严重:刚存好的 3GB 快照会被当成空壳删掉,
// 于是每次都带 -no-snapshot-load,永远冷启动 —— 这是「打开很慢」的一半原因。
const ram = Math.max(size(path.join(base, 'ram.bin')), size(path.join(base, 'ram.img')));
if (pb > 1024 && ram > 1024 * 1024) return true;
if (pb === 0 && ram === 0) return false; // 目录本来就没有,别白删
try { fs.rmSync(base, { recursive: true, force: true }); } catch (_) { /* ignore */ }
this._cleanLegacySnapshots();
return false;
}
/** 清掉旧版遗留/失败重命名留下的快照目录(default_boot 里的 ram.img 可达 3GB) */
_cleanLegacySnapshots() {
const dir = path.dirname(path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`, 'snapshots', SNAPSHOT_NAME));
let names = [];
try { names = fs.readdirSync(dir); } catch (_) { return; }
for (const name of names) {
if (name === SNAPSHOT_NAME) continue;
if (/^default_boot$|\.stale-\d+$/i.test(name)) {
try { fs.rmSync(path.join(dir, name), { recursive: true, force: true }); } catch (_) { /* ignore */ }
}
}
}
/**
* 清掉占着 AVD 锁的孤儿模拟器。
* emulator.exe 只是个启动器,真正的 qemu 被 spawn 成独立进程(detached),
* 所以只 kill 自己手上的 proc 句柄经常留个孤儿在那占着 multiinstance.lock,
* 下一次启动就会 FATAL "Running multiple emulators with the same AVD"。
* 按「AVD 锁里的 pid」+「命令行带本 AVD 名的 qemu/emulator」两个来源清。
*/
async killOrphanProcesses({ onLog = () => {} } = {}) {
if (process.platform !== 'win32') return 0;
const avdDir = path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`);
// 快速路径(每次冷启动都会走到):
// - 没有 .lock → 不可能有活着的 emulator 占着这个 AVD,直接返回;
// - 有 lock 但端口没人监听 → 只是上次强杀留下的残留目录,清掉即可。
// 以前无论什么情况都要跑一次 wmic(1~3 秒,还很吃 CPU),冷启动时明显拖慢。
let locks = [];
try { locks = fs.readdirSync(avdDir).filter((f) => /\.lock$/i.test(f)); } catch (_) { locks = []; }
if (!locks.length) return 0;
if (!(await this._anyEmulatorPortAlive())) {
this.clearLocks(avdDir);
return 0;
}
const pids = new Set();
// 1) 锁文件里 emulator 自己写的 pid(最可靠)
try {
const f = path.join(avdDir, 'hardware-qemu.ini.lock', 'pid');
if (fs.existsSync(f) && fs.statSync(f).isFile()) {
const pid = parseInt(fs.readFileSync(f, 'utf8').trim(), 10);
if (pid) pids.add(pid);
}
} catch (_) { /* ignore */ }
// 2) 兜底:按进程名 + 端口找活着的 qemu(tasklist/netstat 比 wmic 快一个量级)
try {
const [tl, ns] = await Promise.all([
new Promise((res) => execFile('tasklist', ['/FO', 'CSV', '/NH'], { windowsHide: true, maxBuffer: 8 * 1024 * 1024 }, (e, o) => res(e ? '' : String(o || '')))),
new Promise((res) => execFile('netstat', ['-ano', '-p', 'TCP'], { windowsHide: true, maxBuffer: 8 * 1024 * 1024 }, (e, o) => res(e ? '' : String(o || '')))),
]);
const qemuPids = new Set();
for (const line of tl.split('\n')) {
const m = /^"([^"]+)","(\d+)"/.exec(line.trim());
if (m && /qemu|emulator/i.test(m[1])) qemuPids.add(m[2]);
}
for (const line of ns.split('\n')) {
const m = /:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i.exec(line);
if (m && qemuPids.has(m[2])) pids.add(Number(m[2]));
}
} catch (_) { /* 拿不到进程列表就只靠锁文件里的 pid */ }
pids.delete(process.pid);
if (!pids.size) {
this.clearLocks(avdDir);
return 0;
}
onLog(`清理 ${pids.size} 个残留模拟器进程`);
await Promise.all([...pids].map((pid) => new Promise((r) => {
execFile('taskkill', ['/PID', String(pid), '/T', '/F'], { windowsHide: true }, () => r());
})));
await sleep(1200);
this.clearLocks(avdDir);
return pids.size;
}
/** 5554~5620 里是否有 emulator 控制台端口在监听(连接被拒会立刻返回,代价极小) */
async _anyEmulatorPortAlive() {
const net = require('net');
const probe = (port) => new Promise((resolve) => {
const sock = net.connect({ host: '127.0.0.1', port });
let done = false;
const fin = (v) => { if (done) return; done = true; try { sock.destroy(); } catch (_) { /* ignore */ } resolve(v); };
sock.setTimeout(120, () => fin(false));
sock.once('connect', () => fin(true));
sock.once('error', () => fin(false));
});
for (let port = 5554; port <= 5620; port += 2) {
// eslint-disable-next-line no-await-in-loop
if (await probe(port)) return true;
}
return false;
}
/**
* 准备 AVD:写 config.ini。每次启动按当前自动配置重写,保证降级重试即时生效。
*/
ensureAvd({
memoryMB = 2048, cores = 2, gpu = 'software', dataMB = 4096,
heapMB = 256, accel = 'auto', snapshot = true, wipe = false, lcd = null,
} = {}) {
const p = this.provisioner.ensureDirs();
const home = p.avdHome;
const avdDir = path.join(home, `${AVD_NAME}.avd`);
fs.mkdirSync(avdDir, { recursive: true });
this.clearLocks(avdDir);
// 屏幕分辨率:有硬件加速时 720x1280@320 画面清晰、文字不糊;
// 纯软件模拟时降到 540x960,帧率优先(面积只有 56%,肉眼差距远小于流畅度差距)。
const screen = lcd || doctor.lcdFor({ accelOk: this.profile ? this.profile.accelOk : accel !== 'off' });
const choice = this.imageChoice();
const tag = choice.tag;
const api = choice.api;
const tagDisplay = choice.compat ? 'Google Play (ARM 兼容)' : 'AOSP';
fs.writeFileSync(
path.join(home, `${AVD_NAME}.ini`),
`avd.ini.encoding=UTF-8\npath=${avdDir.replace(/\\/g, '/')}\ntarget=android-${api}\n`,
);
const cfgPath = path.join(avdDir, 'config.ini');
const wantImg = choice.dir
? `${choice.dir.replace(/\\/g, '/')}/`
: `system-images/android-${api}/${tag}/${choice.abi}/`;
this.wipePending = false;
if (fs.existsSync(cfgPath)) {
const prev = fs.readFileSync(cfgPath, 'utf8');
const prevTag = /tag\.id=(.+)$/m.exec(prev);
const prevImg = /image\.sysdir\.1=(.+)$/m.exec(prev);
// 比较「镜像身份」而不是绝对路径:同一套镜像换盘/换目录不算换镜像,
// 否则用户一改运行时目录就会被清掉所有已装应用(见 doctor.imageIdentity 注释)。
const prevId = prevImg ? doctor.imageIdentity(prevImg[1].trim()) : '';
const wantId = doctor.imageIdentity(wantImg);
if ((prevTag && prevTag[1].trim() !== tag) || (prevId && prevId !== wantId)) {
// 旧 userdata 与新镜像不兼容(APEX 引导循环),必须重建
this.wipePending = true;
}
}
// 配置指纹变化 → 旧 quickboot 快照必然加载失败或产生黑屏,主动作废。
// 注意:这里只作废**快照**,绝不能顺手 -wipe-data —— 用户数据里是已装的应用和存档。
const key = `${doctor.snapshotKey({
dataMB, emulatorVersion: this._emuVersion || '', api, tag,
}, choice.dir)}|${screen.w}x${screen.h}@${screen.dpi}`;
const keyFile = path.join(avdDir, 'snapshot.key');
let prevKey = '';
try { prevKey = fs.readFileSync(keyFile, 'utf8').trim(); } catch (_) { /* 首次 */ }
const snapshotStale = !!(prevKey && prevKey !== key);
if (this.wipePending || snapshotStale || wipe) {
// 删除可能被系统/安全软件拦截(快照目录常有几个 GB)。
// 失败就改名让 emulator 不再加载它,绝不因为清理失败而中断启动。
const snapDir = path.join(avdDir, 'snapshots');
try {
fs.rmSync(snapDir, { recursive: true, force: true });
} catch (_) {
try { fs.renameSync(snapDir, `${snapDir}.stale-${Date.now()}`); } catch (__) { /* ignore */ }
}
}
// 只有「镜像换了」(tag / sysdir 变化)才需要 -wipe-data:旧 userdata 与新镜像
// 的 APEX 不兼容,不重建会一直卡在引导循环。改容量 / 改分辨率 / 换渲染后端都不算。
fs.writeFileSync(keyFile, key, 'utf8');
// hw.cpu.arch 必须是 ABI 本身(x86_64 不能截成 x86)
const cpuArch = choice.abi === 'arm64-v8a' ? 'arm64'
: choice.abi === 'armeabi-v7a' ? 'arm' : choice.abi;
const cfg = [
`AvdId=${AVD_NAME}`,
'avd.ini.displayname=ApkStart',
'avd.ini.encoding=UTF-8',
`abi.type=${choice.abi}`,
`hw.cpu.arch=${cpuArch}`,
`hw.cpu.ncore=${cores}`,
`hw.ramSize=${memoryMB}`,
`vm.heapSize=${heapMB}`,
`image.sysdir.1=${wantImg}`,
`tag.id=${tag}`,
`tag.display=${tagDisplay}`,
// 旧版写死 16G,会在小硬盘/配额环境下生成巨型文件并拖慢首次开机
`disk.dataPartition.size=${dataMB}M`,
'hw.gpu.enabled=yes',
`hw.gpu.mode=${gpu}`,
'hw.keyboard=yes',
'hw.lcd.width=' + screen.w,
'hw.lcd.height=' + screen.h,
'hw.lcd.density=' + screen.dpi,
'hw.mainKeys=no',
'ShowDeviceFrame=no',
`PlayStore.enabled=${choice.compat}`,
// 快照完全由命令行 -snapshot apkstart 控制:用独立名字,绝不误加载
// 旧版遗留的 default_boot(那是 API30 镜像的内存状态,加载必进引导循环)。
'hw.sdCard=no',
'hw.audioInput=none',
'hw.camera.back=none',
'hw.camera.front=none',
'hw.gps=no',
// 方向/加速度传感器必须关:一旦开启,Android 会按传感器自动旋转,把竖屏
// 内容转成横的(画面整体躺倒 90°、文字竖着、四周黑边)。排版切换现在只靠
// wm density(改 smallestWidth),不需要也不允许传感器参与。
'hw.sensors.orientation=no',
].join('\n') + '\n';
fs.writeFileSync(cfgPath, cfg);
// /data 分区必须先「真的能用」,否则后面一切都是白等(见 ensureDataPartition 注释)
const data = this.ensureDataPartition(avdDir, dataMB);
return {
home, avdDir, ini: path.join(home, `${AVD_NAME}.ini`), image: choice,
wipePending: this.wipePending, screen, data,
};
}
/**
* 保证 userdata 分区是一个**真正可用**的 ext4 —— 这是「点开应用 30 秒进桌面」的地基。
*
* 为什么必须自己做(三条都是实测踩出来的):
* 1. 系统镜像包里的 userdata.img 是 1MB 全零占位,真正格式化靠 avdmanager 调 SDK 的
* mke2fs。ApkStart 直接写 config.ini 拉 emulator,跳过那一步 → /data 全零 →
* 内核 "Invalid ext4 superblock on /dev/block/vdc" → guest 掉进 recovery 重启循环 →
* adbd 永远不上线 → 上层 probe 一直 pending,最后 240s 超时。原表现:点开要等好几分钟。
* 2. emulator 自带的 e2fsck/resize2fs 是 cygwin 版 e2fsprogs 1.42.12,**不认识 encrypt
* 特性**,带这个位它直接 exit 8 拒绝干活,所以「扩文件系统」必须排在补位之前。
* 3. 文件系统必须 ≥ 分区大小:只给 64MB 的话,APEX 解压 + dexopt 立刻写满,
* 之后所有 setxattr 返回 ENOSPC → SELinux 标签写不进去 → netd/media/tombstoned
* 一起 exit 1 → 开机卡在启动动画,adb 永远 offline。
*/
ensureDataPartition(avdDir, dataMB = 4096) {
const emulatorExe = this.locate().emulatorExe;
if (!emulatorExe || !fs.existsSync(emulatorExe)) return { ok: false, reason: 'no-emulator' };
try { fs.mkdirSync(avdDir, { recursive: true }); } catch (_) { /* ignore */ }
const emuDir = path.dirname(emulatorExe);
const img = path.join(avdDir, 'userdata-qemu.img');
const wantBytes = Math.max(1024, Math.round(dataMB || 4096)) * 1024 * 1024;
let size = 0;
try { size = fs.statSync(img).size; } catch (_) { /* 不存在 */ }
if (size > 0 && userdata.hasExt4Superblock(img)) {
// 文件够大 + 文件系统也真的长到了这个大小,才算「不用动」。
// 只看文件大小会漏掉一种真实故障:qemu-img 撑开了文件、resize2fs 却失败了,
// 于是文件 6GB、安卓只有 64MB —— 用户看到的就是「装游戏说空间不足」。
const fsBytes = userdata.fsBytes(img);
const fsOk = fsBytes >= Math.min(size, wantBytes) * 0.95;
if (size >= wantBytes && fsOk) return { ok: true, created: false, size, fsBytes };
// 容量配置变大了(或文件系统没长到位):就地扩容,不重建、保留已装应用
try {
userdata.clearEncryptFlag(img);
if (size < wantBytes) this._qemuImg('resize', img, wantBytes);
this._resize2fs(img);
userdata.setEncryptFlag(img);
const grown = userdata.fsBytes(img);
this.log(`userdata 扩容:文件 ${size} → ${wantBytes},文件系统 ${fsBytes} → ${grown}`);
return { ok: true, created: false, grown: true, size: wantBytes, fsBytes: grown };
} catch (e) {
this.log(`扩容 userdata 失败(继续用现有分区):${e.message}`);
// 老分区仍然可用,但必须如实告诉调用方「这次没扩成」,不能让设置页显示成功
return { ok: false, created: false, size, fsBytes, error: e.message };
}
}
// 首次 / 旧版留下的全零占位 / 镜像损坏:全新造一个
try {
fs.rmSync(img, { force: true });
fs.rmSync(`${img}.qcow2`, { force: true });
// 先不带 encrypt 位(老 e2fsck/resize2fs 才肯干活)
fs.writeFileSync(img, userdata.buildEmptyExt4({ sizeMB: 64, encrypt: false }));
this._qemuImg('resize', img, wantBytes);
this._resize2fs(img);
userdata.setEncryptFlag(img);
this.log(`已重建 userdata:${(wantBytes / 1024 / 1024 / 1024).toFixed(1)}GB ext4(4K block,支持 FBE)`);
return { ok: true, created: true, size: wantBytes };
} catch (e) {
// 尽力而为:哪怕扩容失败,也要把 encrypt 位补回去,让 FBE 能初始化(分区会偏小)
try { userdata.setEncryptFlag(img); } catch (_) { /* ignore */ }
this.log(`重建 userdata 失败:${e.message}`);
return { ok: false, created: true, error: e.message };
}
}
/** emulator 自带 qemu-img.exe:把原始镜像文件撑到目标大小(稀疏,瞬间完成)
* 注意参数顺序:`qemu-img <命令> -f raw <文件> <大小>`。
* 把 -f 放命令前面会被它当成全局参数直接报 unrecognized option。 */
_qemuImg(op, ...rest) {
const exe = path.join(path.dirname(this.locate().emulatorExe), 'qemu-img.exe');
const r = spawnSync(exe, [op, '-f', 'raw', ...rest], {
cwd: path.dirname(exe), windowsHide: true, encoding: 'utf8',
});
if (r.status !== 0) throw new Error(`qemu-img ${op} 失败: ${(r.stderr || '').trim() || r.status}`);
}
/** emulator 自带 resize2fs.exe(cygwin 版,必须在 bin64 目录下跑才能找到 DLL) */
_resize2fs(img) {
const bin = path.join(path.dirname(this.locate().emulatorExe), 'bin64');
const exe = path.join(bin, 'resize2fs.exe');
if (!fs.existsSync(exe)) throw new Error('缺少 resize2fs.exe');
const r = spawnSync(exe, [img], {
cwd: bin, windowsHide: true, encoding: 'utf8', timeout: 180000,
});
if (r.status !== 0) throw new Error(`resize2fs 失败: ${(r.stderr || '').trim() || r.status}`);
}
/** emulator 依赖这些环境变量定位 SDK / AVD;中文路径一律转 8.3 短路径 */
env(root, plan = {}) {
const safeRoot = doctor.shortPath(root);
// AVD 目录必须与 provisioner.paths().avdHome 一致:bundled 只读运行时(EXE 旁
// resources/runtime)时 root/avd 不存在也不可写,AVD 要落到用户数据目录。
const avdHome = doctor.shortPath(this.provisioner.paths().avdHome);
const adbPort = String(plan.adbPort || process.env.ANDROID_ADB_SERVER_PORT || '5044');
return {
...process.env,
ANDROID_SDK_ROOT: safeRoot,
ANDROID_HOME: safeRoot,
ANDROID_AVD_HOME: avdHome,
ANDROID_EMULATOR_HOME: avdHome,
ANDROID_ADB_SERVER_PORT: adbPort,
ANDROID_EMULATOR_USE_SYSTEM_LIBS: '',
...(plan.accel === 'off' ? { ANDROID_I_WANT_MY_TCG: 'yes' } : {}),
};
}
buildArgs({
headless = true, accel = 'auto', port = 5554,
gpu = 'software', memoryMB = 2048, cores = 2,
snapshot = true, wipe = false, lcd = null,
} = {}) {
const args = [
'-avd', AVD_NAME,
'-port', String(port),
// 音频:默认开启(让安卓应用的提示音/视频声音能放出来)。
// 仅当用户在设置里显式关闭时才传 -no-audio 省一点 CPU。
...(this.settings?.engine?.audio === false ? ['-no-audio'] : []),
'-no-boot-anim',
'-no-metrics',
// 关掉崩溃上报:一旦历史崩溃报告存在,emulator 会弹「同意上传」模态框,
// 主线程被卡住、永远不开机(日志表现为 Showing crashdialog to get consent)。
'-crash-report-mode', 'disabled',
'-gpu', gpu,
'-memory', String(memoryMB),
'-cores', String(cores),
];
// 网络:AOSP 模拟器默认走 QEMU 用户态 NAT(-netdev user),安卓侧拿到
// 10.0.2.x 的虚拟地址,出口直接复用主机的物理网卡 NAT 出去。
// 这种模式【不会】在 Windows 上创建任何虚拟网卡 / 虚拟交换机
// (那必须 -netdev tap 或桥接才会发生,我们全程不启用)。
// 所以安卓应用用的是"一台挂在主机 NAT 后面的设备",主机网络栈完全不动,
// 不需要装驱动、也不多一个网络适配器。
// 显式声明不限速:默认值虽然是 full,但某些 -gpu / -net 组合下会被带上
// 模拟器的保守配置,视频类应用(红果、抖音)首屏就会明显慢半拍。
args.push('-netdelay', 'none', '-netspeed', 'full');
// DNS:安卓默认用 10.0.2.3(转发到主机 DNS)。主机走 VPN / 公司网 / 某些运营商
// 时,一次解析能拖到几百毫秒,表现为「页面转圈半天才开始加载」。给一份国内公共
// DNS 作为首选,失败时系统仍会回退。用户可在设置里关掉(内网域名场景)。
if (this.settings?.engine?.fastDns !== false) {
args.push('-dns-server', '223.5.5.5,119.29.29.29');
}
if (lcd) args.push('-skin', `${lcd.w}x${lcd.h}`);
if (headless) {
args.push('-no-window');
} else {
// 注意:**不能再传 -no-skin**。它会覆盖上面的 -skin,让面板尺寸退回
// config.ini 里的旧值 —— 表现就是「设置里切了横屏、实际还是竖屏」,
// 以及「画面只占左上角一条」。面板尺寸必须由 -skin 决定。
// 设备外壳本来就不会画(ShowDeviceFrame=no + 下面这组 style 参数)。
// 注意:不能用 -qt-hide-window。它会让模拟器**根本不创建**那个 Qt 窗口,
// 而窗口代理正是靠 SetParent 把这个窗口嵌进应用窗口来显示画面的 ——
// 用了它之后 probe 永远找不到窗口,用户看到的是一个全黑的应用窗口。
// 窗口的隐藏改由窗口代理常驻压制完成(见 win/agent.ps1 的 QuietSweep)。
}
// 只有快照真的存在才传 -snapshot:全新 AVD(或快照刚被作废)时传了它,
// qemu 会一直等一份不存在的内存状态,进程活着但永远不开机——
// 上层只看到「开机超时」,接着换参数重试,反而被 AVD 锁挡成
// "Running multiple emulators with the same AVD"。
// 快照参数决定「下次开机是 8 秒还是 90 秒」,这里是第二个致命点:
// 老实现「没有快照就传 -no-snapshot」,而 -no-snapshot 同时禁掉了**退出时保存**,
// 于是第一次冷启动结束后永远产生不了快照,用户每次点开都是全量引导。
// 正确做法是 -no-snapshot-load:这次不加载(避免等一个不存在的快照),
// 但退出时照常把内存状态写成 apkstart,下次就直接恢复。
// 快照要占一份约 2~3GB 的 ram.bin(磁盘紧张的用户可以关掉,只影响启动速度)
const wantSnapshot = this.settings?.engine?.keepSnapshot !== false;
if (wipe) {
// 重置数据时不能加载旧快照(数据都对不上了),但**必须允许保存新快照**:
// 修复网络就是靠「重置后第一次开机有网 → 立刻存快照 → 下次恢复」这条链路,
// 老写法这里推的是 -no-snapshot,会把保存一起关掉,快照永远存不下来。
args.push('-no-snapshot-load');
} else if (!wantSnapshot) {
args.push('-no-snapshot');
} else if (snapshot !== false) {
args.push('-snapshot', SNAPSHOT_NAME);
// 网络自愈要求这次冷启动:快照可能是在「没网」时存的,恢复出来依旧没网。
if (!this.hasSnapshot() || this._coldBoot) args.push('-no-snapshot-load');
} else {
args.push('-no-snapshot');
}
if (wipe) args.push('-wipe-data');
if (accel === 'off') args.push('-accel', 'off');
return args;
}
/** 拉起单个进程(不做开机等待,开机等待在 start() 的 probe 循环里) */
spawnOnce(plan, { headless, onLog, logFile }) {
const loc = this.locate();
const env = this.env(loc.root, plan);
const args = this.buildArgs({
headless, accel: plan.accel, port: plan.port, gpu: plan.gpu,
memoryMB: plan.memoryMB, cores: plan.cores,
snapshot: plan.snapshot, wipe: plan.wipe, lcd: plan.lcd,
});
this._logWrite(logFile, `\n--- ${new Date().toISOString()} ${plan.label} ---\n${loc.emulatorExe} ${args.join(' ')}\n`);
const proc = spawn(loc.emulatorExe, args, {
cwd: path.dirname(loc.emulatorExe),
env,
windowsHide: true,
// detached: 让模拟器独立于 ApkStart 进程组。
// Electron 退出时会把自己创建的 job 对象关掉,顺带把子进程一起杀掉——
// 表现就是"关掉 ApkStart 再打开又要冷启动 20 多秒"。独立出去之后模拟器留着,
// 下次启动直接接管(见 Runtime.adoptExisting),点开就是秒进。
detached: true,
stdio: ['ignore', 'pipe', 'pipe'],
});
this.proc = proc;
try { proc.unref(); } catch (_) { /* ignore */ }
const pipe = (stream) => {
stream.setEncoding('utf8');
let buf = '';
stream.on('data', (chunk) => {
buf += chunk;
const lines = buf.split('\n');
buf = lines.pop() || '';
for (const l of lines) {
if (!l.trim()) continue;
this.log(l.trim());
this._logWrite(logFile, `${l.trim()}\n`);
}
});
};
pipe(proc.stdout);
pipe(proc.stderr);
proc.on('exit', (code) => {
this.lastExitCode = code;
const meaning = describeExitCode(code);
this.log(`emulator exit ${code}${meaning ? `(${meaning})` : ''}`);
this._logWrite(logFile, `emulator exit ${code}${meaning ? `(${meaning})` : ''}\n`);
this.proc = null;
onLog(`运行时已退出(code=${code}${meaning ? `,${meaning}` : ''})`);
});
proc.on('error', (e) => {
this.log(`spawn error: ${e.message}`);
this._logWrite(logFile, `spawn error: ${e.message}\n`);
this.proc = null;
});
// qemu 是 detached 的独立进程,等它真正起来再把优先级降下来。
// 不降的话 2~4 个 vCPU 线程会以 Normal 优先级和 Windows 桌面抢 CPU,
// 用户最直观的感受就是「一打开 ApkStart,鼠标就发飘、整机变卡」。
const perf = this.settings?.engine?.priorityMode === 'performance';
setTimeout(() => {
this.setPriority(perf ? 'normal' : 'below').catch(() => {});
}, 3500).unref?.();
return { proc, args };
}
/** 写模拟器日志:带大小滚动,避免长期使用把磁盘写满 */
_logWrite(file, text) {
const limit = Math.max(2048, Number(this.settings?.engine?.logLimitKB || 2048) * 4);
require('./logfile').append(file, text, limit);
}
/** 当前 /data 镜像的实际情况(设置页展示用,不启动安卓也能取) */
dataInfo() {
const dir = path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`);
const img = path.join(dir, 'userdata-qemu.img');
let bytes = 0;
try { bytes = fs.statSync(img).size; } catch (_) { /* 还没建 */ }
return {
avdDir: dir,
imageBytes: bytes,
imageGB: bytes ? Number((bytes / 1073741824).toFixed(1)) : 0,
configuredGB: Number(this.settings?.engine?.dataPartitionGB || 0),
};
}
/**
* 立即把 /data 分区扩容到指定大小(必须保证模拟器已停止,否则镜像被占用)。
* 走的是 ensureDataPartition 的就地扩容路径:qemu-img resize + resize2fs,
* 不重建、不丢已装应用与存档。
*/
resizeDataPartition(dataMB) {
const dir = path.join(this.provisioner.paths().avdHome, `${AVD_NAME}.avd`);
return this.ensureDataPartition(dir, dataMB);
}
/**
* 调整本机 qemu/emulator 进程的优先级(只匹配命令行里带本 AVD 名的进程)。
* level: idle(容器停放)| below(有应用在前台)| normal(性能优先)。
*/
setPriority(level = 'below') {
if (process.platform !== 'win32') return Promise.resolve(0);
const script = path.join(__dirname, 'win', 'priority.ps1');
if (!fs.existsSync(script)) return Promise.resolve(0);
return new Promise((resolve) => {
execFile('powershell.exe', [
'-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
'-File', script, '-Avd', AVD_NAME, '-Level', level,
], { windowsHide: true, timeout: 15000 }, (_err, out) => {
const m = /CHANGED=(\d+)/.exec(String(out || ''));
resolve(m ? Number(m[1]) : 0);
});
});
}
/** 强杀当前尝试(含 qemu 子进程树) */
async killAttempt() {
const proc = this.proc;
this.proc = null;
if (proc) {
try { proc.kill(); } catch (_) { /* ignore */ }
if (process.platform === 'win32' && proc.pid) {
try { spawn('taskkill', ['/PID', String(proc.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }); } catch (_) { /* ignore */ }
}
}
await sleep(800);
// proc 句柄常常已经没了(emulator.exe 启动完就退出,qemu 是 detached 的独立进程),
// 不按进程名兜底清一遍,下一轮就会被 AVD 锁挡成 FATAL。
await this.killOrphanProcesses().catch(() => {});
}
/**
* 重建本专用端口上的 adb server。
*
* 这里是「打开应用要等两分钟」最主要的元凶,历史实现只 kill-server 就返回了:
* emulator 在启动瞬间会去连 ANDROID_ADB_SERVER_PORT 上的 adb daemon,
* 连不上就**再也不注册这台设备** —— adb devices 里要么没有 emulator-5554,
* 要么永远停在 offline(日志里就是那句 "Unable to connect to adb daemon on port: 5044")。
* 于是上层 probe 一直拿不到 sys.boot_completed,白等 3 分钟超时后重试,
* 每次重试都是全量冷启动,快照也因为「设备不在线」保存不了,形成死循环。
*
* 所以必须先 kill(清掉旧设备记录)再 start,并等到端口真的在监听才返回。
*/
/** 供上层在 adb 传输卡住(offline / unauthorized)时主动重启一次 server */
async resetAdbServer() {
const port = Number(process.env.ANDROID_ADB_SERVER_PORT) || this.adbPort || 5044;
return this._resetAdbServer(port);
}
async _resetAdbServer(adbPort) {
let adb = 'adb';
try { adb = this.provisioner.adbVersionPath() || 'adb'; } catch (_) { /* 用 PATH 里的 */ }
const env = { ...process.env, ANDROID_ADB_SERVER_PORT: String(adbPort) };
const run = (args, timeout) => new Promise((resolve) => {
try {
execFile(adb, args, { timeout, windowsHide: true, env }, () => resolve());
} catch (_) { resolve(); }
});
await run(['kill-server'], 6000);
await run(['start-server'], 12000);
// adb start-server 在部分机器上同步返回得很快,但端口还没真正 listen,
// 这里等到能连上为止(最多 ~3 秒,正常几十毫秒)。
const net = require('net');
for (let i = 0; i < 25; i += 1) {
// eslint-disable-next-line no-await-in-loop
const alive = await new Promise((resolve) => {
const sock = net.connect({ host: '127.0.0.1', port: Number(adbPort) });
let done = false;
const fin = (v) => { if (done) return; done = true; try { sock.destroy(); } catch (_) { /* ignore */ } resolve(v); };
sock.setTimeout(150, () => fin(false));
sock.once('connect', () => fin(true));
sock.once('error', () => fin(false));
});
if (alive) return true;
// eslint-disable-next-line no-await-in-loop
await sleep(120);
}
return false;
}
/**
* 等待「spawn 后马上退」的情况。
* 参数错误/DLL 缺失时 emulator 通常 1 秒内就退;进程还在则立刻返回,
* 不必再干等固定 2.5 秒 —— 快照恢复时这段时间足够开机跑完一半。
*/
_waitSpawnSettled(ms = 900) {
const proc = this.proc;
if (!proc) return Promise.resolve(true);
return new Promise((resolve) => {
let done = false;
const onExit = () => fin(true);
const fin = (exited) => {
if (done) return;
done = true;
clearTimeout(timer);
try { proc.removeListener('exit', onExit); } catch (_) { /* ignore */ }
resolve(exited);
};
const timer = setTimeout(() => fin(false), ms);
proc.once('exit', onExit);
});
}
/**
* 让「下一次启动」强制冷启动(不加载快速启动快照)。
*
* 快照里连网卡状态一起被保存:如果快照是在「没网」的时候存的,之后每次恢复都会
* 继续没网。网络自愈时先冷启动一次能绕开这份坏快照。
*/
forceColdBootOnNextStart() { this._coldBoot = true; }
/**
* 让「下一次启动」带上 -wipe-data(仅「修复网络」在多种尝试都失败后使用)。
* 「删掉 userdata 镜像文件」与 emulator 的 `-wipe-data` 并不等价,必须走后者。
*/
forceWipeOnNextStart() { this._forceWipe = true; }
/**
* 体检虚拟机内是否真的能联网。
*
* 为什么需要这一步:安卓虚拟机的 Wi-Fi 配置存在 /data 里,一旦写坏(典型表现是
* `cmd wifi list-networks` 里同一个 AndroidWifi 出现两条、网络 id 撞车),
* wlan0 就会一直 NO-CARRIER、拿不到 IP。这时「需要联网的页面」在应用里就是一块
* 黑屏 —— 用户看到的「红果点同意后黑屏」就是这么来的,跟 GPU/渲染完全无关。
*
* @param {string} [adbPath] 显式指定 adb 可执行文件(Runtime 有更权威的解析)
* @returns {Promise<{ok:boolean, reason:string, gateway?:string, ip?:string}>}
*/
async checkNetwork(adbPath = '', { waitMs = 0, interval = 3000 } = {}) {
const fs = require('fs');
const path = require('path');
let adb = adbPath || '';
if (!adb) {
try { adb = this.provisioner.adbVersionPath() || ''; } catch (_) { adb = ''; }
}
if (!adb) {
// adbVersionPath() 只查「版本文件」,很多安装形态下是空的;
// 直接按运行时根目录找 bundled 的 platform-tools 才稳。
try { adb = path.join(this.locate().root, 'platform-tools', 'adb.exe'); } catch (_) { adb = ''; }
}
if (!adb || !fs.existsSync(adb)) adb = 'adb';
const port = Number(process.env.ANDROID_ADB_SERVER_PORT) || this.adbPort || 5044;
const env = { ...process.env, ANDROID_ADB_SERVER_PORT: String(port) };
const sh = (cmd, timeout = 8000) => new Promise((resolve) => {
try {
execFile(adb, ['-s', this.serial, 'shell', cmd], { timeout, windowsHide: true, env }, (e, out) => {
resolve(e ? '' : String(out || ''));
});
} catch (_) { resolve(''); }
});
// 安卓的多路由表会让 `ip route` 的主表看起来是空的(默认路由在 per-interface 表里),
// 而且 shell 的 uid 不在应用的 network 组里,`ping` 经常误报 "Network is unreachable",
// 哪怕 Wi-Fi 其实已经连上、应用也能正常上网。所以这里只认「有没有拿到 IPv4 地址」,
// 再叠加 `cmd wifi status` 的连接状态做交叉确认,不用 ping 判断。
const addr = await sh('ip -o addr');
const ips = [];
const re = /inet ((?:\d{1,3}\.){3}\d{1,3})\//g;
let m = re.exec(addr);
while (m) {
const ip = m[1];
if (!/^127\./.test(ip)) ips.push(ip);
m = re.exec(addr);
}
const wifi = await sh('cmd wifi status');
const connected = /Wifi is connected/i.test(wifi);
if (!ips.length) {
// Wi-Fi 关联 + DHCP 往往比 sys.boot_completed 晚几十秒才完成。
// 调用方给了 waitMs 就继续等,不要在这一刻就断定「没有网络」。
if (waitMs > 0) {
const t0 = Date.now();
while (Date.now() - t0 < waitMs) {
// eslint-disable-next-line no-await-in-loop
await new Promise((r) => setTimeout(r, interval));
// eslint-disable-next-line no-await-in-loop
const again = await this.checkNetwork(adbPath, { waitMs: 0 });
if (again.ok) return again;
}
}
return { ok: false, reason: connected ? 'no-ip-address' : 'wifi-not-connected', addrs: ips };
}
const ip = ips[0];
const gw = /^10\.0\.2\./.test(ip) ? '10.0.2.2' : ip.replace(/\.\d+$/, '.1');
return { ok: true, reason: '', gateway: gw, ip, wifiConnected: connected };
}
/**
* 启动 + 自动重试。
* @param {Function} probe 异步回调,返回 'ok' | 'pending' | 'fatal'
*/
async start({ headless = false, onLog = () => {}, probe = null, maxAttempts = 4 } = {}) {
if (this.proc && !this.proc.killed) {
return { ok: true, reused: true, serial: this.serial, port: this.port };
}
const loc = this.locate();
if (!loc.emulatorExe) throw new Error('未安装运行时引擎,请先在「运行时」页完成部署');
const choice = this.imageChoice();
if (choice.compat ? !this.provisioner.playImageInfo().ok : !this.provisioner.systemImageInfo().ok) {
throw new Error('系统镜像未就绪,请先在「运行时」页下载 Android 系统镜像');
}
const s = this.settings;
// 开机前先看一眼磁盘:模拟器写的是 AVD(数据分区 + 快照,几个 GB),
// 只有它所在磁盘的余量才决定能不能开机;运行时目录只写日志,要求低得多。
// 之前把两者的余量取最小值,结果「数据目录已经挪到 D 盘、C 盘只剩 400MB」
// 会被误判成磁盘不足 —— 挪盘等于白挪。
const avdHome = this.provisioner.paths().avdHome;
const avdFreeMB = doctor.freeDiskMB(avdHome);
const diskMB = doctor.freeDiskMB(loc.root);
const needMB = 2500;
if (avdFreeMB && avdFreeMB < needMB) {
const msg = `磁盘空间不足:安卓数据目录(${avdHome})所在磁盘只剩 ${(avdFreeMB / 1024).toFixed(1)} GB,`
+ `运行时至少要 ${(needMB / 1024).toFixed(1)} GB 可用。请在「设置 → 系统集成 → 安卓数据目录」`
+ '把它改到空间充足的盘(例如 D:),或先清理磁盘。你的应用与存档不会被自动删除。';
this.log(msg);
onLog(msg);
return { ok: false, error: msg, needsSpace: true, attempts: [] };
}
if (diskMB && diskMB < 300) {
const msg = `运行时目录(${loc.root})所在磁盘只剩 ${(diskMB / 1024).toFixed(1)} GB,`
+ '连日志和临时文件都写不下。请清理磁盘,或把「运行时数据目录」也换到别的盘。';
this.log(msg);
onLog(msg);
return { ok: false, error: msg, needsSpace: true, attempts: [] };
}
const adbPort = await doctor.freeAdbPort(Number(process.env.ANDROID_ADB_SERVER_PORT) || 5044);
// 让本进程里所有 adb 调用和 emulator 用同一个 server 端口
process.env.ANDROID_ADB_SERVER_PORT = String(adbPort);
this.adbPort = adbPort;
// 这四件事互不依赖,并行做:以前是「加速检查 → 版本 → 探端口 → 清 adb server」串行,
// 冷启动前白等 3~5 秒,正好是用户点开应用后盯着加载框的那段时间。
// 上一次运行留下的 adb server 可能还挂着旧设备记录(会把新模拟器挤成 offline),
// 所以清 server 仍然要做,只是不必单独等它。
const [accelInfo, verInfo, startPort] = await Promise.all([
this.provisioner.emulatorAccel(),
this.provisioner.emulatorVersion(),
doctor.freePortPair(5554),
this._resetAdbServer(adbPort),
]);
const emuVersion = verInfo.version || '';
this._emuVersion = emuVersion;
// 与设置页 / 诊断报告共用同一个入口,保证「显示的」就是「实跑的」
const profile = doctor.autoProfile({
settings: s, accel: accelInfo, emulatorVersion: emuVersion, diskMB,
port: startPort, adbPort,
});
this.profile = profile;
const variants = doctor.planVariants(profile).slice(0, maxAttempts);
// 记住「上次拉起就崩」的 GPU 后端,下次把它排到最后。
// 实测:AMD Radeon 780M 上 `-gpu host` 能通过 emulator 自己的硬件检查,
// 但 VM 起来十几秒后进程直接 exit 1(日志里只有 "AEHD is operational"),
// 每次都要白等 20 多秒再退到 swangle。key 里带上 emulator 版本,
// 升级运行时后自动重新给它一次机会。
const badGpuKey = this.settings.engine.badGpu || '';
const [badVer, badGpu] = badGpuKey.includes('|') ? badGpuKey.split('|') : ['', ''];
if (badGpu && badVer === emuVersion) {
const rank = (v) => (v.gpu === badGpu ? 1 : 0);
variants.sort((a, b) => rank(a) - rank(b));
if (variants[0] && variants[0].gpu === badGpu && variants.length > 1) {
onLog(`上次 ${badGpu} 渲染后端启动即崩溃,本次改用 ${variants[1].gpu} 先试`);
}
}
const logFile = path.join(store.DATA_DIR, 'logs', 'emulator.log');
fs.mkdirSync(path.dirname(logFile), { recursive: true });
this._logWrite(logFile, `\n\n=== ${new Date().toISOString()} START ${doctor.describeProfile(profile)} ===\n`);
// 屏幕规格在整个启动过程中保持一致,否则每次重试都换分辨率会狂清快照。
// 分辨率来自 doctor 的 profile(设置里可改「画质」),auto 时按加速状态选。
const screen = (profile && profile.lcd) || doctor.lcdFor({ accelOk: accelInfo.ok });
this.attempts = [];
this.lastDiagnosis = null;
let lastError = '';
// 冷启前先清孤儿:上一次运行留下的 qemu 仍占着 AVD 锁时,
// 所有尝试都会立刻 FATAL "Running multiple emulators with the same AVD"。
// eslint-disable-next-line no-await-in-loop
await this.killOrphanProcesses({ onLog }).catch(() => {});
for (let i = 0; i < variants.length; i += 1) {
const base = variants[i];
// 端口占用也会导致失败,每次重试重新探测一次
// eslint-disable-next-line no-await-in-loop
const port = i === 0 ? startPort : await doctor.freePortPair(startPort + (i * 2));
const plan = { ...base, port, adbPort, lcd: screen };
this.port = port;
// 每轮重置退出码:上一轮 0xC0000005 不能带进下一轮的诊断里
this.lastExitCode = null;
// 日志也按轮切分:内存日志是跨轮累积的,第 1 轮的崩溃行若留在尾部,
// 第 2 轮(比如换后端后端口冲突)会被误诊成同一个崩溃。
const logStart = this._log.length;
onLog(`启动运行时(第 ${i + 1}/${variants.length} 次:${plan.label})…`);
// eslint-disable-next-line no-await-in-loop
const avd = this.ensureAvd({
...plan,
// _forceWipe 也要参与「删旧快照」:重置数据后旧快照必然加载失败
// (实测报 Failed to load snapshot 后退回冷启动),必须先清掉再重建。
wipe: plan.wipe || !!this.wipePending || !!this._forceWipe,
});
// 埋点:上层(main)用它在拉起模拟器**之前**打开黑窗压制。
// 控制台窗口在 spawn 之后几十毫秒就冒出来,事后再补一次扫描必然闪一下,
// 所以这里必须先把它打开、再拉起进程。
if (this.onBeforeSpawn) {
// eslint-disable-next-line no-await-in-loop
try { await this.onBeforeSpawn(); } catch (_) { /* ignore */ }
}
// eslint-disable-next-line no-await-in-loop
const forceWipe = !!this._forceWipe;
this._forceWipe = false;
// _coldBoot 只对这次 spawn 生效,避免之后每次开机都退化成长时间冷启动
this.spawnOnce({ ...plan, wipe: plan.wipe || avd.wipePending || forceWipe }, { headless, onLog, logFile });
this._coldBoot = false;
// 参数错误 / DLL 缺失会立刻退出
// eslint-disable-next-line no-await-in-loop
const dead = await this._waitSpawnSettled(2200);
if (dead || !this.proc) {
const d = doctor.diagnose(this._attemptLines(logStart, 60));
this.attempts.push({ plan: plan.label, diagnosis: d.code, exitCode: this.lastExitCode });
this.lastDiagnosis = d;
lastError = `${d.title}:${d.hint}`;
// 磁盘写满不是「换组参数就能好」的问题:继续重试只会反复失败,
// 而且历史上最后那组参数带 wipe,会把用户数据一起抹掉。直接收工、如实报错。
if (d.code === 'DISK_FULL') {
onLog('磁盘空间不足,已停止重试(不会动你的应用与存档)。');
this._persistFailure({ profile, why: 'disk-full' });
return { ok: false, error: lastError, needsSpace: true, attempts: this.attempts, exitCode: this.lastExitCode };
}
// 加速/镜像类结论可能是缓存里的旧数据,作废掉,下次启动重新探测
if (['ACCEL', 'GPU_INIT', 'GPU_MODE', 'IMAGE', 'DLL', 'ACCESS_VIOLATION'].includes(d.code)) {
try { this.provisioner.invalidateEnvCache(); } catch (_) { /* ignore */ }
}
onLog(`${d.title},自动换一组参数重试…`);
this._noteGpuFailure(plan);
continue;
}
if (!probe) {
return { ok: true, serial: this.serial, port, accel: accelInfo, logFile, profile, attempts: this.attempts };
}
const started = Date.now();
const timeout = plan.bootTimeoutMs || 240000;
let ok = false;
let fatal = false;
let sawBooting = false;
// 快照恢复往往几秒内就能起,固定 3 秒一次意味着平均要多等 1.5 秒才「发现」
// 它已经好了。这里从 200ms 起步逐步放宽到 1.2 秒:开机早期能立刻抓到,
// 长引导过程也不会把 CPU 花在轮询上。
let interval = 200;
let lastNotice = 0;
// eslint-disable-next-line no-await-in-loop
while (Date.now() - started < timeout) {
if (!this.proc) { fatal = true; break; }
let state = 'pending';
try {
// eslint-disable-next-line no-await-in-loop
state = await probe({ serial: this.serial, port, adbPort });
} catch (_) { state = 'pending'; }
if (state === 'ok') { ok = true; break; }
if (state === 'fatal') { fatal = true; break; }
// 只要 adb 能执行 shell,说明内核已经在引导,日志里的普通 Vulkan/EGL 信息不算失败
if (state === 'booting') sawBooting = true;
// 45 秒仍完全没连上,且日志出现明确致命错误 → 提前换方案,不干等 4 分钟
if (!sawBooting && Date.now() - started > 45000) {
const d = doctor.diagnose(this._attemptLines(logStart, 80));
if (['GPU_INIT', 'ACCEL', 'GPU_MODE', 'IMAGE', 'DLL', 'MEMORY', 'ACCESS_VIOLATION'].includes(d.code)) {
this.lastDiagnosis = d;
try { this.provisioner.invalidateEnvCache(); } catch (_) { /* ignore */ }
fatal = true;
break;
}
}
// 每 15 秒一条进度:以前用「取模」判断,自适应间隔下会连着打两三条重复的
if (Date.now() - lastNotice > 15000) {
lastNotice = Date.now();
onLog(`正在开机… ${Math.round((Date.now() - started) / 1000)}s`);
}
// eslint-disable-next-line no-await-in-loop
await sleep(interval);
interval = Math.min(1200, Math.round(interval * 1.6));
}
if (ok) {
const bootMs = Date.now() - started;
// 这一次真的起来了:清掉上次的失败记录,避免以后「诊断」翻出旧账
this._clearFailure();
// 一定要存 quickboot 快照:模拟器进程会随 ApkStart 退出而结束(Electron 的
// job 对象会连带杀掉子进程),下次打开有没有快照直接决定是 25 秒还是 7 秒。
// 装完新应用时 installer 会作废快照,避免"重启后应用消失"。
this.snapshotWorthSaving = true;
onLog(`运行时就绪(${Math.round(bootMs / 1000)}s,${plan.label})`);
// 开机成功不等于能用:顺手体检网络。虚拟机没网时,需要联网的页面会一直黑屏,
// 用户只会说「这个应用黑屏」,很难联想到是网络。这里主动查一次并说清楚。
let network = null;
try { network = await this.checkNetwork(); } catch (_) { /* 体检失败不算启动失败 */ }
if (network && !network.ok) {
onLog('⚠ 安卓虚拟机当前没有网络:需要联网的应用(如红果、短剧类)打开后会一直黑屏。'
+ '可在「设置 → 修复网络」重置安卓数据来修(应用清单会保留,点开时会自动重装)。');
}
return {
ok: true, serial: this.serial, port, accel: accelInfo, logFile,
profile, attempts: this.attempts, bootMs, quickBoot: true, network,
};
}
const attemptLines = this._attemptLines(logStart, 80);
const d = fatal ? (this.lastDiagnosis || doctor.diagnose(attemptLines)) : doctor.diagnose(attemptLines);
this.attempts.push({ plan: plan.label, diagnosis: d.code, timeout: !fatal, exitCode: this.lastExitCode });
this.lastDiagnosis = d;
lastError = fatal ? `${d.title}:${d.hint}` : '开机超时(可能是首次引导较慢或硬件加速未生效)';
onLog(`${lastError},自动换一组参数重试…`);
this._noteGpuFailure(plan);
// eslint-disable-next-line no-await-in-loop
await this.killAttempt();
}
const d = this.lastDiagnosis || doctor.diagnose(this.recentLog(120));
const report = doctor.writeReport({
dataDir: store.DATA_DIR, profile, logLines: this.recentLog(300),
extra: {
attempts: this.attempts,
diagnosis: d,
image: choice,
exitCode: this.lastExitCode,
exitMeaning: describeExitCode(this.lastExitCode),
},
});
const err = new Error(
`运行时多次尝试仍未能启动(${d.title})。\n${d.hint}\n\n`
+ `已尝试:${this.attempts.map((a) => `${a.plan} → ${a.diagnosis}`).join(';')}\n`
+ `诊断报告:${report.file}`,
);
err.diagnosis = d;
err.report = report.file;
err.attempts = this.attempts;
this._persistFailure({ profile, why: 'boot-failed', report: report.file });
throw err;
}
running() { return !!(this.proc && !this.proc.killed); }
/**
* 保存 quickboot 快照(下次开机直接恢复内存状态,像 WSA/应用宝的快速启动)。
*
* 时机很重要:以前的实现是开机后 6 秒就存,正好和用户点开应用抢磁盘 I/O
* (快照要写 1~3GB),体感反而更慢。改成「空闲时再存」,并由 Runtime 在
* 最后一个应用窗口关闭时触发;关机前若还没来得及存,也会补一次。
*/
async saveSnapshotNow(adbPath, { timeout = 45000 } = {}) {
if (!adbPath) return false;
const ok = await this._saveViaAdb(adbPath, { timeout });
// emulator 的 save 命令可能在写盘中途就回 OK,这里按文件完整性再确认一次,
// 只有 snapshot.pb 真正落盘才算数(否则下次加载会失败并白等几秒)。
if (!ok) return false;
return this.hasSnapshot();
}
/**
* 安排一次「空闲时保存快照」。
* 只排一次;如果到点时容器还有应用在前台,就推迟到真正空闲。
*/
scheduleSnapshotSave(adbPath, { delay = 20000, isIdle = () => true } = {}) {
if (!adbPath) return;
if (this._snapTimer) clearTimeout(this._snapTimer);
const arm = (ms) => {
this._snapTimer = setTimeout(async () => {
this._snapTimer = null;
if (!this.running()) return;
if (!isIdle()) { arm(15000); return; }
// 磁盘余量不够写快照(内存大小 + 1GB 余量)就跳过:硬写只会把磁盘写满,
// 进而让下一次开机直接失败。快照只影响启动速度,不写也不影响数据。
const freeMB = require('./doctor').freeDiskMB(store.DATA_DIR);
const needMB = Math.round(Number(this.profile?.memoryMB || 3072) * 1.15) + 1024;
if (freeMB && freeMB < needMB) {
this.log(`跳过快照保存:磁盘剩余 ${(freeMB / 1024).toFixed(1)}GB < 需要 ${(needMB / 1024).toFixed(1)}GB`);
return;
}
await this.saveSnapshotNow(adbPath).catch(() => false);
this._snapSaved = true;
}, ms);
if (this._snapTimer.unref) this._snapTimer.unref();
};
arm(delay);
}
cancelSnapshotSave() {
if (this._snapTimer) clearTimeout(this._snapTimer);
this._snapTimer = null;
}
/** 优雅停止:慢机器先保存 quickboot 快照,再走控制台关机,最后强杀进程树 */
async stop({ adbPath } = {}) {
if (!this.proc) {
// 接管来的实例没有 proc 句柄,但端口上确实有机器在跑,不能直接返回 true 走人
if (!(await this._anyEmulatorPortAlive())) return true;
}
this.cancelSnapshotSave();
const serial = this.serial;
if (adbPath && this.snapshotWorthSaving !== false) {
// 关机前补存一次:空闲路径没来得及存(比如用户装完应用马上退出)时,
// 下一次开机仍然能走快照恢复,而不是重新冷启动。
// 3GB 内存写盘要几秒到二十几秒,超时给足,别让快照写一半就被 kill 掉。
await this._saveViaAdb(adbPath, { timeout: 60000 });
}
if (adbPath) {
await new Promise((resolve) => {
execFile(adbPath, ['-s', serial, 'emu', 'kill'],
{ timeout: 10000, windowsHide: true }, () => resolve());
});
}
// 等它自己走完「落盘 → 退出」的流程。以前固定等 6 秒就强杀,
// 正好把快照写盘掐断,留下一个只有 ram.img 没有 snapshot.pb 的空壳。
//
// 注意不能等 this.proc:emulator.exe 只是个启动器,spawn 完 qemu 自己就退了,
// 拿它的 exit 当「关机完成」会立刻进入强杀分支。这里以控制台端口为准。
for (let i = 0; i < 100 && (await this._consoleAlive()); i += 1) {
// eslint-disable-next-line no-await-in-loop
await sleep(300);
}
await this.killAttempt();
return true;
}
/**
* 记下「拉起就崩」的 GPU 后端,下次启动把它排到最后。
* 只对 auto 模式生效:用户显式指定后端时尊重用户选择,不偷偷改。
*/
_noteGpuFailure(plan) {
try {
const gpu = plan && plan.gpu;
if (!gpu) return;
// 软件渲染是兜底项,它已经是最慢/最稳的选择,没有更差的替代品可退
if (/software|swiftshader|swangle/.test(gpu)) return;
if ((this.settings.engine.gpuMode || 'auto') !== 'auto') return;
store.saveSettings({ engine: { badGpu: `${this._emuVersion || ''}|${gpu}` } });
} catch (_) { /* ignore */ }
}
/** 本实例的控制台端口(5554)上是否还有机器在跑 —— 判断「到底关干净了没有」 */
_consoleAlive() {
const net = require('net');
const port = this.port || 5554;
return new Promise((resolve) => {
const sock = net.connect({ host: '127.0.0.1', port });
let done = false;
const fin = (v) => { if (done) return; done = true; try { sock.destroy(); } catch (_) { /* ignore */ } resolve(v); };
sock.setTimeout(200, () => fin(false));
sock.once('connect', () => fin(true));
sock.once('error', () => fin(false));
});
}
/** 用 adb 触发一次快照保存(失败返回 false,调用方决定要不要再试) */
_saveViaAdb(adbPath, { timeout = 45000 } = {}) {
return new Promise((resolve) => {
execFile(adbPath, ['-s', this.serial, 'emu', 'avd', 'snapshot', 'save', SNAPSHOT_NAME],
{ timeout, windowsHide: true }, (err) => resolve(!err));
});
}
recentLog(n = 40) { return this._log.slice(-n).map((x) => x.line); }
/**
* 只取「本轮启动尝试」产生的日志行。
* 内存日志是跨轮累积的(诊断报告要看到全部尝试),但诊断结论必须只看本轮:
* 否则第 1 轮的 `emulator exit 3221225477` 会让第 2 轮的任何失败都被判成同一个崩溃。
* 本轮一条日志都没有时(进程压根没起来)退回整体尾部,至少给个结论。
*/
_attemptLines(from, max = 80) {
const lines = this._log.slice(Math.max(0, from || 0)).map((x) => x.line);
return lines.length ? lines.slice(-max) : this.recentLog(max);
}
/**
* 从 emulator.log 文件尾部读最近 n 行(内存缓冲为空时用)。
* 用户重启 ApkStart 再导出诊断报告时,内存里的 this._log 已经空了,
* 旧版报告因此只剩一句 UNKNOWN —— 真实崩溃原因全在日志文件里。
*/
tailLogFile(n = 300) {
try {
const file = path.join(store.DATA_DIR, 'logs', 'emulator.log');
const size = fs.statSync(file).size;
const take = Math.min(size, 2 * 1024 * 1024);
const fd = fs.openSync(file, 'r');
try {
const buf = Buffer.alloc(take);
fs.readSync(fd, buf, 0, take, size - take);
const lines = buf.toString('utf8').split(/\r?\n/);
// 从头读的话第一行可能被截断,丢掉它
if (take < size) lines.shift();
return lines.slice(-n);
} finally { fs.closeSync(fd); }
} catch (_) { return []; }
}
}
module.exports = { EmulatorEngine, AVD_NAME, SNAPSHOT_NAME };