Windows 上的安卓应用运行器:双击 APK 即装,应用以独立窗口与桌面图标运行,自持 QEMU 运行时
运行时栈代码走读(sources / download / provision / updater / store / layers / 小工具)
代码版本:
package.json= 0.3.5,main=src/main.js。 行号对应当前工作副本(D:\apkstart-dsh\apkstart),文件可能已变动,引用前请以函数名为准再核一次行号。 阅读范围:src/core/{sources,download,provision,updater,store,layers,logfile,notify,android,display}.js, 顺带读了调用方src/main.js/src/core/{engine,emulator,installer}.js与test/。 本文只描述代码事实;「✓」= 有测试,「✗」= 无覆盖。
依赖方向(重要,避免循环 require):
main.js ──> engine.js ──> provision.js ──> sources.js ──> version.js
│ │ │ │
│ │ │ └──> download.js
│ │ └─────> store.js / doctor.js / zip.js
│ ├──> emulator.js ──> provision.js / logfile.js
│ └──> layers.js ──> store.js(summary 内延迟 require)
├──> updater.js ──> sources.js / download.js / zip.js / version.js
├──> installer.js ──> store.js / provision.js(通过 runtime.provisioner)
└──> android.js / notify.js / display.js / logfile.js
version.js 单独存在的原因写在 version.js:2-4:避免 updater ↔ sources 互相 require 形成环。
1. src/core/sources.js — GitHub / Gitee 双源 + 镜像 + 测速 + 熔断缓存
职责
把「读版本信息」和「拿下载地址」抽象成一组按实测字节速度排序的候选 URL,并对被限流/报错的源做短期熔断。
对外接口
| 导出 | 签名 | 说明 |
|---|---|---|
Sources |
new Sources(settingsFn) |
settingsFn: () => settings,每次判定时现读(不缓存设置) |
Sources#blockedReason |
(id: 'github'|'gitee') => string|null |
null = 可用;否则返回中文原因 暂时跳过(N 分钟内不再尝试)(230-234) |
Sources#fetchReleases |
() => Promise<Array<{source,name,web,rel?,error?}>> |
按 sourcePreference 决定问一边还是两边,Promise.all 并发(237-271);可被测试覆写 |
Sources#latest |
({force=false}) => Promise<Merged> |
合并后的版本信息(见下),10 分钟缓存(277-364) |
Sources#candidates |
(assetOrUrl: string|{url}|{urls:[]}) => string[] |
源站优先、镜像其次,去重保序(371-393) |
Sources#rank |
(urls, {onProgress}) => Promise<string[]> |
按 30 分钟内缓存的实测速度降序;≤1 个地址直接返回(399-432) |
Sources#reset |
() => void |
清测速缓存 + 版本缓存 + 熔断(435-439) |
SOURCES |
{github:{id,name,api,web}, gitee:{...}} |
常量,owner 写死在 22-24 |
measure |
(url, {bytes=256*1024, timeoutMs=9000}) => Promise<{url,ok,got,ms,ttfb,speed,error?}> |
真下 256KB 测吞吐(108-157) |
withMirror |
(url, prefix) => string |
前缀补尾斜杠;非 http(s):// 返回 ''(160-164) |
mirrorList |
(settings) => string[] |
自定义前缀唯一生效 → 其次 autoMirror!==false 时的内置镜像(207-213) |
KNOWN_MIRRORS |
['https://ghfast.top/','https://gh-proxy.com/'] |
42-45 |
latest() 返回结构(350-361):
{
version, tag, name, notes, htmlUrl, publishedAt,
assets: [{ name, size, url, urls: string[], sizes: { [url]: bytes },
parts?: [{index,size,urls:[]}], partial?: bool, source }],
sources: [{ source, name, tag }], // 参与合并的源
unreachable: [{ source, name, error }],
bySource, // 胜出源
stale?: true, staleReason? // 全部源挂掉但手里有旧结果(296)
}
关键实现
1) 版本获取 = 并发问两边 + 降级列表接口(248-269)
- 先
${api}/releases/latest,失败再${api}/releases?per_page=10取第一条非draft; - Gitee 私有仓库会回 404 "Not Found Project"(而不是 401),此时可填只读
runtime.giteeToken(243-246 会拼access_token); - 只有
403/429才记熔断,_blockMs = 15min(226、263)。熔断也在latest()里补记一次(286-290),注释说明是为了让「谁提供结果」可被测试替换(auto-test 就是这么注入的)。
2) 合并策略
- 版本号用
cmpVer取最高(299),然后只保留与该版本相同的资产(307-310); - 资产白名单:
/^ApkStart/i(316),排除 Gitee 自动挂的源码包; - 同名资产跨源合并成
urls[],并逐地址记sizes{}(334-348)——两个源压出来的字节数不同,绝不能平均; - 同版本既有整包又有分片时优先整包(326-327);
- 全部源失败但
_relCache.value存在 → 返回旧结果并打stale(292-298),避免界面直接报错。
3) 缓存三层
| 缓存 | 字段 | TTL | 失效 |
|---|---|---|---|
| 测速 | _rankCache: Map<url,{at,ok,speed}> |
30min(219) | reset();ok=false 也缓存,排序时记 -1(418-421) |
| 版本 | _relCache: {at,key,value} |
10min(223) | key 不匹配(sourcePreference 变了)/ force / reset() |
| 熔断 | _blocked: Map<sourceId, untilMs> |
15min(226) | reset() |
4) 测速是「串行」的(408-417):注释明确写了并发会互相抢带宽,测出来变成「谁抢得凶」。代价是最坏情况 候选数 × 9s(measure 的 timeoutMs)。
5) 吞吐只算「收到首字节之后」的时间(120-122):span = now - (firstAt || t0),把 TLS/DNS 固定开销排除;否则「延迟高但带宽大」的源会被误判成慢。
6) 分片还原 groupParts(172-204):xxx.zip.part1/.part2 → 逻辑资产 {name, size=Σ, parts:[{index,size,urls:[]}], partial:true};缺地址或序号不连续 → broken,被 list 过滤掉,broken 名单返回但 latest() 没有向外暴露。
坑点与不变量
- Gitee 单文件 100MiB(172-204 注释、
.github/release.yml:36-44,78-100):超限就切.part1/.part2;updater._downloadParts负责拼回。 - Gitee 资产条目没有
size(198-201):所以「完整性」只要求「分片连续 + 每片有地址」,不能要求size>0;大小未知时进度按已收字节显示。 - 源码包
v1.2.3.zip/.tar.gz会混进资产(313-316):靠^ApkStart白名单挡掉,\.zip$这种后缀匹配会把源码包当更新包下下来。 - 镜像只能套 GitHub 地址(366-369、385-390):ghfast / gh-proxy 只代理 GitHub,拼 Gitee 只会 403,白测一次速。
- 同名资产必须留全部地址(329-333):以前按名字去重「谁先来用谁」,GitHub 在前 → Gitee 地址被丢 → 自动选源退化成只用 GitHub。
SAMPLE_BYTES = 256KB(52),但provision.installRuntimePack:532的注释还写着「128KB」——注释已过期,实现是 256KB。measure里openUrl返回的是res(流),done()时req.destroy()关的是流不是请求对象(115-132 的req = res),能用但命名有误导性。groupParts对part0(从 0 开始)也会判broken(196 要求index === i+1)。- 不变量:
candidates()第一项永远是原始源站 URL(380-382),rank()只在length>1时排序(401),这是「最坏情况还能直连下载」的保底。
被谁调用
src/core/provision.js:16(require)、:145(new Sources(() => store.getSettings()))、:149-151(get sources)、:535(rank)、:588(candidates,_downloadUrls)。src/core/updater.js:23,47(new Sources(this.settings))、:74(latest)、:140-141(candidates+rank)、:191-196(分片各自candidates+rank)。src/main.js:819-825:设置里改了sourcePreference/mirrorPrefix/autoMirror→updater.sources.reset()+provisioner.sources.reset()。注意:这里不会清provisioner._cache.pack / emulatorUrl / sysimgUrl / playUrl(见 §3 坑点)。
测试覆盖(test/auto-test.js)
- ✓
:843候选地址含镜像前缀,自定义前缀优先于公共镜像 - ✓
:864测速结果按速度排序,全部失败时保持原序不丢可用地址(并验证reset()) - ✓
:878Gitee 自动附带的源码包(v1.2.3.zip)绝不能被当成安装包 - ✓
:901Gitee 资产没有size:分片组仍要成立 - ✓
:926分片资产必须一路传到updater.asset - ✓
:949合并版本时只认同版本资产 - ✓
:976同名整包两边都有时两个地址都留着 - ✓
:1282版本结果缓存 10 分钟,force强制重查 - ✓
:1300403 熔断跳过 +blockedReason文案 +reset()解除 - ✓
:1323全部源不可达时退回上次结果(stale)
2. src/core/download.js — 单流 / 分块 / 多源并行 + 断点续传 + 看门狗
职责
只依赖 http/https/fs 的四层下载器:单流续传 → 单源分块 → 多源分块(带宽叠加)→ 依次换源;全部带空闲看门狗与「保证 settle」保护。
对外接口
| 导出 | 签名 | 返回 |
|---|---|---|
openStream |
(url, {method='GET', headers={}, redirects=0}) => Promise<IncomingMessage> |
跟随 301/302/303/307/308(≤6 跳),socket 空闲超时 30s(15-36) |
head |
(url) => Promise<{status,size,type,error?}> |
永不抛,失败 status:0(38-50) |
sha256File |
(file) => Promise<hex> |
52-60 |
download |
(url, dest, opt) => Promise<{file,size}> |
opt = {onProgress,signal,expectSha256,retries=2,idleMs=30000} |
downloadParallel |
(url, dest, opt) => Promise<{file,size,parallel:n}> |
opt += {connections=8,minChunk=1MB,retries=3} |
downloadAny |
(urls, dest, opt) => Promise<{file,size,url}> |
依次试,全失败抛聚合错误(314-326) |
downloadMulti |
(urls, dest, opt) => Promise<{file,size,parallel,sources,multi,resumed}> |
opt += {minChunk=2MB,retries=6,idleMs=20000,slowAfterMs=45000,slowBps=120*1024}(338-548) |
downloadAnyParallel |
(urls, dest, opt) => Promise<{file,size,url}> |
依次用 downloadParallel(551-563) |
onProgress 回调体:{got,total,percent,speed,eta}(downloadMulti 额外带 sources)。
关键实现
1) download():单流 + 续传(68-173)
- 每次尝试前
statSync(dest).size→Range: bytes=existing-(75-77); 416视为「已完整」,直接break(82-86);200且existing>0= 服务器不支持续传 →rmSync后重写(97-100);- 非 200/206:最多重试
retries=2次,固定退避 1500ms(87-90); - 空闲看门狗
idleMs(默认 30s):kick()每次收到数据重置,超时res.destroy()+finish(Error('连接停滞(长时间无数据)'))(112-130)。注释(109-111)记录:连接静默时res既不end也不error,pipe永不finish,整个下载卡死且无报错; signal.abort→res.destroy(new Error('已取消'))(132-133);- 收尾强制
onProgress({percent:100})(162-163);expectSha256不符 → 删文件 + 抛错(165-171)。
2) downloadParallel():单源分块(180-311)
- 已有非空文件 → 直接退回
download(),避免分块状态丢失(188-191); - 探测 Range:
Range: bytes=0-0,206 +content-range才并行;total < minChunk*2也退回单流(193-210); n = min(connections, ceil(total/minChunk)),per = ceil(total/n)(212-213);- 先
ftruncateSync(fd,total)建空文件,再各块fs.writeSync(fd, buf, 0, len, pos)定位写(219-220、268); - 每块最多
retries=3,退避800 * triesms(285-300); - 结束校验
size === total,否则抛「下载不完整」(307-310)。
3) downloadMulti():多源分块(338-548)
list = 去重(urls);只有一个 →downloadParallel(350-352);Promise.all并发探测每个地址的content-range总大小(355-365);全部不支持 Range →downloadAnyParallel(367-370);- 基准总大小取
usable[0].total,即rank()排好序的第一个(最快的源),不是Math.max(371-377);只混用total === 该值的源(378-381); n = clamp(2..connections, ceil(total/minChunk)),块按i % same.length轮转分配源(384、409-416);- 分块断点续传边车
${dest}.chunks.json(391-405):只有m.total===total && m.n===n && dest 大小===total才认;否则删文件+删边车重下。完成的块doneSet.add(c.start)+saveMeta()(518-520); - 续传时把已完成块算进
got,进度不回到 0(425-427); - 低速换源:单块跑够
slowAfterMs=45s且平均 <slowBps=120KB/s,且c.rotates < 2→res.destroy()+ 抛「该源速度过低…换源重试」,c.pos保留(446-451、492-503)。注释点名现象:「卡在 95% 不动」; - 每块
retries=6(注释:3 次在「三个源里两个偶尔停摆」不够用),失败时c.src += 1换源,退避600 * tries(523-534); - 失败退出时
saveMeta()再抛(526-528),成功后rmSync(meta)(542)。
10) 「保证 settle」双保险:fetchChunk 里自己维护 settled + finish(),看门狗直接调用 finish,因为 res.destroy(err) 有时只发 close 不发 error(466-480)。
坑点与不变量
- 多源只能混用「声明总大小一致」的源(371-381),否则会拼出坏文件;大小不同(GitHub/Gitee 各压一份)时只走最快那个。
c.rotates必须显式初始化为 0(415 注释):undefined < 2是false,换源逻辑永远不触发(历史 bug)。- 每次请求只允许换一次源(459-463):同一条连接
destroy后仍可能收到已缓冲的包,会重复触发换源把源跳过头。 - 续传只对
download()与downloadMulti生效,downloadParallel见到半截文件就降级单流(188-191)——这是设计取舍,不是 bug。 provision.installQemu:1100传了{ resume: true },但download()根本没有resume选项(69),续传是自动的:该参数是无效/历史遗留。downloadMulti不处理opt.signal(只有download()处理),取消多源下载目前只能靠超时/抛错。download()的416分支会break并把「已存在文件」当作完整文件(82-86);若existing > total(上次写坏)不会自愈,只有expectSha256能兜住。openStream的timeout: 30000是 socket 空闲超时,没有单独 connect 超时;DNS 卡住时靠外层measure/rank的定时器。- UA 在
download.js:13是ApkStart/0.2,sources.js:64是ApkStart/0.3,两处不一致(无功能影响,仅日志/服务端统计)。 - 不变量:所有下载函数的
onProgress在成功结束前一定会被调一次percent:100(163、308、545),UI 不会停在 99%。
被谁调用
src/core/provision.js:14(require)、:434downloadAny(adb)、:541downloadMulti(运行时整包)、:912downloadAnyParallel(emulator)、:1010(play 镜像)、:1052(aehd)、:1143(ISO)、:628-629/:1071-1072openStream(抓索引/目录页)、:1226-1228head(probeSources)。src/core/updater.js:20,150(downloadMulti更新包)、:198(downloadAnyParallel每个分片)。test/engine-test.js:32;test/boot-test.js:23,38(真下 ISO,走test:boot)。
测试覆盖
test/engine-test.js
- ✓
:83完整下载 + 跟随重定向 - ✓
:89断点续传(已有半截文件) - ✓
:101HEAD 探测 + SHA256 - ✓
:108SHA256 校验失败会清理文件 - ✓
:118并行分块下载:多连接拼接内容一致 - ✓
:133源不支持 Range 时自动回退单流
test/auto-test.js(本地起 http 服务打真实字节)
- ✓
:995多源并行下载:两个源体积不同时跟最快的源走 - ✓
:1068不同分块从不同源拉,拼出来字节必须完全一致 - ✓
:1108失败后重来只补缺的块(边车) - ✓
:1155连接建立后一个字节都不来,必须超时换源而不是挂死 - ✓
:1198某个源只跑几十 KB/s 时换源,而不是卡在最后几 % 不动 - ✓
:1251只有一条可用地址时退回单源分块 - ✓
:1033分片更新包按顺序拼回整包,大小不符立刻中止(updater._downloadParts)
3. src/core/provision.js — 运行时自举(adb / emulator / system image / qemu / aehd)
职责
不依赖第三方模拟器,把 adb、emulator、系统镜像、AEHD、QEMU、虚拟磁盘全部「下载→校验→解压/安装→落盘」,并统一管理这些文件该放哪(paths())、够不够空间(guardDisk)、装没装好(checkEnv)。
对外接口(class Provisioner,导出 {Provisioner, SOURCES, MIN_SIZE, absUrl, baseOf})
| 成员 | 签名 | 说明 |
|---|---|---|
constructor |
(appRoot) |
140-146;内部 _sources = new Sources(() => store.getSettings()) |
get sources |
Sources |
149-151,与 updater 共用同一套镜像/测速设置 |
get root |
string |
settings.runtime.dir 或 %APPDATA%\apkstart\runtime(192-195) |
paths() |
Paths |
197-245,见下表 |
ensureDirs() |
Paths |
建 root/qemu/platform-tools/images/_tmp/avdHome(247-253) |
guardDisk |
(component, targetDir) => Promise<freeMB> |
不足直接抛中文错误(262-277) |
hypervisor |
() => Promise<{whpx,dll,hypervisorPresent,note}> |
只做毫秒级文件检查(281-296) |
adbVersion / qemuVersion / emulatorVersion |
() => Promise<{ok,path,version}> |
各带 30s 内存缓存(298-338、687-714) |
inspectIso |
(file) => {ok,iso9660,rawImage,size,reason,magic} |
读 0x8001 处 CD001(341-365) |
checkEnv |
() => Promise<Env> |
367-424,UI 的「状态」全靠它 |
installAdb |
(onProgress) => {ok,path,version} |
428-456 |
resolveRuntimePack |
() => {url,name,size,tag,page,from} |
476-516,Gitee/GitHub 并发找 ApkStart-runtime-*.zip |
installRuntimePack |
(onProgress) => {ok,name,tag} |
522-580,轻量版一键部署 |
extractZip |
(zipPath,destDir,{onEntry}) => destDir |
591-622,>64MB 用文件版 zip、大条目流式 |
resolveEmulatorUrl / resolveSysimgUrl / resolvePlayUrl / resolveQemuUrl |
() => Promise<string> |
从 Google 索引/目录页动态解析,落兜底常量 |
materializeImages |
(onLog) => Promise<count> |
722-794,.img.xz/.gz → .img(只做一次) |
systemImageInfo / playImageInfo |
() => {ok,dir,size,api,tag?,note?} |
797-839 / 972-980 |
emulatorAccel |
() => Promise<{ok,kind,note,...}> |
845-902,-accel-check + 落盘缓存 |
installEmulator |
(onProgress) => {ok,path,version} |
905-937 |
ensurePlatformTools / adbVersionPath |
() / () => bool / string |
940-955 / 957-963 |
installSystemImage |
(onProgress) |
966-969,等价于 installPlayImage(只有一份基础镜像) |
installPlayImage |
(onProgress) => playImageInfo |
1004-1044,顺手清 android-30 |
installAehd |
(onProgress) => {ok,dir,installer} |
1047-1062,只下载不解安装 |
installQemu |
(onProgress) => {ok,path,version} |
1090-1130,NSIS /S /D= 静默安装 |
downloadIso / inspectImage / importIso / importDisk |
1134-1195(QEMU 路线) | |
createDisk |
(sizeGB=24, onProgress) |
1199-1220,qemu-img create -f qcow2 |
probeSources |
() => {adb,qemu,iso} |
1224-1231,HEAD 探测三个固定 URL |
envCacheGet/Set, invalidateEnvCache, _envKey |
154-188,落盘环境探测缓存 |
paths() 返回(225-245):
{ root, qemuDir, qemuExe, qemuImg,
adbDir, adbExe,
emulatorDir, emulatorExe,
sysImgRoot, // ★ 见下方三分支
sysImgDir: <sysImgRoot>/android-34/google_apis_playstore/x86_64,
avdHome, aehdDir,
imagesDir, iso, disk, tmp,
sysTag:'google_apis_playstore', sysApi:'34', sysAbi:'x86_64' }
checkEnv() 返回(387-423):
{ adb:{ok,path,version,required}, emulator:{ok,path,version,required,note},
sysimg:{ok,dir,size,api,required,note}, playImage:{ok,dir,size,...},
accel:{ok,kind,note}, qemu:{ok,...}, iso:{ok,path,size,iso9660,reason,...},
disk:{ok,path,size,note}, hypervisor:{...},
ready, engine:'emulator'|'qemu'|'none', paths }
ready = adb.ok && (emulatorReady || qemuReady);emulatorReady = emulator.ok && (sysimg.ok || playImage.ok)(384、420)。
关键实现
1) paths() 的三条路径规则(197-245)——这是「镜像到底落在哪个盘」的唯一权威
root:settings.runtime.dir,空则%APPDATA%\apkstart\runtime(192-195)。avdHome(237):settings.runtime.avdDir,否则若 root 不在DATA_DIR下就用<DATA_DIR>/avd,否则<root>/avd(202-209)。理由(202-206):单文件发行版的运行时被解到临时目录,AVD 放进去等于每次退出丢应用。sysImgRoot三分支(217-224):<root>/system-images已存在 → 用它(整包解压产物);- 否则
<DATA_DIR>/system-images存在 → 用它(老用户/单文件发行版布局); - 两处都没有 → 落
<root>/system-images(全新安装;注释说明 CI 组装运行时靠这个,且DATA_DIR可能被重定向到临时目录)。
2) materializeImages()(722-794)
- 源目录固定
<root>/system-images(723),目标目录this.paths().sysImgRoot(726),注释明确要求两者用同一套规则,否则出现「整包解到 D 盘、镜像又展开回 C 盘 AppData」(实测 1.2GB + 3.3GB 并存)。 - 遍历:
.img.xz优先于.img.gz(foundMap,729-741);其它文件(kernel-ranchu/ramdisk.img/ 未压缩.img)必须一并复制(728、751-760),否则模拟器报「还差系统镜像」。 - 已展开判定:
fileSize(dest) > 32MB跳过(765)。 .xz解压必须绕过包的 ESM 入口(771-781):require.resolve('@napi-rs/lzma')取目录再require(dir/index.js),注释说明 Electron 的 Node 20 不支持require('stream-polyfill.mjs'),且exports不允许直接写/index.js。- 单个镜像失败只
onLog('展开镜像失败:…')(790),不向上抛。
3) installRuntimePack()(522-580)——轻量版的「一键」
resolveRuntimePack():自定义settings.runtime.runtimePackUrl优先(477-478,size:0);结果缓存到this._cache.pack,never invalidated(479、514);- 并发问 GitHub/Gitee 的
releases?per_page=15,找assets里/^ApkStart-runtime-.*\.zip$/i,按cmpVer取最高 tag(487-515); guardDisk('runtime', p.root)(525)→'runtime'不在need表里,落到 default 512MB + 1024MB buffer = 1536MB(264-266);rank(this._downloadUrls(pack.url))测速(534-536),失败退回原候选;downloadMulti(urls, tmp/runtime-pack.zip, {connections: settings.runtime.downloadConnections||8})(529、541-555);** 进度映射percent = clamp(1..90, pct*0.9)**(551);- 体积闸门:
< 200MB抛「运行时整包下载不完整,可重试续传」(556); extractZip(zip, p.root, {onEntry})(559-565),进度 91→99;- 写标记
<root>/.runtime-pack.json({name,tag,at,from})并删 zip(566-571); - 立刻
materializeImages(...).catch(() => 0)(573-576),注释说明否则紧接着的checkEnv()会认为没装镜像、又去 Google 下一套 1.4GB; - 返回
{ok,name,tag},进度 100。
4) extractZip()(591-622)
fileSize > 64MB→new ZipFile(path)(不整包进内存);否则new ZipArchive(fs.readFileSync(...));- 单个条目
uncompSize > 64MB走zip.pipeTo()流式,其余fs.writeFileSync(zip.read()); finally { zip.close() }(618-620)。
5) checkEnv()(367-424):Promise.all 起 5 个探测(adb/qemu/hypervisor/emulator/accel),再叠加 inspectIso、fileSize(disk)、systemImageInfo()、playImageInfo();sysimg.ok 被定义为 systemImageInfo().ok || playImageInfo().ok(381-399)。
6) 环境探测落盘缓存(126-188)
- 文件:
%APPDATA%\apkstart\cache\env.json(129-131); - key =
exe 路径 + exe(size:mtime) + aehd.sys(size:mtime) + WinHvPlatform.dll 存在与否(154-162); - TTL:可用结论 6h(126),不可用只信 10 分钟(127,用户可能刚开了虚拟化);
- 开机失败时
invalidateEnvCache()由 emulator 调用(emulator.js:848,886)。
7) emulatorAccel()(845-902):解析 -accel-check 文本;三条兜底规则:emulator-check 缺失但有 aehd.sys → 判可用(879-883,注释说明「避免误判无加速而强行 -accel off,软件模拟在部分机器上直接崩溃」);hasAehdFile && /aehd/ → 可用(884);hv.dll && /whpx/ → 可用(886);否则 viaTcg: true(888-897)。
8) 磁盘守卫 guardDisk()(262-277)
| component | need(MB) | + buffer 1024MB |
|---|---|---|
| adb | 64 | 1088 |
| emulator | 600 | 1624 |
| sysimg / playimg | 1800 | 2824 |
| qemu | 320 | 1344 |
| iso | 1100 | 2124 |
| aehd | 64 | 1088 |
未列(如 'runtime') |
512 | 1536 |
不足时抛:「目标磁盘空间不足:该组件约需 N MB…把『运行时数据目录』改到空间更大的盘(设置 → 系统集成 → 运行时数据目录 → 浏览)」。
坑点与不变量
- 镜像落点必须与
paths().sysImgRoot一致:installPlayImage解到p.sysImgRoot(1023),materializeImages目标paths().sysImgRoot(726),playImageInfo查p.sysImgRoot(974)。任何新代码若自己拼<DATA_DIR>/system-images就会复现「设了运行时目录还是下到 AppData」。 guardDisk('runtime')的估算偏低:512+1024=1536MB,而实际是「1.5GB 包 + 落盘 zip + 解出 3.3GB system.img + .xz 展开」。小盘机器会在解压阶段失败并留下半截文件(installRuntimePack没有清理半截 zip 的逻辑,靠下一次续传)。this._cache.pack/emulatorUrl/sysimgUrl/playUrl没有失效入口:main.js:819-825只sources.reset()。用户在设置里改了sourcePreference或换了整包地址,同一进程内仍用旧地址(runtimePackUrl例外,因为每次先读设置,477)。materializeImages的失败被两处吞掉:自身.catch(e => onLog(...))(790)+调用方.catch(() => 0)(576)。@napi-rs/lzma缺失/被杀软拦截 → 镜像永远展不开 →checkEnv().sysimg.ok === false→ 每次启动都重新走「下载运行时」路径(典型「卡在准备运行时」)。emulatorVersion()失败不缓存(687-714):ok:false直接 return,没有envCacheSet,也没有 30s 内存缓存;每次checkEnv()都会execFile(emulator.exe -version)最多 20s。成功路径才写缓存(707-710)。emulatorVersion缓存只在内存/落盘,_cache.emulatorVerAt只在成功时设置,失败路径会让状态轮询反复拉起进程。extractZip不校验 zip-slip:path.join(destDir, name)直接拼(606);updater._extract有startsWith(path.resolve(dest))防护(updater:237),两边不一致。运行时整包与更新包都来自本项目 release,风险低,但接手者别把extractZip用到不可信输入上。resolveRuntimePack()的自定义地址size: 0,下载进度只能靠探测或已收字节;installRuntimePack里total也因此为 0,mb文案会缺「/ 总大小」。installAdb解压到p.root(446),zip 顶层就是platform-tools/;installEmulator同理(926)。所以 root 同时是ANDROID_SDK_ROOT(232-234 注释)。ensurePlatformTools()(939-955):emulator 要求 SDK root 下有platform-tools,否则 FATAL;它从engine/platform-tools、tools/platform-tools、settings.adbPath所在目录复制 3 个文件(adb.exe+ 两个 dll)。installAehd只下载(1047-1062),安装要管理员:main.js:1121-1200走silent_install.bat+ UAC。- QEMU 安装:NSIS
/S /D=<dir>,/D必须最后且不加引号(1112-1116);setTimeout600s 后强杀(1119)。 systemImageInfo()(797-839):先在paths().sysImgDir找,再把sysImgRoot、<root>/system-images、<appRoot>/engine/system-images下所有android-*/tag/abi枚举一遍(按 API 降序),任何一套system.img > 300MB且有kernel-ranchu就算 ok。这是「完整版可能只带更小的 AOSP 镜像」的兼容点。playImageInfo()与sysimg.ok的关系:checkEnv().sysimg.ok把两者或起来(390-399),但engine.ensure()用的是env.sysimg.ok(engine.js:852),所以只有 play 镜像也能启动。- 不变量:所有
install*的onProgress都以{stage:'download'|'extract'|'install'|'done', percent}形式汇报,main.js:317统一加component,UI 侧app.js:357 updateStepProgress只读percent/message。 SOURCES里硬编码的兜底版本会过期(emulator-windows_x64-16847572.zip、x86_64-34_r14.zip,27-41),只在索引抓不到时使用。
被谁调用
src/core/engine.js:16,54(new Provisioner(appRoot))、:79,202,393,995(paths())、:109,235,368,635,849,996(checkEnv)、:264,761(emulatorAccel)、:639(createDisk)、:848(materializeImages)、:1017,1021(paths().root→ layers)、:873(needsSetup)。src/core/emulator.js:17,29、:53,225(paths/ensureDirs)、:56,63(systemImageInfo)、:62,723(playImageInfo)、:659(adbVersionPath)、:761-762(emulatorAccel+emulatorVersion)、:848,886(invalidateEnvCache)。src/core/installer.js:95-99(playImageInfo+installPlayImage,首次遇到 ARM 应用按需下);:159,169,190,489(playImageInfo判定)。src/main.js::314-354(autoDeploy主流程)、:707(paths().root给 UI)、:824(sources.reset)、:898,932,939,946,953,964,977(自检/诊断)、:1076-1269(各provision:*IPC)、:1330,1542(avdHome/root)、:1631(预热前checkEnv)。test/engine-test.js:146-220,391-401、test/auto-test.js:1347-1350、test/boot-test.js:44。
测试覆盖
test/engine-test.js
- ✓
:149默认运行时目录位于数据目录下 - ✓
:156空环境检查:adb 未就绪,组件结构完整 - ✓
:166内置 ZIP 解压可用 - ✓
:197SDK 索引里的相对 url 会被补全成绝对地址(absUrl/baseOf) - ✓
:211解析出的 emulator / 系统镜像地址都是可下载的绝对 URL - ✓
:244镜像校验:区分有效 ISO9660 / 损坏 / 未下完(inspectIso) - ✓
:391playImageInfo校验 API 34 兼容镜像完整性
test/auto-test.js
- ✓
:1339系统镜像落点:全新安装必须落在运行时目录(覆盖paths().sysImgRoot三分支)
test/boot-test.js:44 起真实 checkEnv + 真机启动(npm run test:boot,不联网也能跑但要 ISO)。
未覆盖:installRuntimePack、resolveRuntimePack、materializeImages、installAdb/installEmulator/installPlayImage/installAehd/installQemu、guardDisk 全都没有单测(都需要真实网络/大文件)。
4. src/core/updater.js — 在线更新(check / prepare / apply)
职责
从本仓库 GitHub/Gitee Releases 取最新版本,按安装形态挑资产、下载并组装载荷,生成一段 PowerShell 覆盖脚本在进程退出后执行「替换 + 重启」。
对外接口(导出 {Updater, cmpVer, OWNER, REPO})
| 成员 | 签名 | 说明 |
|---|---|---|
constructor |
({currentVersion, exePath, isPackaged, dataDir, settings?, onProgress?}) |
38-50;this.installDir = dirname(exePath),this.sources = new Sources(settings) |
get flavor |
'setup' | 'portable' |
53-59:installDir 下有 Uninstall *.exe → setup |
get updateDir |
<dataDir>/update |
61-63 |
check |
({force=false}) => Promise<Latest> |
73-115,见下 |
prepare |
(info?) => Promise<{mode:'zip'|'setup', payload, version}> |
121-176 |
_downloadParts |
(asset, target, conns, total) |
182-227,分片下载 + 顺序拼接 |
_extract |
(zipPath, dest) |
229-251,带 zip-slip 防护、逐条流式 |
apply |
(job, {waitPid?, spawn?}) => true | script |
258-325;spawn:false 时只返回脚本(测试用) |
static repoUrl() |
() => 'https://github.com/RoutineMiku/apkstart/releases' |
328-330 |
cmpVer |
re-export 自 version.js |
333 |
check() 返回(82-112):
{ version, tag, name, notes, htmlUrl, publishedAt,
asset: { name, size, url, urls[], sizes{}, source, parts?, partial? } | null,
assets, sources, unreachable,
flavor, hasUpdate, current, canAutoApply }
asset 挑选(77-80):
setup:/Setup\.exe$/i→ 兜底/win.*\.exe$/iportable:/portable.*\.zip$/i→/win64.*\.zip$/i→/\.zip$/ihasUpdate = cmpVer(merged.tag, current) > 0(109);canAutoApply = !!asset && (asset.url || asset.parts?.length)(111)。
关键实现
1) check()(73-115) 只做「元数据 + 挑资产」,下载地址在 prepare() 里才测速。force 透传给 sources.latest。
2) prepare()(121-176)
- 载荷目录
<dataDir>/update/<version>/; - 有
asset.parts→_downloadParts(133-134); - 否则
candidates(asset)→rank()→downloadMulti(ranked, file, {connections})(136-163); - 进度总大小的取法:
sizes[url]按ranked顺序找第一个已知的(142-147),注释说明拿错会「一直显示 92% 再突然跳到完成」; .zip→ 解到payload/→{mode:'zip',payload:out};其余 →{mode:'setup',payload:file}(166-175)。
3) _downloadParts()(182-227):每个分片单独 candidates + rank(可以一部分走 Gitee、一部分走镜像),downloadAnyParallel 到 <name>.<index>.tmp,校验 part.size(若已知,211-216),fs.writeSync(fd, buf, 0, len, doneBytes) 顺序落盘,最后校验 doneBytes === total(224-226)。整片 readFileSync 进内存(213)——分片 ≤100MiB,可接受。
4) apply()(258-325)—— 更新链最关键的一段
生成的脚本(lines,265-307)依次:
$ErrorActionPreference='SilentlyContinue',Note()写<updateDir>/update.log;Wait-Process -Id <waitPid> -Timeout 90+Sleep 700ms(270-272);mode==='zip':Copy-Item -Recurse -Force最多 12 轮,每轮用「目标 exe 是否存在」当探针,失败Sleep 600ms(275-290);之后Remove-Item $src(解压目录,289);mode==='setup':Start-Process -ArgumentList '/S' -Wait并记录 exit code(291-298);- 重新拉起
exe(300-301); Remove-Item <updateDir>/<version> -Recurse -Force,最后exit 0(304-306,注释:清理失败不应让调用方以为更新失败)。
启动方式(309-324):
- 脚本先落盘
update/apply.log.ps1便于排障(310); - 真正执行用
-EncodedCommand(UTF-16LE base64,313),注释说明绕开 PS 5.1 按 ANSI/GBK 解码无 BOM 脚本导致中文路径乱码; - 不能
detached(315-318):某些安全软件/沙箱会拦「分离的控制台进程」,表现为脚本压根没跑(界面上「正在替换程序并重启」卡住);改用普通子进程 +child.unref(); spawn(ps, ['-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass','-WindowStyle','Hidden','-EncodedCommand',b64], {stdio:'ignore', windowsHide:true})。
坑点与不变量
- 安装版 vs 便携版靠「安装目录里有没有
Uninstall *.exe」判定(53-59),没有其它标记;NSIS 静默覆盖安装,便携版靠复制覆盖。 - 覆盖不会删除旧版本多出来的文件(287-288 注释),只清本次解压目录;所以「删掉的 dll 残留」可能影响新版本(目前判断为无害)。
apply()之后调用方必须退出:main.js:594-596apply(job)后 900msapp.quit();脚本最多等 90s。- Gitee 100MiB →
.part1/.part2(130-134 注释);sources.latest已把分片合逻辑资产,check()必须把parts一路带出来(88-101),auto-test:926 专门守这个。 sizes逐地址记录,不能用asset.size一处了事(142-147、sources:339-347)。- 潜在误判:默认兜底
/\.zip$/i会把运行时整包当更新包(80)。同一个 release 里既有ApkStart-vX-win64-portable.zip也有ApkStart-runtime-vX.zip(.github/workflows/release.yml:44,187),当前靠portable正则先命中才没出问题;一旦便携包改名,/\.zip$/i会挑到 1.5GB 的运行时整包并覆盖程序目录。 prepare不校验下载结果的 zip 完整性,_extract才暴露错误;下载大小与total不符时downloadMulti会抛(download:546)。- 更新只在打包后检查:
main.js:1665 if (app.isPackaged);开发态不查。 - 不变量:
apply()必须在prepare()成功之后调用(prepare无载荷时抛错,main.js:592捕获后sendProgress({stage:'error'}))。 flavor每次readdirSync(installDir),无缓存(53-59)——高频调用会有磁盘 IO,目前只在 check/UI 用。
被谁调用
src/main.js:38(require)、:1503-1511(构造,注入settings/onProgress)、:579-604(runUpdate:check→prepare→apply→quit)、:496,584,588(托盘/手动检查 +repoUrl())、:1447(app:updateCheck,force默认为真)、:1456(app:updateOpen)、:1461(app:updateApply)、:1667(启动 8s 静默检查)。src/preload.js:71-72(updateCheck/updateApply);src/ui/app.js设置页「软件更新」。
测试覆盖(test/auto-test.js)
- ✓
:820版本比较按数字逐段比(cmpVer) - ✓
:828安装形态决定挑哪个资产 +flavor判定 - ✓
:926分片资产必须一路传到updater.asset(否则prepare报「没有可用的下载地址」) - ✓
:1033分片更新包按顺序拼回整包,大小不符立刻中止(_downloadParts) - 间接覆盖:
:843/:864/:878/:901/:949/:976(sources)、:995/:1068/:1108/:1155/:1198/:1251(downloadMulti) - 未覆盖:
apply()生成的脚本内容(无断言抓apply.log.ps1)、_extract的 zip-slip、prepare的sizes选择。
5. src/core/store.js — 设置与应用清单持久化
职责
一个「读时合并默认值 + 原子写」的 JSON 存储:%APPDATA%\apkstart\{settings.json,apps.json,icons/,apks/}。
对外接口(module.exports = store)
| 成员 | 签名 | 说明 |
|---|---|---|
DATA_DIR / ICON_DIR / APK_DIR |
string |
10-14;DATA_DIR = %APPDATA%\apkstart |
getSettings() |
() => Settings |
175-186:deepMerge(DEFAULT_SETTINGS, 磁盘内容) + 强制迁移 |
saveSettings(patch) |
(patch) => Settings |
188-196:deepMerge(当前, patch),engine.resourceMode 存在时翻译成三开关 |
getApps() |
() => App[] |
198-201,坏文件回落 [] |
saveApps(apps) |
(apps) => void |
203-205 |
upsertApp(app) |
(app) => app |
207-214,按 package 合并 |
removeApp(pkg) / getApp(pkg) |
216-223 | |
iconPath(pkg) / apkPath(pkg,version='cur') |
=> string |
225-231 |
ensureDirs() |
() => void |
119-123 |
DEFAULT_SETTINGS |
常量对象 | 16-117,被测试与 doctor 直接引用 |
关键实现
- 原子写(133-138):写
<file>.tmp→renameSync,避免半截 JSON。 deepMerge(140-150):只递归普通对象,数组和标量直接覆盖;base[k]必须是对象才递归。- 读时迁移(175-186)——三处强制覆盖,没有版本号字段:
s.engine.headless = false(179):旧版无头运行 ≠ 打不开窗口;s.hideAfterLaunch = false(181):旧版退出壳层会杀掉整个运行时;s.freeform = false(184):旧版 freeform 小窗会变成「窗口里套小窗」。 因为每次读都覆盖,旧 settings.json 里的true永久失效(auto-test:455 断言)。
- 资源策略翻译(160-170、191-193):
save→liteMode:true/priorityMode:balanced/renderSize:540x960;smooth→false/performance/720x1280;balanced→true/balanced/auto。只在patch.engine.resourceMode出现时触发,避免与细项开关打架。 - 默认值里的「事实约束」(写在注释里,读的时候别删):
engine.headless:false(28-30):无头模式 SurfaceFlinger 不出 VSYNC,应用活着但没画面;engine.badGpu:''(32-34):记录「拉起就崩」的<emulator版本>|<gpu>,升级运行时自动失效;runtime.dir:''(68)=%APPDATA%\apkstart\runtime;runtime.downloadConnections:8(88);runtime.sourcePreference:'auto'(91)、autoMirror:true(94)、giteeToken:''(97);runtime.compatImage:false(78)——已基本废弃:provision.checkEnv:381-384不再依赖它,把 play 镜像同时当主镜像;engine.logLimitKB:2048(55)、engine.prefetch无、engine.prewarm:true(65);display.portrait:'900x1600'(112),但main.js:276用的是d.portrait || '540x960'(默认值不一致,实际以 settings 里存在的 900x1600 为准)。
DEFAULT_SETTINGS缺runtime.avdDir:provision.paths():207读runtime.avdDir,新装用户这里是undefined;UI 写入后才有(ui/app.js:1203)。同理runtime.installed被engine.js:870读,但默认值里没有。
坑点与不变量
getSettings()每次调用都readFileSync + JSON.parse,没有内存缓存(175-186)。而provision.paths()每次调用要读 2~4 次 settings(193、207、209 等),checkEnv()在多处被状态轮询调用 → 高频小文件读。要做性能优化这里是第一个下手点。saveSettings写的是「合并后的完整对象」(189-194),所以 settings.json 会带上当时的所有默认值;升级后新增的默认值不会被写入,只在读时合并——这正是迁移可以放在读时的原因。- 迁移是单向强制(179-184),未来若要允许用户重新打开 headless,必须改这里而不是改 UI。
writeJson的renameSync在跨卷时会失败(os.tmpdir与DATA_DIR同卷时没事;测试里改APPDATA后仍在同卷)。- 测试隔离方式:改
process.env.APPDATA再重新 require(auto-test.js:11,1344-1347);DATA_DIR是模块加载时求值的常量,同进程内改 env 不会生效——写测试时注意。
被谁调用
src/core/provision.js:12,145,192,197-237,452,1159,1187,1193,1217。src/core/engine.js:15,1017-1021(store.DATA_DIR)、src/core/emulator.js:16、src/core/installer.js:10、src/core/sharer.js:10、src/core/layers.js:162(summary内延迟 require)。src/main.js:全流程(启动迁移、app:info、settings:get/set、bootstrabBundledRuntime:97-171直接saveSettings({runtime:{dir}}))。test/engine-test.js:147、test/auto-test.js:456,700,1346,1374,1386、test/boot-test.js:21。
测试覆盖
- ✓
auto-test.js:455旧配置强制迁移:无头与「启动后退出」不再生效 - ✓
auto-test.js:1373资源策略一处切换,自动翻译成 vCPU/优先级/分辨率 - ✓
auto-test.js:1385数据分区容量可配置,默认不再是死数字 - ✓
engine-test.js:149默认运行时目录位于数据目录下(依赖DATA_DIR) - 未覆盖:
upsertApp/removeApp/apkPath/iconPath、writeJson原子性。
6. src/core/layers.js — 容器分层盘点 / 回收
职责
把运行时目录当成镜像层来做只读盘点与按明确清单回收(默认 dryRun),并给设置页一个「一共占了多少盘」的摘要。
对外接口(导出 {analyze, prune, summary, walk, dirSize})
| 导出 | 签名 | 说明 |
|---|---|---|
walk |
(dir, out=[], depth=0) => [{path,size}] |
递归文件列表,深度上限 6(15-27) |
dirSize |
(dir) => bytes |
29 |
analyze |
(root, {keepAvd='apkstart.avd', aggressive=false, keepSnapshots=false}) => {total,groups,candidates} |
36-127 |
prune |
(root, {apply=false, keepAvd, aggressive, keepSnapshots, onRemove}) => {…analyze, apply, removed, saved, after} |
133-152 |
summary |
(root) => {total,totalText,runtimeText,groups,reclaimable,reclaimableText,count} |
155-184 |
candidates[] 项:{path, size, reason, kind:'file'|'dir'}。
关键实现
1) analyze() 的 8 类回收项(对应代码顺序)
| # | 行号 | 目标 | reason |
|---|---|---|---|
| 0 | 48-51 | emulator/、system-images/、avd/、platform-tools/ |
只做 size 分组(groups),不删 |
| 1 | 53-61 | emulator/qemu/windows-x86_64/qemu-system-{aarch64,armel,i386}* |
非 x86_64 的 QEMU 目标 |
| 2 | 63-68 | system-images/**/{NOTICE.txt,source.properties} 且 >1MB |
镜像包内大体积说明文件 |
| 3 | 70-77 | system-images/android-30(仅当 API34 play 的 system.img 存在)、<root>/x86_64 |
旧镜像 / 解压错位目录 |
| 4 | 79-86 | avd/*.avd 中 name !== keepAvd |
非活动 AVD(含 8-16GB 用户数据) |
| 5 | 87-90 | avd/**/*.lock |
上次异常退出残留锁文件 |
| 6 | 91-100 | avd/<keepAvd>/snapshots 或 snapshots.stale-N(keepSnapshots=false 时) |
旧 quickboot 快照 |
| 7 | 103-110 | <root>/_tmp、<root>/images |
下载临时文件 / 旧 QEMU·ISO 遗留 |
| 8 | 112-123 | aggressive 时 emulator/crashreport.exe |
构建发行包专用 |
2) prune() 的安全约束(139-141)
const p = path.resolve(c.path), rootAbs = path.resolve(root);
if (p === rootAbs || !p.startsWith(rootAbs + path.sep)) continue; // 不出 root、不删 root
apply=false 时一个文件都不动(142-149),只返回清单;删除失败(被占用)静默跳过,下次再清(148)。
3) summary()(155-184):运行时 analyze + 4 个额外目录(avd、APK_DIR、ICON_DIR、logs),过滤 0 字节组,单位在 1GB 以上转 GB。
坑点与不变量
aggressive的黑名单是硬约束(112-114 注释):Qt6WebEngineCoreAndroidEmu.dll是qemu-system-x86_64.exe的加载时依赖,绝不能删;qsn/netsim保守保留。keepAvd默认写死'apkstart.avd',与emulator.js的AVD_NAME必须一致;改名要同步两处。- 运行时正在跑时必须
keepSnapshots:true:engine.cleanup()传keepSnapshots: this.vmRunning(engine.js:1019-1023),否则删当前会话的快照会把运行中的机器写坏。 walk的深度 6 是为了防符号链接环/深层目录炸栈;超过 6 层的文件不计入 size(会低估)。analyze的candidates不包含「活动 AVD 的 userdata/快照(keepSnapshots=true时)」,这是「已装应用不会被清」的保证(auto-test:174 断言)。prune的after只是total - saved,不重新扫描,真删失败时与实际略有出入。
被谁调用
src/core/engine.js:1017(usage()→summary)、:1019-1023(cleanup()→prune)。src/main.js:1004(runtime:usage→runtime.usage()→summary)、:1056-1071(runtime:cleanup:先apply:false拿清单 →dialog.showMessageBox二次确认 →apply:true)。src/ui/app.js(设置页「占用/清理」面板,经runtime:usage/runtime:cleanup)。test/auto-test.js:25,157,167,171。
测试覆盖
- ✓
auto-test.js:139盘点可回收项:非 x86_64 QEMU、旧镜像、旧 AVD、锁文件、旧快照(含 dryRun 不删除、apply后活动 AVD 与 x86_64 QEMU 保留) - 未覆盖:
summary()的额外 4 个目录、aggressive分支、深度上限。
7. 小工具四件套
7.1 src/core/logfile.js — 按大小滚动日志
| 导出 | 签名 | 说明 |
|---|---|---|
rotate |
(file, limitKB) => bool |
15-26:size < limit 返回 false;否则删旧 .1.log → rename 成 .1.log |
append |
(file, line, limitKB=2048) => bool |
33-45:每进程首次 + 每 200 行做一次 rotate(39),appendFileSync 补换行 |
trimNow |
(file, limitKB=2048) => bool |
48-50:启动时无条件检查一次 |
- 职责:
app.log/emulator.log长期 append 会被写满(header 2-9),只保留一份.1.log。 - 坑点:
limitKB被Math.max(256, ...)夹到 ≥256KB(39、49);counters是模块级Map,进程重启归零;rotate用renameSync,Windows 上文件被占用会失败并返回 false(静默)。 - 被谁调用:
src/main.js:85(appLog,logs/app.log)、src/core/emulator.js:577(emulator 日志)。 - 测试:✓
auto-test.js:1404日志超过上限自动滚动,只保留一份备份。
7.2 src/core/notify.js — 安卓通知 → Windows 通知
| 导出 | 签名 | 说明 |
|---|---|---|
parseRecords |
(dumpsys 文本) => [{pkg,key,title,text}] |
34-63 |
NotifyBridge |
new NotifyBridge({getClient,getAppLabel,getAppIcon,onOpen}) |
start()/stop(),内部 setInterval(_tick, POLL_MS=2500)(11、77-89) |
关键实现:
- 每 2.5s
client.shell('dumpsys notification --noredact', {timeout:12000})(97),先isOnline()(96); - 过滤:
SYSTEM_PKGS白名单 +com.android.providers.*+launcher(18-32);FLAG_ONGOING_EVENT(0x2)、FLAG_FOREGROUND_SERVICE(0x40)跳过(43-45); - 首次
_tick只做基线primed,避免启动瞬间把历史通知全弹一遍(99-104);seen超 500 条裁到 300(113); - 点击
note.on('click')→onOpen(pkg)(130); - 模块顶层
require('electron')(9)→ 纯 Node 测试跑不了,所以test/notify-test.js用 electron 跑。
被谁调用:src/main.js:36,682-697(startNotifier(),只在容器有应用窗口时由 onContainerActive(true) 启动,:670-678 关闭时 stop();:1772 退出时 stop)。
测试:test/notify-test.js(用真实 test/notif.txt dump 调 parseRecords,不在 npm test 里);NotifyBridge 本体无覆盖。
7.3 src/core/android.js — 安卓设置开关(不需要进桌面)
| 导出 | 说明 |
|---|---|
ACTIONS |
11 个 android.settings.* action 常量(7-19) |
AndroidSettings |
new AndroidSettings(runtime);方法 status()、setWifi、setAirplane、setVolume、setAnimations、setFontScale、setDensity、tune({pkg})、open(action)、permissions(pkg)、grantAll(pkg) |
关键实现:
client()每次await runtime.ensure()(24-28),失败抛「运行时未就绪」;_sh(commands)把多条命令用;拼成一次adb shell(30-34),20s 超时;status()用echo "k=$(...)"一次拿 7 个值再正则解析(37-61);tune():关三个动画 +max_cached_processes=32+ 可选deviceidle whitelist +pkg(111-121);permissions()解析dumpsys package的runtime permissions:段,按缩进收尾(131-145);grantAll()逐个pm grant,失败忽略(147-156);- 取值范围:
fontScale 0.85~1.3、density 120~640、volume 0~100(79-108)。
被谁调用:src/main.js:1501(androidSet = new AndroidSettings(runtime))、:1404-1434(android:status/set/open/tune/permissions/grantAll IPC);src/preload.js 暴露给设置页。
测试:✗ 无覆盖(需要真实 adb)。
7.4 src/core/display.js — 显示适配的纯计算
| 导出 | 签名 | 说明 |
|---|---|---|
densityFor |
(w,h,manual) => dpi |
manual>0 时夹 120min(w,h)/2.57 夹 200 |
portraitSize |
(str) => {w,h} |
解析 900x1600,非法/横屏回 {900,1600}(12-18) |
defaultBounds |
(area) => {x,y,w,h} |
高度 area.h*0.84,宽 9:16,居中(20-28) |
fullscreenBounds |
(portrait, area) => {x,y,w,h} |
铺满高度、按竖屏比例算宽、水平居中(36-46) |
sizeFor |
(mode, portrait, area) => {w,h} |
两种模式都返回竖屏预设(55-57) |
关键不变量(写在注释里):模拟器窗口的宽高比在开机时被 LCD 锁死,直接 SW_MAXIMIZE 只会得到贴左边、宽度不变的窗口;所以「全屏」= 最大化窗口而不改 Android 分辨率(48-54),切换模式不需要重启运行时。
被谁调用:src/main.js:32(require)、:274-277(portraitSize() 读 display.portrait)——只有 portraitSize 在运行时代码里被用;densityFor/defaultBounds/fullscreenBounds/sizeFor 目前只被测试调用(appwin.js:46 有自己的一份 AppWindow.sizeFor)。
测试:✓ auto-test.js:465 显示适配:窗口/全屏共用竖屏分辨率,窗口比例 9:16 可拉伸(覆盖 4 个函数)。
8. 下载 / 部署 / 更新总链路
8.1 文字流程图
【用户点「一键完成」】
src/ui/app.js:371 deployAll()
├─ setStepBusy('all',true) → 按钮文案「准备中…」(app.js:334)
├─ api.autoDeploy() → preload.js:45 invoke('runtime:autoDeploy')
└─ IPC runtime:autoDeploy → main.js:870
└─ autoDeploy() → main.js:314 (有 deploying 互斥锁,main.js:313/315)
【autoDeploy 主流程 main.js:314-354】
1. env = provisioner.checkEnv() main.js:319
2. needEngine = !env.emulator.ok || !env.sysimg.ok main.js:320
3. if needEngine && settings.runtime.preferGithubRuntime:
installRuntimePack(progress) provision.js:522
├─ resolveRuntimePack() provision.js:476
│ ├─ runtimePackUrl 自定义?直接用 :477
│ ├─ 并发 GET GitHub / Gitee releases?per_page=15 :487
│ └─ 找 assets /^ApkStart-runtime-.*\.zip$/,cmpVer 取最高 :497-515
├─ guardDisk('runtime', root) [512+1024=1536MB] :525 → :262
├─ sources.rank(sources.candidates(url)) 串行测速 :534-536 → sources.js:399
├─ downloadMulti(urls, _tmp/runtime-pack.zip) :541 → download.js:338
│ ├─ 并发 Range 探测 → 只混用「总大小一致」的源 download.js:355-381
│ ├─ 分块 8 线程轮转分配 + .chunks.json 边车 download.js:391-416
│ └─ 空闲看门狗 20s / 低速 45s&<120KB/s 换源 download.js:449-503
├─ 体积闸门 <200MB → 抛「整包下载不完整」 :556
├─ extractZip(zip, root) >64MB 用 ZipFile 流式 :559 → :591
├─ 写 <root>/.runtime-pack.json,删 zip :566-571
└─ materializeImages() .img.xz/.gz → .img :573-576 → :722
afterPack = checkEnv() main.js:328
if emulator.ok && sysimg.ok → return {ok:true,source:'github'}
else → 继续走官方源补齐(main.js:330)
4. 官方源逐组件兜底(仅当上一步失败/不完整):
installAdb() provision.js:428 → downloadAny platform-tools.zip
installEmulator() provision.js:905 → downloadAnyParallel + extractZip + ensurePlatformTools
installSystemImage() provision.js:966 → installPlayImage(:1004) → downloadAnyParallel + extractZip
5. after = checkEnv();ok = adb.ok && emulator.ok && sysimg.ok main.js:347-348
6. finally deploying=false main.js:351-353
【UI 接着开机 app.js:381-387】
api.runtimeStart() → main.js:880 → runtime.ensure() engine.js:787 起
├─ provisioner.materializeImages(onLog).catch(()=>{}) engine.js:848
├─ checkEnv() engine.js:849
├─ killOrphanEmulators() engine.js:856
└─ boot() 失败则 doctor 诊断 + 变体重试(GPU/accel/内存逐级降)
【启动后的两条后台链】
A. 自动部署(延迟 20s)main.js:1657-1661 → autoDeploy() ← 与 UI 同一个函数
B. 更新检查(打包后延迟 8s)main.js:1665-1676
updater.check() updater.js:73
└─ sources.latest({force}) sources.js:277
├─ fetchReleases() 并发 GitHub/Gitee :237
├─ 403/429 → 熔断 15min :286-290
├─ 全部失败 → 上一次结果 + stale :292-298
└─ 同版本资产合并(urls[] + sizes{})、parts 保留 :304-348
info.hasUpdate → notify + send('update:state')
【用户点「立即更新」】
main.js:579 runUpdate() (updateBusy 互斥)
├─ updater.prepare(info) updater.js:121
│ ├─ parts? _downloadParts() 每片单独测速+下载+顺序拼 :182
│ └─ 否则 candidates→rank→downloadMulti :140-163
│ └─ .zip → _extract 到 update/<ver>/payload :166-173
├─ updater.apply(job) updater.js:258
│ ├─ 生成 PS 脚本(Wait-Process 90s → 复制/静默安装 → 重启 → 清理 → exit 0)
│ ├─ 落盘 update/apply.log.ps1(排障) :310
│ └─ spawn powershell -EncodedCommand(**非 detached**)+ unref :319-323
└─ setTimeout(900ms) → quitting=true; app.quit() main.js:596
└─ 脚本等进程退出 → 覆盖安装目录 → Start-Process exe → 删 update/<ver>
关键时序数字(都是一次性常量,接手时不要随便调小):
autoDeploy延迟 20s(main.js:1661,注释:冷启动磁盘/CPU 已打满);- 更新检查延迟 8s 且仅
app.isPackaged(main.js:1665-1675); apply里Wait-Process -Timeout 90、复制 12 轮 ×600ms、重启后 400ms 清理(updater.js:271-306);apply返回后 900ms 退出应用(main.js:596);downloadMulti:块空闲 20s、低速阈值 45s + 120KB/s、每块重试 6 次、换源上限 2 次;download(单流):空闲 30s、非 2xx 重试 2 次 ×1.5s。
8.2 这条链上最容易出问题的环节
| # | 现象(用户视角) | 代码位置 | 机理 / 备注 |
|---|---|---|---|
| 1 | 「卡在准备运行时」,进度条长时间停在 1~3% | provision.js:531(固定 percent:1)+ sources.js:412-417(串行测速,每地址 ≤9s)+ sources.js:52(256KB/次) |
4 个候选(直连+2 镜像+Gitee)就是 30s+ 的「没有任何字节进度」。网络越差候选越多,越像卡死 |
| 2 | 进度 停在 99% 很久,随后又跳回「改用官方源补齐」 | provision.js:575-576(materializeImages(...).catch(()=>0))+ :790(单镜像失败只 onLog) |
.xz 展开失败被两层 catch 吞掉 → checkEnv().sysimg.ok=false → autoDeploy 走 main.js:330 再下一套 1.4GB;下次启动还会重试展开 |
| 3 | @napi-rs/lzma 相关的乱错 |
provision.js:771-781(require.resolve('@napi-rs/lzma') 再按文件路径 require index.js) |
打包时若 lzma 二进制没被带上/被 asar 压住 → Cannot find module;注释解释了为什么不能直接 require('@napi-rs/lzma')(ESM polyfill) |
| 4 | 「设了运行时目录,还是下到 AppData」 | provision.js:217-224(sysImgRoot 三分支)、:726(materializeImages 目标)、:237(avdHome)、store.js:67-98(runtime.dir 默认空)、main.js:97-171(bootstrapBundledRuntime 会覆盖 runtime.dir) |
① 老用户 <DATA_DIR>/system-images 已存在 → 分支 2 继续用它,不会搬;② 便携版 exe 旁带 runtime/ 时,bootstrapBundledRuntime 在 main.js:165-168 直接 saveSettings({runtime:{dir: bundled}}),用户手设的目录被覆盖(只有 sameTree && emulator.exe 存在 才尊重旧设置,:144-148);③ AVD 另有 avdDir 设置,可能与运行时目录不同盘 |
| 5 | 磁盘明明够却报「空间不足」,或反过来解压到一半失败 | provision.js:262-277(need 表 264-265 无 'runtime')、main.js:940(自检阈值 8192MB) |
guardDisk('runtime') 只估 1536MB,整包 + 展开实际要 ~5GB;guard 通过后仍可能撑爆 |
| 6 | 进度 卡在 95% 不动(历史 issue) | 已有对策:download.js:446-451,492-503(低速换源)、:466-480(保证 settle);单流路径仍只有 idleMs=30s(:112) |
慢源拖尾块;边车(.chunks.json)保证重试只补缺块,不会整包重下 |
| 7 | 「连接被中断 / 停滞」后整个下载作废 | download.js:155(close 且 !complete → reject)、:526-528(块耗尽重试 → 抛 + 存边车) |
设计上可续传;但 downloadParallel 见半截文件就降级单流(:188-191),多线程退化为单线程 |
| 8 | 更新卡在「正在替换程序并重启」 | updater.js:315-323(不能 detached 的兼容性注释)、:271(Wait-Process 90s)、:280-285(复制 12 轮) |
安全软件拦「分离进程」→ 脚本没跑;或卸载/安装被 UAC 挡住;update/update.log 是唯一现场 |
| 9 | 更新完程序目录里多了 1.5GB 的奇怪文件 | updater.js:80(便携版兜底 /\.zip$/i) |
若某版本只有 ApkStart-runtime-vX.zip 而没有 portable 资产,会被当成更新包解压进安装目录 |
| 10 | Gitee 上「有一个版本没有安装包」 | .github/workflows/release.yml:36-44,78-100(100MiB 闸门 + GITEE_TOKEN 缺失直接失败);消费端 sources.js:172-204、updater.js:182-227 |
编译期问题,但现象出现在这里;分片必须 part1..N 连续,否则整组被丢弃(sources.js:196-203) |
| 11 | 换源/改镜像前缀后仍走老地址 | main.js:819-825 只 sources.reset();provision.js:479,514,642,664,984 的 _cache.* 无失效入口 |
需要重启进程才彻底生效 |
| 12 | 状态轮询把 CPU/进程拉满 | provision.js:687-714(emulatorVersion 失败不缓存)、:298-315(adb 30s 缓存)、:845-902(accel 30s + 落盘 6h/10min) |
未安装 emulator 时每次 checkEnv 都 execFile 探测多路径 |
| 13 | AVD 判定「已被占用」而起不来 | layers.js:87-90(锁文件清单)、main.js:963-969(自检发现 .lock)、engine.js:856(killOrphanEmulators) |
上次异常退出残留 *.lock,清理面板能回收 |
| 14 | 首启把「已装应用/数据」丢掉 | store.js:179-184(三处强制迁移)、engine.js:848(materializeImages)、doctor.snapshotKey/imageIdentity(快照指纹,auto-test.js:88,98) |
迁移是单向的;快照指纹不含数据分区大小(auto-test:1395),扩容不会清数据 |
8.3 给接手者的三条「先看这里」
- 只看一个函数就能解释八成的部署问题:
Provisioner.checkEnv()(provision.js:367)。它同时决定了 UI 的「差什么」、autoDeploy的分支、engine.ensure()走 emulator 还是 qemu、以及诊断报告的内容。 - 路径规则只有一处:
Provisioner.paths()(provision.js:197)。任何新代码要落运行时文件,必须从这里拿路径,不要自己拼DATA_DIR。 - 下载策略都收敛在
Sources+downloadMulti:新增源只要进candidates();新增「限速/选优」逻辑只需要改rank()与downloadMulti的混源条件,不要在provision.js里另写一套。