Meta 实现 Android 虚拟设备框架 Cuttlefish 原生运行于 Apple Silicon Mac

Meta 旗下的 Reality Labs 致力于开发各类产品，比如AI 眼镜。借助模拟器，我们不必依赖紧缺的实体硬件，也能扩大开发和测试的规模。

为非手机类 Android 设备测试软件时，虚拟设备能否高度还原实体产品的软件行为至关重要。Goldfish 这类轻量级模拟器虽然能解决一部分问题，但与真机之间的差异很容易掩盖缺陷，导致它们直到开发后期才暴露出来。保真度不足还会降低团队对设备模拟的信任度，进而加剧对稀缺真机硬件的依赖。

Cuttlefish 是 Android 开源项目（AOSP）推出的虚拟设备框架，专门用于在虚拟硬件上测试 Android 软件。它引导与真机相同的系统镜像，并在虚拟硬件上运行高度还原的软件栈，因此相比轻量级模拟器，Cuttlefish 能更精准地贴合物理设备的真实行为。

遗憾的是，Cuttlefish 仅支持 Linux，而我们的应用和代码库开发者日常使用的是搭载 Apple 芯片的 Mac 设备。这迫使我们不得不同时维护 Goldfish 和 Cuttlefish 两套方案。

我们意识到，如果能统一到基于 Cuttlefish 的单一平台上，所有开发者就都能用上同样高保真的虚拟设备。难点在于移植整个技术栈，让 Cuttlefish 能够在 macOS 上原生运行。

碎片化带来的影响

同时维护两套模拟器平台带来了沉重的运维负担：不仅消耗算力资源，给开发者带来困扰，还拖慢了模拟器团队的研发节奏。每套工具都要兼顾两个独立平台，基础设施和工程人力也被分散开来。此外，开发者还必须根据自己的工作方式在模拟器目标之间做妥协：Goldfish 跨平台通用但保真度较差，而 Cuttlefish 保真度高却只能运行在 Linux 上。

AOSP 官方也同样存在这一割裂：Goldfish 面向应用开发者，而 Cuttlefish 服务于 Android 平台开发者。只要保留这种分立格局，我们就不得不承受碎片化带来的代价。

技术栈与 macOS 的适配差距

Cuttlefish 充当编排层，而真正运行客体操作系统（guest OS）的组件是虚拟机监控器（VMM）。在 Linux 上，Cuttlefish 通常使用 crosvm，不过此前也曾将 QEMU 作为备选 VMM 提供过支持。但这段集成代码随着时间推移逐渐荒废。为了在 macOS 上实现对 Apple 芯片的原生支持，我们重新启用了对 QEMU 的支持。

Cuttlefish 的许多虚拟设备都使用 vhost-user 后端，即通过套接字向 QEMU 提供 virtio 设备的独立进程。这种架构十分清晰，但其大部分实现都硬编码了针对 Linux 的强假设。其中有三项假设在 macOS 上直接失效：首先，vhost-user 机制仅限制在 Linux 环境，无法在 macOS 上构建或运行；其次，Apple 的 Hypervisor 施加了 QEMU 未曾预料的资源限制；最后，原生的显示、构建及签名链路根本不存在。我们逐一攻克了这三个难题。

让 vhost-user 摆脱 Linux 限制，支持跨平台

在架构层面，最关键的改动集中在 QEMU 的 vhost-user 路径上。前端、libvhost-user 以及诸如 vhost-user-blk 之类的 contrib 后端此前均仅限 Linux。我们放宽了这些构建限制，让 vhost-user 前端和库既能在 Linux 上构建，也能在 macOS 上构建。这样一来，Cuttlefish 的设备后端在 Mac 上就能像在 Linux 上一样移交给 QEMU。没有这项改动，让 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 权限（JIT entitlement）。在 Cuttlefish 方面，我们加入了 macOS 宿主机支持，让框架的编排逻辑能够直接在 Mac 上构建并运行，而不再默认依赖 Linux 宿主机。

带来的收益

通过转向统一平台，我们降低了维护成本，精简了基础设施需求，淘汰了冗余工具链，提升了保真度，并确保开发者本地运行的 Cuttlefish 虚拟设备与 CI 中使用的完全一致。

统一的平台也让基于共享技术栈支持各项功能变得更加轻松，其中包括：

• 蓝牙配对与连接。
• Wi-Fi。
• 蜂窝网络。
• 3D 图形。
• 无线（OTA）更新测试：在虚拟设备上测试 OTA 更新流程。
• Fastboot。
• 快照功能：在 CI 和开发流程中保存并恢复设备状态。

除了支持 Reality Labs 的内部工程师外，这套完全相同的虚拟设备也开放给了面向我们生态开发的外界开发者。这种统一确保了第三方团队的测试环境，与我们开发及验证系统本身所用的 Cuttlefish 平台完全一致。

随着 AI 智能体在 Android 开发中扮演日益重要的角色，验证执行和运行时行为变得与代码生成同等关键。虚拟设备让工程师与自动化智能体能够在隔离环境中并行操作，从而加速应用运行与快速迭代。借助即时重置状态和反复运行测试的能力，团队无需再依赖共享的物理硬件，避免了工作流被打断。归根结底，高保真模拟确保了这些持续反馈闭环既迅速又切实有效。

回馈社区

尽管我们打造这一方案的初衷是为了 Reality Labs 的内部开发，但 macOS 支持的价值远不止于我们自家的产品。我们正将这项成果分享给社区，方便其他开发者基于成就了我们工作的 QEMU 和 AOSP 底层能力进一步构建。

我们通过两部分公开发布这些成果：

• qemu-wearables：由 Meta 维护的 QEMU 分支，包含我们提交的代码。
• cuttlefish-wearables：一套补丁文件，附带为 Android/AOSP 打补丁的说明指南。

这些仓库包含我们对 QEMU 的改动和 Cuttlefish 系列补丁，以及构建与应用补丁的操作说明。

我们同时也在探索将这些改动贡献给 QEMU 和 AOSP 上游的途径。在此期间，开发者可以直接使用我们的分支与补丁集。

致谢

该项目依托于 QEMU 与 Cuttlefish/AOSP 社区打下的基础。我们尤其感谢 Stefano Garzarella 打造的 vsock-user 实现，这直接促成了我们在 macOS 上的集成。

同时特别鸣谢 Meta 的 Olya Arkhangelskaia 和 Tom Care，感谢他们在将 Cuttlefish 引入 macOS 过程中所做的奠基性工作；也感谢 Jeffrey Effendy 在改善原生 Mac 开发者体验及后续产品化落地中所做的贡献。

文章 Mac 上的 Cuttlefish：在 Apple Silicon 原生运行 Android 虚拟设备框架 最初发表于 Engineering at Meta。