三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Android虚拟设备Cuttlefish：从系统开发到深度测试的完整指南

发布时间：2026/8/8 3:16:15 三亩地 编程学习日记
Android虚拟设备Cuttlefish：从系统开发到深度测试的完整指南

1. 为什么我们需要一个“虚拟”的Android设备？

如果你是一名Android开发者，或者对Android系统本身感兴趣，那么“真机调试”和“模拟器”这两个词你一定不陌生。真机调试，意味着你需要一台物理的Android手机，通过USB线连接到电脑，安装应用、运行、调试。这听起来很直接，但实际操作中，你可能会遇到驱动问题、设备型号碎片化、系统版本不一致、甚至手机没电、被电话打断等种种麻烦。而传统的Android模拟器，比如Android Studio自带的AVD（Android Virtual Device），虽然解决了物理设备的依赖问题，但它本质上是一个运行在x86架构上的、高度抽象的“仿真器”。它模拟的是Android应用运行的环境，而非一个完整的、可以深度定制的Android系统。

这就引出了我们今天要讨论的核心：Cuttlefish。它不是一个传统的应用模拟器，而是一个Android虚拟设备（Android Virtual Device），更准确地说，它是一个运行在虚拟化环境（如KVM）上的完整Android系统镜像。你可以把它理解为一台“软件定义的手机”，从内核、系统服务到应用框架，都是真实的Android代码在运行。这意味着，你可以用它来做一些AVD做不到的事情：比如，测试系统级的功能（如新的内核模块、硬件抽象层HAL实现）、验证OTA升级流程、调试系统服务（System Server）的崩溃，甚至构建和运行一个你自己修改过的AOSP（Android Open Source Project）版本。

最近在开发者社区里，关于Android测试和开发的讨论热度不减。从“android studio loading devices”的卡顿抱怨，到“android profiler, 如何用火焰图分析app对cpu占用”的性能调优需求，再到“教我兄弟学android逆向”这类底层探索，都反映出开发者对更强大、更可控的Android运行环境的需求。Cuttlefish正是为了满足这类深度需求而生的官方解决方案。它绕过了传统模拟器的诸多限制，让你能在自己的工作站上，获得一个近乎裸机性能、且完全受你控制的Android设备。

2. Cuttlefish 与 AVD：核心差异与选型指南

在决定投入时间搭建Cuttlefish之前，我们必须先厘清它和Android Studio AVD的根本区别。这决定了你该在什么场景下使用它。

AVD (Android Virtual Device): 应用开发者的瑞士军刀AVD的设计目标是应用兼容性测试和快速迭代开发。它通过一个名为“QEMU”的处理器模拟器，在x86主机上模拟ARM指令集（也可以通过Intel HAXM或AMD Hyper-V进行硬件加速，运行x86系统镜像）。它的优势非常明显：

  • 开箱即用：Android Studio内集成，图形化界面点几下就能创建。
  • 资源占用相对可控：可以方便地调整内存、存储和CPU核心数。
  • 针对应用测试优化：提供了丰富的传感器模拟（位置、旋转、电池）、网络状态模拟、截图录屏等工具，非常适合前端应用功能的验证。

但是，AVD的“虚拟”是有限度的。它运行的是一个预编译好的、针对模拟环境优化过的系统镜像。你很难，甚至不可能将你自己编译的、包含自定义内核或系统服务的AOSP镜像直接刷进去。当你的工作触及系统底层时，AVD就显得力不从心了。

Cuttlefish：系统开发者和深度测试者的利器Cuttlefish则走了另一条路。它利用主机的硬件虚拟化支持（KVM），直接创建一个虚拟机（VM），然后将一个标准的、可用于真机的Android系统镜像（通常是aosp_cf_x86_64_phone-userdebug这类target）作为虚拟机的“磁盘”来启动。这意味着：

  • 运行真实的Android系统：你在虚拟机上看到的，和你刷入真机的是同一套系统。所有系统进程、服务都是真实的。
  • 支持自定义系统镜像：你可以编译任意的AOSP分支或定制版本，然后直接用它来启动Cuttlefish，进行端到端的系统验证。
  • 更真实的硬件交互模拟：Cuttlefish通过虚拟化设备（VirtIO）来模拟GPU、网络、音频等，其行为更接近真实硬件，适合测试驱动、HAL等。
  • 支持丰富的调试接口：你可以通过adb、fastboot甚至直接进入内核控制台与设备交互，进行系统级调试。

简单来说，AVD是“模拟Android环境来跑App”，而Cuttlefish是“在虚拟硬件上跑完整的Android系统”。如果你的工作是开发一个普通的App，那么AVD足够了。但如果你在做：

  • AOSP系统开发与定制
  • 系统级API或服务的测试
  • 内核或驱动开发
  • Android兼容性测试套件（CTS）的本地运行
  • 自动化测试框架（如Trade Federation）的集成测试
  • 研究Android系统架构

那么，Cuttlefish是你的不二之选。

3. 搭建 Cuttlefish 运行环境：从零开始的详细步骤

搭建Cuttlefish环境比安装AVD要复杂一些，因为它需要宿主机的深度配合。以下步骤基于Ubuntu 22.04 LTS，其他Linux发行版原理类似，但包管理命令可能不同。

3.1 前置条件检查：虚拟化与依赖库

首先，确保你的CPU支持硬件虚拟化（Intel VT-x或AMD-V），并且在BIOS中已启用。在终端运行：

grep -Eoc '(vmx|svm)' /proc/cpuinfo

如果输出大于0，则表示支持。

接下来，安装必要的依赖包。这些包提供了编译工具、库文件以及Cuttlefish运行所需的基础设施。

sudo apt update sudo apt install -y git-core gnupg flex bison build-essential zip curl zlib1g-dev \ libc6-dev-i386 libncurses5 lib32ncurses5-dev x11proto-core-dev libx11-dev \ lib32z1-dev libgl1-mesa-dev libxml2-utils xsltproc unzip fontconfig \ python3 android-sdk-platform-tools-common \ qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager \ cpu-checker

安装完成后，将当前用户加入kvm和libvirt用户组，以便无需sudo权限即可访问虚拟化资源。

sudo usermod -aG kvm $USER sudo usermod -aG libvirt $USER

重要提示：修改用户组后，你需要完全注销并重新登录，或者开启一个新的登录会话（例如通过su - $USER），才能使组权限生效。这是很多新手容易忽略，导致后续cvd start命令报权限错误的关键一步。

3.2 获取 Android 源码与 Cuttlefish 主机包

Cuttlefish的运行分为两部分：主机工具（Host Package）和设备镜像（Device Image）。主机工具负责创建和管理虚拟机，设备镜像就是我们要运行的Android系统。

方法一：从AOSP源码构建（推荐给系统开发者）如果你需要运行自己修改过的AOSP，这是唯一的方法。

  1. 按照官方指南（source.android.com/docs/setup/download）下载和初始化AOSP源码仓库（Repo工具）。
  2. 同步代码后，进入源码根目录，执行以下命令来构建主机工具和x86_64的手机镜像：
    source build/envsetup.sh lunch aosp_cf_x86_64_phone-userdebug # 选择Cuttlefish手机目标 m -j$(nproc) # 编译整个系统，这需要很长时间和大量磁盘空间
    编译成功后，主机工具位于out/host/linux-x86/bin/，镜像文件位于out/target/product/vsoc_x86_64/。

方法二：下载预编译包（快速上手）对于大多数测试和评估目的，Google提供了预编译的Cuttlefish包。

  1. 访问 https://ci.android.com ，这是Android的持续集成构建网站。
  2. 在左侧选择分支（如aosp-main），在右侧的Target列找到并点击aosp_cf_x86_64_phone-userdebug（或其他Cuttlefish目标）。
  3. 在构建成功的页面，找到并下载cvd-host_package.tar.gz（主机工具包）和aosp_cf_x86_64_phone-img-xxxxxx.zip（设备镜像）。注意两者的构建号最好一致。

3.3 安装主机包与启动你的第一个虚拟设备

假设你通过方法二下载了预编译包。

  1. 解压主机包并安装：
    tar -xzf cvd-host_package.tar.gz cd cvd-host_package sudo ./bin/unpack_bootloader_images.sh $HOME
    这个脚本会将必要的引导镜像解压到你的家目录下。
  2. 解压设备镜像：
    unzip aosp_cf_x86_64_phone-img-xxxxxx.zip -d $HOME
  3. 设置环境变量： Cuttlefish的主机工具需要知道镜像文件在哪里。编辑你的shell配置文件（如~/.bashrc），添加：
    export ANDROID_HOST_OUT=$HOME/cvd-host_package export ANDROID_PRODUCT_OUT=$HOME # 假设你把镜像解压到了家目录
    然后执行source ~/.bashrc使其生效。
  4. 启动Cuttlefish： 这是最激动人心的时刻。在终端运行：
    cd $ANDROID_HOST_OUT ./bin/launch_cvd --daemon
    --daemon参数表示在后台运行。第一次启动会花费一两分钟，因为它需要创建虚拟磁盘等资源。

如果一切顺利，你将会看到类似VIRTUAL_DEVICE_DISPLAY_0=localhost:6444的输出。这个端口（通常是6444）就是Cuttlefish显示器的VNC端口。

3.4 连接与交互：ADB、VNC与控制台

设备启动后，你有多种方式与它交互：

  • 通过ADB：Cuttlefish会自动在本地启动ADB服务。运行adb devices，你应该能看到一个名为localhost:6520的设备。之后你就可以像操作真机一样安装APK、运行命令了。
    adb -s localhost:6520 shell
  • 通过VNC查看界面：你可以使用任何VNC客户端（如vinagre、Remmina）连接到localhost:6444，查看和操作Android的图形界面。密码默认为空。
  • 通过控制台：Cuttlefish提供了一个强大的控制台工具cvd。
    ./bin/cvd status # 查看设备状态 ./bin/cvd stop # 停止设备 ./bin/cvd start # 启动设备 ./bin/cvd restart # 重启设备

4. 高级配置与实战调优：让 Cuttlefish 更趁手

基础运行只是开始。要让Cuttlefish真正成为你的生产力工具，还需要进行一些配置和优化。

4.1 资源配置：分配多少CPU和内存才合适？

默认配置可能不适合你的机器。你可以在启动时通过参数指定资源。编辑一个启动脚本start_cf.sh：

#!/bin/bash cd $ANDROID_HOST_OUT ./bin/launch_cvd \ --daemon \ --cpus=4 \ # 分配4个CPU核心 --memory_mb=8192 \ # 分配8GB内存 --x_res=720 \ # 屏幕水平分辨率 --y_res=1280 \ # 屏幕垂直分辨率 --dpi=320 \ # 屏幕密度 --gpu_mode=guest \ # GPU模式：'guest' (使用主机GPU加速), 'swiftshader' (软件渲染) --blank_data_image_mb=8192 # 数据分区大小

--gpu_mode=guest可以显著提升图形性能，但要求主机有合适的GPU驱动。如果遇到图形问题，可以回退到--gpu_mode=swiftshader。

4.2 网络配置：让虚拟设备访问互联网

默认情况下，Cuttlefish使用一个隔离的NAT网络，设备可以访问外网，但外部网络无法直接访问设备。对于需要设备对外提供服务的测试（如Web服务器），你需要配置端口转发或桥接网络。

一种简单的方法是使用ADB反向代理：

adb -s localhost:6520 reverse tcp:8080 tcp:8080

这样，主机上访问localhost:8080的流量就会被转发到Cuttlefish设备的8080端口。

对于更复杂的网络需求，可以研究Cuttlefish的--tap_name参数，将设备的网络接口桥接到主机的物理网络。

4.3 磁盘与数据持久化

Cuttlefish的虚拟磁盘在设备停止后默认会被删除。如果你想保留数据（如下次启动时应用还在），需要使用--data_policy参数。

./bin/launch_cvd --daemon --data_policy=always_create

always_create会每次都创建新的空数据分区。如果你想复用上次的数据，需要先停止设备，然后使用--data_policy=use_existing启动。更高级的用法是创建自定义的overlay镜像，这允许你在一个基础镜像上叠加可写的修改层。

4.4 集成到开发工作流：与 Android Studio 和 CI/CD 配合

虽然Cuttlefish没有像AVD那样的Android Studio原生插件，但你仍然可以将它集成到开发流程中。

  • 在Android Studio中使用：确保Cuttlefish在运行且ADB已连接（localhost:6520）。在Android Studio的运行配置中，直接选择这个ADB设备作为部署目标即可。你可以像调试真机App一样进行断点调试、性能剖析（使用Android Profiler连接该设备）。
  • 在CI/CD流水线中：这是Cuttlefish的一大优势。你可以在无头（headless）模式下启动它（不启动图形界面），用于自动化测试。例如，在GitLab CI或Jenkins的脚本中：
    # 启动设备（无图形） ./bin/launch_cvd --daemon --start_webrtc=false # 等待设备就绪 adb wait-for-device # 安装并运行测试 adb install app-debug-androidTest.apk adb shell am instrument -w com.example.test/androidx.test.runner.AndroidJUnitRunner # 收集测试结果 adb pull /sdcard/test_results.xml . # 停止设备 ./bin/stop_cvd
    这样可以实现完全自动化的、在完整系统环境下的集成测试。

5. 常见问题排查与性能优化心得

在实际使用中，你肯定会遇到各种问题。这里分享一些我踩过的坑和解决方案。

5.1 启动失败：权限问题与内核模块

问题：运行launch_cvd时提示Failed to create VM或Permission denied。

  • 检查用户组：确认你已重新登录，并且groups命令输出中包含kvm和libvirt。
  • 检查KVM模块：运行lsmod | grep kvm，应该看到kvm_intel或kvm_amd。如果没有，使用sudo modprobe kvm_intel加载。
  • 检查/dev/kvm权限：运行ls -l /dev/kvm，所有者应为root:kvm。如果不是，可以尝试sudo chown root:kvm /dev/kvm。

问题：启动时卡在Booting Linux on physical CPU 0x0或类似信息。 这通常是镜像不匹配或损坏导致的。请确保你使用的主机包和设备镜像来自同一次构建。重新下载匹配的构建包是最稳妥的解决办法。

5.2 ADB 无法连接：端口冲突与多实例

问题：adb devices列表为空。

  • 检查Cuttlefish ADB端口：Cuttlefish默认使用6520端口。运行netstat -tlnp | grep 6520查看端口是否被监听。如果被其他进程占用，可以在启动时指定其他端口：--base_instance_num=2（端口会变为6522，6446等）。
  • 启动多台Cuttlefish：Cuttlefish支持同时运行多个实例，每个实例拥有独立的ADB和VNC端口。启动第二个实例：./bin/launch_cvd --daemon --base_instance_num=2。这样你会得到两个设备：localhost:6520和localhost:6522。

5.3 图形界面卡顿或黑屏：GPU 渲染模式选择

问题：VNC连接后界面非常卡顿，或者只显示黑屏。

  • 首选方案：尝试在启动时添加--gpu_mode=guest。这需要主机安装合适的GPU驱动（对于Intel/NVIDIA/AMD显卡）。这能提供近乎原生的图形性能。
  • 备用方案：如果guest模式有问题（比如在云服务器上），使用--gpu_mode=swiftshader。这是CPU软件渲染，兼容性最好，但性能较差，适合无头模式或简单测试。
  • 检查VNC客户端：有些VNC客户端对编码支持不好。可以尝试换一个，如tigervnc-viewer。

5.4 存储空间不足：管理虚拟磁盘

Cuttlefish运行一段时间后，可能会在$HOME目录下生成大量的磁盘镜像文件（*.img），占用几十GB空间。

  • 定期清理：使用./bin/stop_cvd --all停止所有实例，然后可以安全删除$HOME下除了你主动保留的镜像之外的所有*.img和*.qcow2文件。下次启动时会自动重建。
  • 指定数据目录：通过--data_dir参数将虚拟磁盘文件生成到其他有更大空间的分区。

5.5 性能优化实战心得

  1. 使用SSD：虚拟磁盘的I/O性能至关重要。将Cuttlefish运行在SSD硬盘上，启动速度和应用加载速度会有质的提升。
  2. 分配足够内存：Android系统本身就需要不少内存。如果只分配2GB或4GB，系统会频繁使用Swap，导致整体卡顿。对于现代Android版本（11+），建议至少分配6-8GB内存。
  3. 关闭不需要的服务：如果你在无头模式下跑自动化测试，可以考虑编译一个更精简的AOSP版本（比如移除一些预装应用和后台服务），或者启动后通过ADB关闭动画、定位等非必要服务来节省资源。
  4. 利用主机多核：多分配几个CPU核心给Cuttlefish（--cpus=4或更多），能显著提升多任务和编译测试时的响应速度。

从“android studio loading devices”的漫长等待，到拥有一个瞬间启动、任意配置的完整Android系统；从担心真机系统版本碎片化，到在同一个Cuttlefish实例上快速切换不同的AOSP构建进行测试——这种掌控感的提升，对于从事系统层或深度兼容性测试的开发者来说，是革命性的。它把Android从一个需要实体硬件的“黑盒”，变成了一个可以在代码层面完全掌控、随意拆解和组装的软件对象。虽然初始搭建有一定门槛，但一旦跑通，它将成为你探索Android世界最得力的沙盒。

编程学习 学习日记 实战经验
← 返回列表