Cuttlefish 登陆 Mac:在 Apple Silicon 上原生运行 Android 虚拟设备框架
Meta 的 Reality Labs 负责打造 AI 眼镜等产品。模拟器让我们无需依赖稀缺的实体硬件,就能扩展开发和测试规模。
为非手机类 Android 设备测试软件时,关键在于虚拟设备能在多大程度上还原实体设备的软件行为。Goldfish 这类轻量级模拟器虽然能部分解决问题,但它与真实设备的差异可能把 bug 掩盖到开发后期才暴露。这种保真度的不足还会削弱大家对设备模拟的信任,进一步加重对稀缺实体硬件的依赖。
Cuttlefish 是 Android 开源项目(AOSP)推出的虚拟设备框架,用于在虚拟硬件上测试 Android 软件。它启动与真实硬件相同的系统镜像,在虚拟硬件上运行完整的软件栈,因此比轻量级模拟器更接近实体设备的行为。
遗憾的是,Cuttlefish 只支持 Linux,而我们的应用和库开发者用的都是 Apple silicon 的 Mac。这迫使我们同时维护 Goldfish 和 Cuttlefish 两套方案。
我们知道,如果能统一到基于 Cuttlefish 的单一平台上,就能让所有开发者都享受到同样高保真的虚拟设备。挑战在于移植整个技术栈,让 Cuttlefish 能在 macOS 上原生运行。
碎片化的影响
同时维护两套模拟器平台带来了沉重的运维负担:消耗计算资源、给开发者造成困惑、拖慢模拟器团队的进度。每个工具都得支持两个独立的平台,基础设施和工程人力也被一分为二。此外,开发者还得根据自己的工作方式来选择模拟器:Goldfish 到处能跑但保真度较低,Cuttlefish 保真度高却离不开 Linux。

AOSP 也存在同样的割裂:Goldfish 面向应用开发者,Cuttlefish 则服务于 Android 平台开发者。只要这种分工还在,我们就不得不承受碎片化带来的种种问题。
技术栈与 macOS 的缺口
Cuttlefish 负责编排调度,而真正运行客户机操作系统的是一个虚拟机监视器(VMM)。在 Linux 上,Cuttlefish 通常使用 crosvm,此前也支持过 QEMU 作为替代的 VMM。不过随着时间推移,QEMU 的集成早已停止维护。为了在 macOS 上实现 Apple 芯片的原生支持,我们重新启用了 QEMU。
Cuttlefish 的许多虚拟设备都使用 vhost-user 后端,也就是一些独立进程,通过 socket 向 QEMU 提供 virtio 设备。这套架构本身很干净,但很多代码都写死了对 Linux 的假设。其中有三个假设在 macOS 上会出问题:vhost-user 相关代码只在 Linux 下编译和运行;Apple 的 hypervisor 对资源施加了 QEMU 没预料到的限制;此外,原生的显示、构建和签名路径也都不存在。这三点我们都逐一解决了。

让 vhost-user 超越 Linux 实现可移植
结构上最重要的改动集中在 QEMU 的 vhost-user 路径上。前端、libvhost-user 以及 vhost-user-blk 等 contrib 后端原本都只限 Linux 使用。我们放宽了这些构建限制,让 vhost-user 前端和相关库在 macOS 和 Linux 上都能编译。这样 Cuttlefish 的设备后端在 Mac 上向 QEMU 交接的方式就与 Linux 完全一致。没有这项改动,Cuttlefish 赖以立足的高保真设备模型就无法在 Linux 之外使用。
适应 Hypervisor.framework 的约束
在 Apple 芯片上,QEMU 通过 HVF(Hypervisor.framework)而非 KVM 来加速。QEMU 的 HVF 后端原本追踪的内存区域数量不足,无法支持较大规模的 Cuttlefish 配置。我们增加了它的追踪槽位数量,让这些配置能够正常运行。
可用的原生显示
本地应用开发需要一个可交互的显示屏,让开发者能够直接查看并操作虚拟设备。为了实现直接交互、摆脱对 WebRTC 接口的依赖,我们改用了 QEMU 的原生 Cocoa 显示。相关改动包括:
- BGRA 像素格式支持:实现准确的画面渲染,消除 Apple 芯片上的视觉伪影。
- 鼠标点击模拟触摸:将指针操作转换为触摸输入,以操作触屏设备。
- 自定义几何参数:为 graphic_console_init 添加 -g 标志用于显示配置。
我们还启用了尚不稳定的 Rutabaga 结构体,以匹配 gfxstream/rutabaga 配置中 Rust 侧的图形 ABI。
在 Apple 芯片上的构建与签名
最后是构建和打包工作:初步支持 Darwin 构建、在 macOS 上构建 arm64 版 QEMU,以及修复工具链问题。macOS 构建除了支持代码签名和公证外,还需要 JIT entitlement。在 Cuttlefish 一侧,我们增加了对 macOS 宿主机的支持,让这套框架的编排逻辑能够在 Mac 上构建和运行,而不是默认假设宿主机是 Linux。
收益
迁移到统一平台后,我们降低了维护成本、减少了基础设施需求、去掉了冗余工具、提升了保真度,并确保开发者在本地运行的就是 CI 中所用的同一套 Cuttlefish 虚拟设备。

单一平台也让在共享技术栈上支持各种能力变得更简单,包括:
- 蓝牙配对与连接。
- Wi-Fi。
- 蜂窝网络。
- 3D 图形。
- OTA 更新测试:针对虚拟设备测试空中下载(OTA)更新流程。
- Fastboot。
- 快照:在 CI 和开发流程中保存和恢复设备状态。
除了支持 Reality Labs 的工程师,这套相同的虚拟设备也开放给为我们生态开发的外部开发者使用。这样一来,第三方团队测试时所用的,正是我们在 OS 开发与验证中使用的同一套基于 Cuttlefish 的平台。
随着 AI agent 在 Android 开发中扮演越来越重要的角色,验证执行和运行时行为与代码生成同等重要。虚拟设备让工程师和自动化 agent 能够在隔离环境中并行工作,方便运行应用、快速迭代。借助即时状态重置和反复测试,团队摆脱了对共享实体硬件的依赖,也避免了工作流被打断。归根结底,高保真的模拟保证了这些持续反馈循环既快速又有价值。
回馈社区
虽然我们是为 Reality Labs 内部的开发而构建,但 macOS 支持的价值远不止于我们的产品。我们把这些工作分享给社区,希望其他开发者能在我们赖以实现的 QEMU 和 AOSP 基础之上继续构建。
我们分两部分发布这些成果:
- qemu-wearables:Meta 维护的 QEMU fork,包含我们的提交。
- cuttlefish-wearables:一组补丁文件,附有对 Android/AOSP 打补丁的说明。
这些仓库包含我们对 QEMU 的改动以及 Cuttlefish 补丁系列,并附有构建和打补丁的说明。
我们也在探索将这些改动贡献回 QEMU 和 AOSP 上游。在此之前,开发者可以使用我们的 fork 和补丁集。
致谢
本项目离不开 QEMU 和 Cuttlefish/AOSP 社区打下的基础。尤其要感谢 Stefano Garzarella 开发的 vsock-user 实现,它直接促成了我们的 macOS 集成。
同时特别感谢 Meta 的 Olya Arkhangelskaia 和 Tom Care 在将 Cuttlefish 移植到 macOS 方面的奠基性工作,以及 Jeffrey Effendy 对原生 Mac 开发体验的改进和后续的产品化工作。