apkstart README

项目的 README,来自 github.com/RoutineMiku/apkstart。合并为一个 markdown 文件:README.md。

ApkStart

ApkStart Logo

CI Release License: MIT Platform

Windows 上的安卓应用运行器 —— 让安卓应用像 Windows 原生软件一样被安装和使用。 注:本项目为早期版本,作者自娱自乐产物,所有修改都是作者下班和休息日在处理,开源免费,不插广告,暂时也不是很好用,没有找过营销号推广,无妄之灾。

主界面

┌────────────────────────────────────────────────────────────┐
│  桌面图标(真实应用图标 .lnk)                              │
│      │  双击                                               │
│      ▼                                                     │
│  ApkStart.exe --launch <包名>                              │
│      │  运行时未启动?→ 自动拉起(Android Emulator + API34)│
│      ▼                                                     │
│  按系统解析出的 LAUNCHER 入口启动(不是 APK 里的主 Activity)│
│      │  存活观察 18 秒,闪退自动重试 / 重置数据 / 补权限     │
│      ▼                                                     │
│  模拟器窗口 = 应用窗口(改标题、换图标、竖屏比例、全屏居中) │
└────────────────────────────────────────────────────────────┘

下载即用(不想编译)

两个源内容一致,国内建议用 Gitee:

安装包(三种形态,内容与版本号完全一致):

形态 文件名 何时选它
商店版 ApkStart_<四段版本>_x64.msix 从 Microsoft Store 装。内置完整运行时,装完不联网;自更新交给商店
完整便携版 ApkStart-v*-win64-full.zip(约 830 MB,解压 ~1.3 GB) 不想装、也不想等下载:解压即用,运行时(模拟器 + 系统镜像)全在包里
安装版 ApkStart-v*-Setup.exe(约 1.3 GB) 想要桌面/开始菜单快捷方式、卸载项
轻量便携版 ApkStart-v*-win64-portable.zip(96 MiB,解压 ~227 MB) 只想先试试,首次启动再联网下载运行时

所有形态的 ApkStart.exe 都写入了品牌图标 + 版本资源(FileDescription = ApkStart 安卓应用运行器, CompanyName = RoutineMiku,版本与 package.json 同步),不再是 Electron 的默认图标和 33.x 版本号。 自己从源码打包时:npm run pack(轻量)/ npm run pack:full(完整)/ npm run build:msix(商店包)。

画面铺满是怎么做到的

模拟器的物理面板方向(hw.lcd.width/height)就是画面的真实形状。面板方向和应用自己声明的 screenOrientation 不一致时,Android 只会给应用一个信箱式的中间窄条 —— 两侧补黑,换窗口大小、 改 wm size、改 letterbox 样式都填不满(这套组合逐项试过,见 src/core/apk.js 的注释)。

所以 ApkStart 在安装 APK 时离线解析 AndroidManifest.xml,统计出这个应用天然是横屏还是竖屏 (启动 Activity 加权;全 sensor / fullSensor 的会在首次运行后再问安卓要一次实际值),存进 apps.json,启动时按它选面板:

只有「面板方向和应用方向不一致」的那一次才重启运行时(约 40 秒,标题栏会给出提示), 之后同方向的应用都是秒进。标题栏的旋转按钮会把这个应用的方向记住(其它应用不受影响), 设置 → 应用窗口 → 屏幕方向可以改成「强制横屏 / 强制竖屏」。

排版由「逻辑密度」决定:720 宽按 190dpi 算等于 606dp,正好越过 Android 的 600dp 平板断点, 红果短剧的双列剧集页、设置页分栏都只在这个密度下出现(镜像默认 320dpi 只有 360dp,是手机排版)。 这就是设置里的「平板排版」开关,默认打开;关掉会回到手机排版。

在线更新(自动选较快的源)

设置 → 软件更新 → 「检查更新」,或托盘右键 → 「检查更新」。发现新版本后点「立即更新」即可。

更新链路不是死连 GitHub,而是每次现测现选:

  1. 同时问 GitHub 与 Gitee 的最新版本,取版本号更高的那个(一个源超时/被墙不影响另一个);
  2. 把「源站直连 / Gitee 同名资产 / 镜像前缀」列成候选,每个地址真下 256KB 测速, 只算「收到首字节之后」的吞吐(握手时间不计入,否则高延迟大带宽的源会被误判成慢);
  3. 按实测速度排序,用最快的那条分块并行下载;失败自动换下一条。

设置里的「下载与更新源」可以强制只用某一边(企业网络只放行一个域名时用), 也可以关掉公共加速镜像、或改用自建镜像前缀。Gitee 附件单文件上限 100MB, 便携包换用 7-Zip 的 deflate(-mx=9)压缩后是 95.0MB,所以 Gitee 上也是 一个能直接双击解压的整包(以前要切成 .part1/.part2 手工拼接,那版已经废弃)。 两个源的同名包体积并不完全一样,客户端按测速结果只挑一个源下完,不会混拼。

两个仓库都是公开的,Gitee 的发行版列表匿名就能读,不需要填任何 token。 (只有在 Gitee 限流返回 403/429 时,才需要在设置里填一个只读 token 提高额度。)

开箱即有的默认行为(不用去设置里找):

从源码构建

# 1. 安装依赖(含 Electron 运行时)
npm install

# 2. 启动并完成运行时部署(一次性下载 adb / Android Emulator / 系统镜像)
npm start

# 3.(可选)注册 .apk 双击安装
npm run assoc:on

# 4. 打包便携版(免安装,可直接分发)
npm run pack
# 产出 dist/ApkStart-win64-portable/ApkStart.exe
# 5. 压成 zip 发布(必须用这个脚本,别用 Compress-Archive:体积会大 5MB、塞不进 Gitee)
node build/zip.js dist/ApkStart-win64-portable ApkStart-win64-portable.zip

单文件 EXE(内置完整运行时,装完不再联网)

如果希望「一个 EXE 发出去,对方双击就能跑,不用等下载」,用这条:

# 先把 engine/ 整理成可分发运行时(system.img 用 xz/LZMA2 极限压缩,3.1GB → 约 1.1GB;
# 同时裁掉 emulator 里用不到的部分:arm64 的 QEMU、Vulkan 后端、多语言包、qsn/自检工具、VR 资源)
npm run runtime

# 再打成安装版 EXE(electron-builder nsis 目标,装到当前用户目录)
npm run build:exe
# 产出 dist/release/ApkStart-<版本>-Setup.exe

体积构成(实测):Electron 约 180MB、emulator 瘦身后约 480MB、系统镜像 xz 压缩后约 1.1GB, 最终安装包约 1.32GB(相比 gzip 方案省约 490MB)。能再压的硬下限就在 system.img 那条 (它就是安卓系统本身,且是 verity 保护的镜像,无法从外部裁掉 GMS 组件)。 网络默认走主机 NAT,不创建虚拟网卡,所以也不依赖任何额外驱动。

首次启动会把 xz 镜像展开到 %APPDATA%\apkstart\system-images(约 20 秒,只做一次), 之后每次直接复用。AVD 与已装应用固定存放在 %APPDATA%\apkstart\avd, 即使便携版每次解压到临时目录也不会丢。

运行时说明:完全独立,不依赖任何第三方模拟器

ApkStart 是一个自持的项目,运行时组件全部由自己下载、校验和管理(位于 %APPDATA%\apkstart\runtime)。 轻量版默认从本项目的 GitHub Release 下载整包(ApkStart-runtime-*.zip),拿不到才退回下表里的官方源:

组件 来源 大小 用途
adb(platform-tools) dl.google.com 官方源 ~8 MB 安装/启动安卓应用
Android Emulator dl.google.com 官方源(8 线程并行下载) ~440 MB 运行时引擎(自带设备模型与 GPU 转译)
Android 14 通用系统镜像(Google Play x86_64) dl.google.com 官方源 源镜像 ~3.1 GB(xz 后 ~1.1 GB) 唯一的基础层:x86 应用、仅含 ARM 库的应用、GMS 都能跑,镜像即系统,无需安装
AEHD 驱动(可选) dl.google.com 官方源 ~0.2 MB 硬件加速(或用 Windows「虚拟机平台」WHPX)

首次使用时,「运行时」页会引导完成以上部署(一键部署):

  1. adb 与运行时引擎、系统镜像自动下载(官方源实测 10+ MB/s);
  2. 部署完成后自动开机,之后双击桌面图标自动拉起,全程无感。

运行时部署向导

设备兼容性(自动处理,无需干预)

容器式低成本运行

目录结构

apkstart/
├─ src/
│  ├─ main.js              主进程:窗口/托盘/单实例/命令行分发/IPC
│  ├─ preload.js           安全桥接
│  ├─ ui/                  渲染层(原生 HTML/CSS/JS,无框架)
│  └─ core/
│     ├─ zip.js            极简 ZIP 读取器(按需解压)
│     ├─ axml.js           Android 二进制 XML 解析
│     ├─ arsc.js           resources.arsc 资源表解析(应用名/图标路径还原)
│     ├─ apk.js            APK 元信息:包名/版本/启动 Activity/图标/ABI
│     ├─ png.js            零依赖 PNG 编码器 + 程序图标绘制
│     ├─ shortcut.js       多尺寸 ICO 生成 + .lnk 快捷方式
│     ├─ assoc.js          .apk 文件关联(HKCU,免管理员)
│     ├─ adb.js            adb 客户端(安装/启动/同步/截图/…)
│     ├─ engine.js         运行时管理:探测/模拟器托管/空闲回收
│     ├─ sharer.js         本机 ↔ 安卓共享目录双向同步
│     ├─ installer.js      安装流水线编排
│     └─ store.js          应用清单与设置持久化
├─ engine/                 运行时组件下载缓存(emulator / system-images / platform-tools)
├─ tools/platform-tools/   便携 adb 放置处
├─ test/                   单元测试 + Electron 集成测试 + 冒烟截图
├─ build/pack.js           便携版打包
└─ scripts/assoc.js        .apk 关联命令行开关

命令行

ApkStart.exe                      打开主界面
ApkStart.exe <路径\to.apk>        安装 APK
ApkStart.exe --launch <包名>      直接启动应用(桌面快捷方式使用此参数)

测试

npm test                                   # 纯 Node 单元测试 + 引擎链路测试(不需要网络)
npm run test:boot                          # 真实引导测试:用 61MB Alpine guest 验证 QEMU 参数/建盘/优雅关机
npm run selftest                           # 运行时自检:装好 Android 后一键验证 安装→启动→截图→共享目录
electron test/electron-integration.js      # ICO / 快捷方式集成测试
electron . --smoke test\shot.png           # 启动应用并截图(界面冒烟)

npm run selftest 是装好系统后的「验收命令」——它会对当前设备依次检查 adb 连接、 Android 版本、freeform 支持、共享目录双向同步,加 --apk 某应用.apk 还会完整走一遍 安装 → 独立窗口启动 → 前台确认 → 截图。

设计取舍(诚实说明)

兼容模式下运行红果免费短剧(Android 14 · AEHD 硬件加速)
红果短剧在 ApkStart 兼容模式运行

提示「未启用硬件加速」怎么办

安卓模拟器在 Windows 上只有两条加速路:

方式 是什么 谁需要管理员 装完要重启吗
WHPX Windows 自带功能「Windows 虚拟机监控程序平台」 开这个功能时 要
AEHD Google 自家内核驱动 装驱动时 不用

注意别只开「虚拟机平台(VirtualMachinePlatform)」——那是 WSL2 要用的,模拟器要的是 「虚拟机监控程序平台(HypervisorPlatform)」。只开前者,emulator -accel-check 依然会说不可用。

没加速也能跑(纯软件模拟),只是开机会慢到几分钟——这也是应用里那条提示的目的, 不是启动失败。

桌面图标不对 / 显示成 ApkStart 的图标怎么办

每个安卓应用的桌面快捷方式都应该用它自己的图标(安装时从 APK 里解出来存到 %APPDATA%\apkstart\icons\<包名>.ico)。如果显示成了 ApkStart 的绿色播放键,或者干脆是空白图标:

  1. 设置 → 系统集成 → 重建快捷方式(会把桌面和开始菜单的快捷方式按当前应用清单重写一遍, 连同图标和任务栏身份一起修好);
  2. 还不行就删掉那个快捷方式,在 ApkStart 里右键应用 → 重新创建快捷方式/重装一次。

为什么会坏:早期版本整理图标时把这些 .lnk 图标的 IconLocation 统一指向了 ApkStart 的品牌图; 另外把便携版整个目录挪到别处后,.lnk 里记的绝对路径也会失效。重建一次即可。

顺带说一句:每个应用的快捷方式都带自己的 AppUserModelID, 所以固定到任务栏后,任务栏按钮和固定项用的是同一个应用图标,不会混成 ApkStart。

为什么我的 adb devices 看不到这台安卓设备

ApkStart 的 adb 服务跑在专用端口 5044,和系统里你自己的 adb(5037)完全隔开 —— 这样你的 Android Studio / scrcpy 不会跟它抢设备,它也不会误杀你手动开的模拟器。

要用命令行连它:

$env:ANDROID_ADB_SERVER_PORT = 5044
adb devices              # 会看到 emulator-5554

⚠️ 不要对着 5555 端口手动 adb connect:Play 版系统镜像会弹「允许 USB 调试吗」的系统对话框,而且它会盖在正在运行的安卓应用上,看起来像是程序出了问题。

关于作者

ApkStart 由 RoutineMiku 开发维护。

关于面板:公众号二维码与项目链接

Powered by RoutineMiku

参与贡献

欢迎 Issue / PR。壳层保持零第三方依赖,提交前请跑 npm test;细节见 CONTRIBUTING.md。

许可证

MIT。发行包只含 ApkStart 自身代码与 Electron 运行时,不分发安卓系统镜像、QEMU 二进制或 Google 组件;这些由用户本机首次启动时从官方源按需下载,遵循各自的许可协议。

apkstart (RoutineMiku/apkstart)

正在搜索数据库…

这是什么?ApkStart 可在 Windows 上运行 Android 应用:双击 APK 文件即可完成安装,生成桌面图标,并在独立窗口中打开。它使用内置的、基于 QEMU 的运行时。
需要我自己运行完整的 Android 模拟器吗?不需要。它在后台封装了 Android Emulator 和 QEMU,因此每个应用都在独立窗口中打开,你不会看到模拟器界面。它并非从零开发的虚拟化程序,而是基于 AOSP、QEMU 和 adb 构建。
怎么让它运行起来?从 Releases 下载 ApkStart-v-Setup.exe(约 1.3 GB,已包含运行时)并运行;也可以使用更轻量的便携版 zip(约 100 MB),它会在首次启动时获取运行时。然后双击任意 .apk 文件即可安装。
我需要先安装其他东西吗?不需要 Android 设备、单独的模拟器、管理员权限或驱动程序。安装程序自带运行时并安装到用户文件夹中,外壳本身没有第三方依赖。
所有应用都能真正运行吗?不能保证。对模拟器有深度检测的应用,例如需要真实传感器或基带的应用,可能仍然无法工作。仅支持 ARM 的应用需要在设置中启用 ARM 兼容模式,该模式会切换到 Android 14 镜像。
安装后还需要联网吗?不需要。完整的 Setup EXE 是自包含的,首次启动解压系统镜像后,应用不再下载任何内容。只有便携版 zip 会在首次启动时获取运行时。
想要流畅性能,需要一块好的显卡吗?不是必需的。没有硬件加速时,它会回退到软件模拟,速度较慢。启用 AEHD 或 Windows 虚拟机平台(WHPX)可提供硬件加速。
应用能和 Windows 共享文件吗?可以。Windows 用户配置文件中的共享文件夹会与 Android 内的 /sdcard/ApkStartShared 双向同步,几秒内完成。因此应用保存的文件会显示在你的电脑上。
应用在 Windows 中是怎么显示的?每个已安装的应用都会获得一个桌面图标和开始菜单快捷方式,因此你可以在 Windows 搜索中按名称找到它,任务栏也会按应用对窗口进行分组。
它会创建虚拟网卡吗?不会。Android 的网络流量通过 QEMU 用户模式 NAT 经由你的物理网卡传输,因此不会创建虚拟网卡、虚拟交换机或额外驱动程序。
为什么要自己做,而不直接用模拟器?作者专注于原生应用的使用体验,而不是编写虚拟化程序,而是基于 AOSP、QEMU 和 adb 构建。每个应用都在独立的可调整大小的窗口中打开,显示真实图标,保持手机的宽高比,并记住窗口尺寸。
大小
14.3 MB
星标
7.4K
时长
20天
提交 · 90 天