1. 项目概述为什么我们需要 Cuttlefish如果你是一名 Android 开发者或者对 Android 系统底层感兴趣那么“模拟器”和“虚拟机”这两个词你一定不陌生。从早期的 Android SDK 自带的模拟器AVD到后来性能更强的第三方模拟器它们都是我们开发和测试应用的重要工具。但今天要聊的Cuttlefish和这些“传统”的模拟器有本质的不同。它不是用来让你在电脑上玩手游的也不是一个简单的应用运行沙盒。Cuttlefish 是一个由 Google 官方维护的、可配置的、用于 Android 平台开发的虚拟 Android 设备。简单来说Cuttlefish 能让你在云端服务器或者本地的高性能机器上虚拟出一个几乎与真实硬件无异的 Android 设备。这个“设备”拥有完整的 Android 框架、内核、驱动栈甚至可以通过虚拟化技术模拟出 GPU、TPU 等专用硬件。这意味着什么意味着你可以用它来开发和测试那些对硬件有深度依赖的功能比如相机 HAL硬件抽象层、传感器融合、神经网络加速、甚至是完整的车载信息娱乐系统IVI。这些都是普通 AVD 或第三方模拟器难以企及的领域。我第一次接触 Cuttlefish 是在为一个车载 Android 项目做系统级集成测试时。当时我们需要验证一个自定义的音频路由策略它深度依赖特定的 SoC 音频驱动和 Android Automotive 的音频框架。在物理真机上反复刷机测试效率极低且风险高。而普通的 AVD 根本无法模拟出我们定制的硬件接口。Cuttlefish 的出现解决了这个痛点我们可以在 CI/CD 流水线中自动启动一个包含我们自定义系统镜像的虚拟设备运行完整的自动化测试套件。这不仅仅是“模拟一个手机”而是“虚拟化一块开发板”。2. Cuttlefish 的核心架构与工作原理拆解要理解 Cuttlefish 的强大之处必须深入到它的架构层面。它不是一个单体应用而是一个基于crosvmChrome OS 虚拟机的、模块化的虚拟化解决方案。2.1 与传统 AVD 的本质区别很多人会把 Cuttlefish 和 Android Studio 里的 AVDAndroid Virtual Device搞混。虽然它们目标都是“在非手机硬件上运行 Android”但实现路径和深度天差地别。AVD (QEMU-based) 它基于 QEMU 这个通用的机器模拟器。AVD 模拟的是一个特定的、预设的硬件模型比如 Pixel 6。它主要面向应用开发者目的是提供一个快速启动、易于使用的环境来运行和调试 APK。它的系统镜像通常是通用的“通用系统镜像”GSI剥离了很多硬件特定的驱动和 HAL。你无法轻易地更换内核或者添加一个自己编写的硬件服务。Cuttlefish (crosvm-based) 它使用 crosvm 来提供更强的隔离性和性能。Cuttlefish 的核心思想是虚拟化硬件接口而不是模拟一个完整的、固定的手机模型。它通过 VirtIO 等虚拟化标准将主机的资源CPU、内存、存储、网络以及一些虚拟的“设备”如虚拟 GPU、虚拟 TPU、虚拟摄像头暴露给 Guest Android 系统。最关键的是你可以使用自己编译的、包含任意定制驱动的完整 Android 系统镜像包括boot.img,vendor.img,system.img等来启动它。这使得它成为系统开发者、OEM 厂商和芯片供应商进行平台级开发和集成测试的理想工具。用一个类比来说AVD 像是一个“安卓手机模拟器”游戏你只能使用游戏里提供的固定角色和装备而 Cuttlefish 则是一个“安卓硬件沙盒”你可以自带所有的硬件蓝图和驱动程序在这个沙盒里组装并测试你自己的定制手机。2.2 组件交互与启动流程一个 Cuttlefish 实例的启动涉及多个守护进程的协同工作。理解这个过程对后续的问题排查至关重要。cuttlefish-user与cuttlefish-base 这是两个核心的 Debian 软件包。cuttlefish-base包含了所有运行时需要的工具和库而cuttlefish-user则负责管理用户空间的进程。安装它们后你的主机系统会多出像launch_cvd这样的关键命令。launch_cvd- 启动器 这是你启动虚拟设备的入口命令。它的工作非常复杂读取你指定的镜像文件路径--system_image,--boot_image,--vendor_image等。为虚拟机分配资源CPU核心数、内存大小。启动一系列的“虚拟设备”后端进程每个进程对应一种硬件。例如crosvm 运行 Android 内核和系统的主虚拟机进程。webrtc 提供基于 WebRTC 的音频/视频流这是 Cuttlefish 的“屏幕”你可以通过浏览器来访问设备的 UI。tcp_publisher 管理设备的网络端口转发比如将虚拟设备的 ADB 端口通常 6520映射到主机的某个端口。modem_simulator 模拟蜂窝网络调制解调器。gnss_grpc_proxy 模拟 GPS 信号。运行时交互 设备启动后你可以通过多种方式与它交互Web UI 在浏览器中打开https://localhost:8443你会看到一个设备列表和实时屏幕画面。这是最直观的交互方式。ADB 通过adb connect localhost:6520连接到设备之后就可以像操作真机一样使用所有 ADB 命令。Fastboot 虚拟设备也支持 Fastboot 模式你可以通过fastboot -s vsock-3:5555 flash ...这样的命令来刷写新的镜像。这种模块化设计的好处是灵活且健壮。如果虚拟摄像头服务崩溃了通常不会导致整个 Android 系统宕机你可以单独重启这个服务。3. 从零开始Cuttlefish 环境搭建与配置实战理论讲得再多不如亲手跑起来。下面我将以在 Ubuntu 22.04 LTS 系统上搭建 Cuttlefish 为例展示完整的流程和每一步背后的考量。3.1 系统准备与依赖安装Cuttlefish 对主机系统有一定要求主要是内核版本和虚拟化支持。注意强烈建议在物理机或拥有完整虚拟化支持Intel VT-x/AMD-V的虚拟机上操作。嵌套虚拟化在虚拟机里再开虚拟机虽然可能成功但性能和稳定性会大打折扣且问题排查极其复杂。首先更新系统并安装基础依赖sudo apt update sudo apt upgrade -y sudo apt install -y git curl python3 python3-pip接下来是核心依赖KVM基于内核的虚拟机。Cuttlefish 通过 KVM 来获得接近原生的 CPU 和内存性能。# 安装 KVM 及相关工具 sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager # 将当前用户加入 kvm 和 libvirt 组避免每次都用 sudo sudo adduser $USER kvm sudo adduser $USER libvirt操作完成后务必注销并重新登录让组权限生效。之后验证 KVM 是否可用# 检查 KVM 模块是否加载 lsmod | grep kvm # 你应该看到 kvm_intel 或 kvm_amd 模块 # 检查当前用户是否有访问 /dev/kvm 的权限 ls -l /dev/kvm # 输出应为 crw-rw---- 1 root kvm ...且你的用户在 kvm 组内。3.2 安装 Cuttlefish 主机包Google 为 Debian/Ubuntu 系列提供了官方的软件包仓库。我们通过添加这个仓库来安装。# 下载并添加 Google 的 Linux 软件包签名密钥 curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/google-cloud.gpg # 添加 Cuttlefish 软件包仓库 echo deb https://packages.cloud.google.com/apt cuttlefish-main main | sudo tee /etc/apt/sources.list.d/cuttlefish.list sudo apt update # 安装 Cuttlefish sudo apt install -y cuttlefish-user安装过程会自动拉取cuttlefish-base作为依赖。安装完成后关键的命令行工具如launch_cvd、stop_cvd、adb的特殊版本等就已经就绪了。3.3 获取 Android 系统镜像这是最关键也最容易出错的一步。你不能直接用从 Pixel 手机提取的 OTA 包也不能用 Android Studio 下载的通用镜像。你需要专门为 Cuttlefish 构建或下载的镜像。方案一推荐用于最新特性测试从 CI 构建服务器下载Google 的 Android 团队会为每个提交到 AOSP 主分支的变更构建 Cuttlefish 镜像。这是获取最新、最稳定镜像的官方途径。访问 Android CI 网站 。在左侧选择aosp-main分支找到最新的成功构建通常是最上面绿色的那个。点击进入构建详情页在 “Target” 列找到名为aosp_cf_x86_64_phone-userdebug或aosp_cf_x86_64_tv-userdebug根据你需要测试的设备类型的目标。点击该目标下载aosp_cf_x86_64_phone-img-xxxxxx.zip这样的镜像包。解压到某个目录例如~/android_images/。方案二用于自定义开发从 AOSP 源码自行构建如果你需要测试自己修改的 AOSP 代码这是唯一的方法。source build/envsetup.sh lunch aosp_cf_x86_64_phone-userdebug # 选择 Cuttlefish 手机目标 m -j$(nproc) # 开始构建耗时很长构建成功后镜像文件位于$ANDROID_PRODUCT_OUT目录下包含boot.img,system.img,vendor.img,super.img等。3.4 启动你的第一个虚拟设备假设你已经把下载的镜像解压到了~/android_images目录。启动命令非常简单cd ~/android_images launch_cvd第一次运行launch_cvd时它会做很多初始化工作生成实例独有的数据分区镜像、创建证书用于 Web UI 的 HTTPS 连接、分配资源等。这个过程可能需要一两分钟。当你在终端看到大量日志输出最后稳定下来并且出现类似VIRTUAL_DEVICE_DISPLAY_POWER_MODE_CHANGED这样的日志时基本就启动成功了。此时打开你的浏览器访问https://localhost:8443。由于使用的是自签名证书浏览器会提示不安全需要手动点击“高级”-“继续前往”之类的选项。之后你应该能看到一个虚拟 Android 设备的启动动画并最终进入系统界面。在另一个终端你可以用 ADB 连接它adb connect localhost:6520 adb devices # 你应该看到 localhost:6520 device adb shell # 现在你就在虚拟设备的 Shell 里了4. 高级配置与定制化技巧基础启动只是开始。Cuttlefish 的强大在于其高度的可配置性。4.1 资源配置与多实例运行默认配置可能不符合你的需求。launch_cvd提供了丰富的参数# 启动一个拥有 4 个 CPU 核心、8GB 内存、256GB 存储的强性能设备 launch_cvd -cpus4 -memory_mb8192 -data_policyalways_create -blank_data_image_mb262144 # 同时启动多个设备用于测试多设备交互如蓝牙配对、Nearby Share launch_cvd --num_instances2 # 第二个实例的 ADB 端口会是 6521Web UI 端口会是 8444以此类推。实操心得-data_policyalways_create和-blank_data_image_mb是关键。默认情况下Cuttlefish 会复用上一次的数据镜像以加速启动。但在进行干净的测试或镜像有重大变更时这会导致奇怪的问题。使用always_create确保每次都是全新的用户数据分区。blank_data_image_mb则允许你设置数据分区的大小测试需要大量本地存储的应用时非常有用。4.2 网络与传感器模拟Cuttlefish 可以模拟一个真实的网络环境。# 启动设备并启用模拟调制解调器可以设置信号强度、网络类型4G/5G launch_cvd --modem_simulator_sim_type5G在 Web UI 的设备控制面板中你可以动态改变网络状态飞行模式、信号格、GPS 位置、电池电量等。这对于测试应用在不同网络条件和设备状态下的行为至关重要。你甚至可以通过adb直接注入传感器数据adb shell cmd sensor_injection set-data \ --sensor-type android.sensor.accelerometer \ --values 0.0 9.8 0.0这个命令模拟了设备平放时加速度计的数据重力加速度在 Y 轴。这对于测试游戏、健身应用或任何依赖传感器的功能来说是自动化测试的神器。4.3 使用自定义内核与系统镜像这是 Cuttlefish 作为系统开发工具的核心价值。假设你修改了 AOSP 内核 (common-android分支) 并编译出了新的bzImage。# 停止当前运行的实例 stop_cvd # 使用自定义内核启动并指定你编译的完整镜像集 launch_cvd \ --kernel_path/path/to/your/custom/bzImage \ --system_image/path/to/system.img \ --boot_image/path/to/boot.img \ --vendor_image/path/to/vendor.img通过这种方式你可以无缝地将内核开发、驱动调试、系统服务修改的验证流程整合到 Cuttlefish 中极大提升开发效率。5. 常见问题排查与实战经验录在实际使用中你肯定会遇到各种问题。下面是我踩过的一些坑和解决方案。5.1 启动失败类问题问题执行launch_cvd后卡住或快速退出日志中出现Failed to allocate KVM VM或/dev/kvm权限错误。排查 这几乎总是 KVM 权限或可用性问题。解决确认已重新登录执行groups命令确保输出中包含kvm和libvirt。检查 KVM 模块lsmod | grep kvm。如果没有输出手动加载sudo modprobe kvm_intel(Intel) 或sudo modprobe kvm_amd。检查 BIOS 设置确保 CPU 的虚拟化技术Intel VT-x, AMD-V已在 BIOS/UEFI 中启用。如果你是在云服务器上操作需要选择支持嵌套虚拟化的实例类型。如果在 VMware/VirtualBox 内运行 Ubuntu需要在虚拟机设置中显式开启“虚拟化 Intel VT-x/EPT 或 AMD-V/RVI”选项。问题Web UI (https://localhost:8443) 无法打开或打开后黑屏/无设备。排查 端口冲突或webrtc进程启动失败。解决检查端口占用sudo ss -tulpn | grep -E ‘:(8443|6520)’。如果被其他进程占用可以停止该进程或者用launch_cvd --webrtc_port9443 --adb_port7420指定新端口。查看 Cuttlefish 日志所有进程的日志默认输出到stdout和stderr。仔细阅读launch_cvd启动时的最后几十行输出看是否有webrtc相关的错误。常见错误是缺少某些 WebRTC 的依赖。尝试使用--start_webrtcfalse参数启动然后通过 VNC 连接如果启用。这可以判断是 Android 系统没起来还是仅仅是 Web 前端的问题。5.2 运行时与连接类问题问题adb connect localhost:6520失败提示cannot connect to localhost:6520。排查 ADB 桥接服务 (tcp_publisher) 未正常运行或防火墙阻止。解决检查 Cuttlefish 进程ps aux | grep cvd。应该能看到crosvm、webrtc、tcp_publisher等多个进程。如果tcp_publisher不存在可能是启动时出错了。检查主机防火墙Ubuntu 默认的ufw可能会阻止本地端口。可以临时禁用测试sudo ufw disable测试后记得重新启用sudo ufw enable。使用adb devices前先尝试adb kill-server adb start-server重启 ADB 守护进程。问题设备运行缓慢UI 卡顿。排查 资源不足或图形渲染模式不佳。解决增加资源使用-cpus和-memory_mb分配更多 CPU 和内存。对于 UI 测试建议至少 2 个核心和 4GB 内存。启用 GPU 加速如果主机有物理 GPU 并安装了正确的驱动可以尝试在launch_cvd中添加--gpu_modehost参数。这会将主机的 GPU 直通或虚拟化给 Cuttlefish大幅提升图形性能。但配置相对复杂需要主机支持 SR-IOV 或类似技术。降低分辨率默认分辨率可能很高。使用--x_res720 --y_res1280降低屏幕分辨率以提升性能。5.3 镜像与刷写类问题问题使用自定义镜像启动后设备卡在 Android Logo 动画Bootloop。排查 镜像不兼容或损坏。Cuttlefish 对镜像的格式和内容有特定要求。解决确认镜像目标你构建或下载的镜像必须是aosp_cf_x86_64_*目标而不是aosp_x86_64_*。后者是给传统 AVD 用的。检查镜像完整性确保下载的 ZIP 包完整解压无错误。对于自编译镜像确保lunch时选择了正确的 target。查看内核日志在启动命令中加入--debug参数获取更详细的内核启动日志。卡住时尝试通过adb如果能连接上的话执行adb shell dmesg | tail -100或者查看主机上crosvm进程的输出寻找 panic 或 error 信息。尝试干净启动使用-data_policyalways_create确保不是旧数据分区导致的不兼容。问题如何持久化我对虚拟设备的修改Cuttlefish 的实例数据默认存储在~/.android/cuttlefish/下。但直接备份这个目录并不总是可靠。推荐的方法是在虚拟设备中进行你需要的所有配置和安装。关闭设备 (stop_cvd)。使用cp命令备份~/.android/cuttlefish/instances/cvd-1/data.img这个文件。这个文件包含了整个数据分区。下次启动时可以通过launch_cvd --data_image/path/to/your/backup/data.img来使用这个备份的数据镜像从而恢复到你保存的状态。我个人在深度使用 Cuttlefish 一年多后最大的体会是它彻底改变了 Android 系统级功能的开发测试流程。将原本需要真机集群才能完成的兼容性测试、压力测试搬到了可版本化、可自动化的云端虚拟集群中。虽然初期搭建和问题排查有一定门槛但一旦跑通其带来的效率提升和成本节约是巨大的。对于任何从事 Android 框架、HAL、系统定制或深度自动化测试的工程师来说投入时间掌握 Cuttlefish 都是一笔非常划算的投资。
1. 项目概述为什么我们需要 Cuttlefish如果你是一名 Android 开发者或者对 Android 系统底层感兴趣那么“模拟器”和“虚拟机”这两个词你一定不陌生。从早期的 Android SDK 自带的模拟器AVD到后来性能更强的第三方模拟器它们都是我们开发和测试应用的重要工具。但今天要聊的Cuttlefish和这些“传统”的模拟器有本质的不同。它不是用来让你在电脑上玩手游的也不是一个简单的应用运行沙盒。Cuttlefish 是一个由 Google 官方维护的、可配置的、用于 Android 平台开发的虚拟 Android 设备。简单来说Cuttlefish 能让你在云端服务器或者本地的高性能机器上虚拟出一个几乎与真实硬件无异的 Android 设备。这个“设备”拥有完整的 Android 框架、内核、驱动栈甚至可以通过虚拟化技术模拟出 GPU、TPU 等专用硬件。这意味着什么意味着你可以用它来开发和测试那些对硬件有深度依赖的功能比如相机 HAL硬件抽象层、传感器融合、神经网络加速、甚至是完整的车载信息娱乐系统IVI。这些都是普通 AVD 或第三方模拟器难以企及的领域。我第一次接触 Cuttlefish 是在为一个车载 Android 项目做系统级集成测试时。当时我们需要验证一个自定义的音频路由策略它深度依赖特定的 SoC 音频驱动和 Android Automotive 的音频框架。在物理真机上反复刷机测试效率极低且风险高。而普通的 AVD 根本无法模拟出我们定制的硬件接口。Cuttlefish 的出现解决了这个痛点我们可以在 CI/CD 流水线中自动启动一个包含我们自定义系统镜像的虚拟设备运行完整的自动化测试套件。这不仅仅是“模拟一个手机”而是“虚拟化一块开发板”。2. Cuttlefish 的核心架构与工作原理拆解要理解 Cuttlefish 的强大之处必须深入到它的架构层面。它不是一个单体应用而是一个基于crosvmChrome OS 虚拟机的、模块化的虚拟化解决方案。2.1 与传统 AVD 的本质区别很多人会把 Cuttlefish 和 Android Studio 里的 AVDAndroid Virtual Device搞混。虽然它们目标都是“在非手机硬件上运行 Android”但实现路径和深度天差地别。AVD (QEMU-based) 它基于 QEMU 这个通用的机器模拟器。AVD 模拟的是一个特定的、预设的硬件模型比如 Pixel 6。它主要面向应用开发者目的是提供一个快速启动、易于使用的环境来运行和调试 APK。它的系统镜像通常是通用的“通用系统镜像”GSI剥离了很多硬件特定的驱动和 HAL。你无法轻易地更换内核或者添加一个自己编写的硬件服务。Cuttlefish (crosvm-based) 它使用 crosvm 来提供更强的隔离性和性能。Cuttlefish 的核心思想是虚拟化硬件接口而不是模拟一个完整的、固定的手机模型。它通过 VirtIO 等虚拟化标准将主机的资源CPU、内存、存储、网络以及一些虚拟的“设备”如虚拟 GPU、虚拟 TPU、虚拟摄像头暴露给 Guest Android 系统。最关键的是你可以使用自己编译的、包含任意定制驱动的完整 Android 系统镜像包括boot.img,vendor.img,system.img等来启动它。这使得它成为系统开发者、OEM 厂商和芯片供应商进行平台级开发和集成测试的理想工具。用一个类比来说AVD 像是一个“安卓手机模拟器”游戏你只能使用游戏里提供的固定角色和装备而 Cuttlefish 则是一个“安卓硬件沙盒”你可以自带所有的硬件蓝图和驱动程序在这个沙盒里组装并测试你自己的定制手机。2.2 组件交互与启动流程一个 Cuttlefish 实例的启动涉及多个守护进程的协同工作。理解这个过程对后续的问题排查至关重要。cuttlefish-user与cuttlefish-base 这是两个核心的 Debian 软件包。cuttlefish-base包含了所有运行时需要的工具和库而cuttlefish-user则负责管理用户空间的进程。安装它们后你的主机系统会多出像launch_cvd这样的关键命令。launch_cvd- 启动器 这是你启动虚拟设备的入口命令。它的工作非常复杂读取你指定的镜像文件路径--system_image,--boot_image,--vendor_image等。为虚拟机分配资源CPU核心数、内存大小。启动一系列的“虚拟设备”后端进程每个进程对应一种硬件。例如crosvm 运行 Android 内核和系统的主虚拟机进程。webrtc 提供基于 WebRTC 的音频/视频流这是 Cuttlefish 的“屏幕”你可以通过浏览器来访问设备的 UI。tcp_publisher 管理设备的网络端口转发比如将虚拟设备的 ADB 端口通常 6520映射到主机的某个端口。modem_simulator 模拟蜂窝网络调制解调器。gnss_grpc_proxy 模拟 GPS 信号。运行时交互 设备启动后你可以通过多种方式与它交互Web UI 在浏览器中打开https://localhost:8443你会看到一个设备列表和实时屏幕画面。这是最直观的交互方式。ADB 通过adb connect localhost:6520连接到设备之后就可以像操作真机一样使用所有 ADB 命令。Fastboot 虚拟设备也支持 Fastboot 模式你可以通过fastboot -s vsock-3:5555 flash ...这样的命令来刷写新的镜像。这种模块化设计的好处是灵活且健壮。如果虚拟摄像头服务崩溃了通常不会导致整个 Android 系统宕机你可以单独重启这个服务。3. 从零开始Cuttlefish 环境搭建与配置实战理论讲得再多不如亲手跑起来。下面我将以在 Ubuntu 22.04 LTS 系统上搭建 Cuttlefish 为例展示完整的流程和每一步背后的考量。3.1 系统准备与依赖安装Cuttlefish 对主机系统有一定要求主要是内核版本和虚拟化支持。注意强烈建议在物理机或拥有完整虚拟化支持Intel VT-x/AMD-V的虚拟机上操作。嵌套虚拟化在虚拟机里再开虚拟机虽然可能成功但性能和稳定性会大打折扣且问题排查极其复杂。首先更新系统并安装基础依赖sudo apt update sudo apt upgrade -y sudo apt install -y git curl python3 python3-pip接下来是核心依赖KVM基于内核的虚拟机。Cuttlefish 通过 KVM 来获得接近原生的 CPU 和内存性能。# 安装 KVM 及相关工具 sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager # 将当前用户加入 kvm 和 libvirt 组避免每次都用 sudo sudo adduser $USER kvm sudo adduser $USER libvirt操作完成后务必注销并重新登录让组权限生效。之后验证 KVM 是否可用# 检查 KVM 模块是否加载 lsmod | grep kvm # 你应该看到 kvm_intel 或 kvm_amd 模块 # 检查当前用户是否有访问 /dev/kvm 的权限 ls -l /dev/kvm # 输出应为 crw-rw---- 1 root kvm ...且你的用户在 kvm 组内。3.2 安装 Cuttlefish 主机包Google 为 Debian/Ubuntu 系列提供了官方的软件包仓库。我们通过添加这个仓库来安装。# 下载并添加 Google 的 Linux 软件包签名密钥 curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/google-cloud.gpg # 添加 Cuttlefish 软件包仓库 echo deb https://packages.cloud.google.com/apt cuttlefish-main main | sudo tee /etc/apt/sources.list.d/cuttlefish.list sudo apt update # 安装 Cuttlefish sudo apt install -y cuttlefish-user安装过程会自动拉取cuttlefish-base作为依赖。安装完成后关键的命令行工具如launch_cvd、stop_cvd、adb的特殊版本等就已经就绪了。3.3 获取 Android 系统镜像这是最关键也最容易出错的一步。你不能直接用从 Pixel 手机提取的 OTA 包也不能用 Android Studio 下载的通用镜像。你需要专门为 Cuttlefish 构建或下载的镜像。方案一推荐用于最新特性测试从 CI 构建服务器下载Google 的 Android 团队会为每个提交到 AOSP 主分支的变更构建 Cuttlefish 镜像。这是获取最新、最稳定镜像的官方途径。访问 Android CI 网站 。在左侧选择aosp-main分支找到最新的成功构建通常是最上面绿色的那个。点击进入构建详情页在 “Target” 列找到名为aosp_cf_x86_64_phone-userdebug或aosp_cf_x86_64_tv-userdebug根据你需要测试的设备类型的目标。点击该目标下载aosp_cf_x86_64_phone-img-xxxxxx.zip这样的镜像包。解压到某个目录例如~/android_images/。方案二用于自定义开发从 AOSP 源码自行构建如果你需要测试自己修改的 AOSP 代码这是唯一的方法。source build/envsetup.sh lunch aosp_cf_x86_64_phone-userdebug # 选择 Cuttlefish 手机目标 m -j$(nproc) # 开始构建耗时很长构建成功后镜像文件位于$ANDROID_PRODUCT_OUT目录下包含boot.img,system.img,vendor.img,super.img等。3.4 启动你的第一个虚拟设备假设你已经把下载的镜像解压到了~/android_images目录。启动命令非常简单cd ~/android_images launch_cvd第一次运行launch_cvd时它会做很多初始化工作生成实例独有的数据分区镜像、创建证书用于 Web UI 的 HTTPS 连接、分配资源等。这个过程可能需要一两分钟。当你在终端看到大量日志输出最后稳定下来并且出现类似VIRTUAL_DEVICE_DISPLAY_POWER_MODE_CHANGED这样的日志时基本就启动成功了。此时打开你的浏览器访问https://localhost:8443。由于使用的是自签名证书浏览器会提示不安全需要手动点击“高级”-“继续前往”之类的选项。之后你应该能看到一个虚拟 Android 设备的启动动画并最终进入系统界面。在另一个终端你可以用 ADB 连接它adb connect localhost:6520 adb devices # 你应该看到 localhost:6520 device adb shell # 现在你就在虚拟设备的 Shell 里了4. 高级配置与定制化技巧基础启动只是开始。Cuttlefish 的强大在于其高度的可配置性。4.1 资源配置与多实例运行默认配置可能不符合你的需求。launch_cvd提供了丰富的参数# 启动一个拥有 4 个 CPU 核心、8GB 内存、256GB 存储的强性能设备 launch_cvd -cpus4 -memory_mb8192 -data_policyalways_create -blank_data_image_mb262144 # 同时启动多个设备用于测试多设备交互如蓝牙配对、Nearby Share launch_cvd --num_instances2 # 第二个实例的 ADB 端口会是 6521Web UI 端口会是 8444以此类推。实操心得-data_policyalways_create和-blank_data_image_mb是关键。默认情况下Cuttlefish 会复用上一次的数据镜像以加速启动。但在进行干净的测试或镜像有重大变更时这会导致奇怪的问题。使用always_create确保每次都是全新的用户数据分区。blank_data_image_mb则允许你设置数据分区的大小测试需要大量本地存储的应用时非常有用。4.2 网络与传感器模拟Cuttlefish 可以模拟一个真实的网络环境。# 启动设备并启用模拟调制解调器可以设置信号强度、网络类型4G/5G launch_cvd --modem_simulator_sim_type5G在 Web UI 的设备控制面板中你可以动态改变网络状态飞行模式、信号格、GPS 位置、电池电量等。这对于测试应用在不同网络条件和设备状态下的行为至关重要。你甚至可以通过adb直接注入传感器数据adb shell cmd sensor_injection set-data \ --sensor-type android.sensor.accelerometer \ --values 0.0 9.8 0.0这个命令模拟了设备平放时加速度计的数据重力加速度在 Y 轴。这对于测试游戏、健身应用或任何依赖传感器的功能来说是自动化测试的神器。4.3 使用自定义内核与系统镜像这是 Cuttlefish 作为系统开发工具的核心价值。假设你修改了 AOSP 内核 (common-android分支) 并编译出了新的bzImage。# 停止当前运行的实例 stop_cvd # 使用自定义内核启动并指定你编译的完整镜像集 launch_cvd \ --kernel_path/path/to/your/custom/bzImage \ --system_image/path/to/system.img \ --boot_image/path/to/boot.img \ --vendor_image/path/to/vendor.img通过这种方式你可以无缝地将内核开发、驱动调试、系统服务修改的验证流程整合到 Cuttlefish 中极大提升开发效率。5. 常见问题排查与实战经验录在实际使用中你肯定会遇到各种问题。下面是我踩过的一些坑和解决方案。5.1 启动失败类问题问题执行launch_cvd后卡住或快速退出日志中出现Failed to allocate KVM VM或/dev/kvm权限错误。排查 这几乎总是 KVM 权限或可用性问题。解决确认已重新登录执行groups命令确保输出中包含kvm和libvirt。检查 KVM 模块lsmod | grep kvm。如果没有输出手动加载sudo modprobe kvm_intel(Intel) 或sudo modprobe kvm_amd。检查 BIOS 设置确保 CPU 的虚拟化技术Intel VT-x, AMD-V已在 BIOS/UEFI 中启用。如果你是在云服务器上操作需要选择支持嵌套虚拟化的实例类型。如果在 VMware/VirtualBox 内运行 Ubuntu需要在虚拟机设置中显式开启“虚拟化 Intel VT-x/EPT 或 AMD-V/RVI”选项。问题Web UI (https://localhost:8443) 无法打开或打开后黑屏/无设备。排查 端口冲突或webrtc进程启动失败。解决检查端口占用sudo ss -tulpn | grep -E ‘:(8443|6520)’。如果被其他进程占用可以停止该进程或者用launch_cvd --webrtc_port9443 --adb_port7420指定新端口。查看 Cuttlefish 日志所有进程的日志默认输出到stdout和stderr。仔细阅读launch_cvd启动时的最后几十行输出看是否有webrtc相关的错误。常见错误是缺少某些 WebRTC 的依赖。尝试使用--start_webrtcfalse参数启动然后通过 VNC 连接如果启用。这可以判断是 Android 系统没起来还是仅仅是 Web 前端的问题。5.2 运行时与连接类问题问题adb connect localhost:6520失败提示cannot connect to localhost:6520。排查 ADB 桥接服务 (tcp_publisher) 未正常运行或防火墙阻止。解决检查 Cuttlefish 进程ps aux | grep cvd。应该能看到crosvm、webrtc、tcp_publisher等多个进程。如果tcp_publisher不存在可能是启动时出错了。检查主机防火墙Ubuntu 默认的ufw可能会阻止本地端口。可以临时禁用测试sudo ufw disable测试后记得重新启用sudo ufw enable。使用adb devices前先尝试adb kill-server adb start-server重启 ADB 守护进程。问题设备运行缓慢UI 卡顿。排查 资源不足或图形渲染模式不佳。解决增加资源使用-cpus和-memory_mb分配更多 CPU 和内存。对于 UI 测试建议至少 2 个核心和 4GB 内存。启用 GPU 加速如果主机有物理 GPU 并安装了正确的驱动可以尝试在launch_cvd中添加--gpu_modehost参数。这会将主机的 GPU 直通或虚拟化给 Cuttlefish大幅提升图形性能。但配置相对复杂需要主机支持 SR-IOV 或类似技术。降低分辨率默认分辨率可能很高。使用--x_res720 --y_res1280降低屏幕分辨率以提升性能。5.3 镜像与刷写类问题问题使用自定义镜像启动后设备卡在 Android Logo 动画Bootloop。排查 镜像不兼容或损坏。Cuttlefish 对镜像的格式和内容有特定要求。解决确认镜像目标你构建或下载的镜像必须是aosp_cf_x86_64_*目标而不是aosp_x86_64_*。后者是给传统 AVD 用的。检查镜像完整性确保下载的 ZIP 包完整解压无错误。对于自编译镜像确保lunch时选择了正确的 target。查看内核日志在启动命令中加入--debug参数获取更详细的内核启动日志。卡住时尝试通过adb如果能连接上的话执行adb shell dmesg | tail -100或者查看主机上crosvm进程的输出寻找 panic 或 error 信息。尝试干净启动使用-data_policyalways_create确保不是旧数据分区导致的不兼容。问题如何持久化我对虚拟设备的修改Cuttlefish 的实例数据默认存储在~/.android/cuttlefish/下。但直接备份这个目录并不总是可靠。推荐的方法是在虚拟设备中进行你需要的所有配置和安装。关闭设备 (stop_cvd)。使用cp命令备份~/.android/cuttlefish/instances/cvd-1/data.img这个文件。这个文件包含了整个数据分区。下次启动时可以通过launch_cvd --data_image/path/to/your/backup/data.img来使用这个备份的数据镜像从而恢复到你保存的状态。我个人在深度使用 Cuttlefish 一年多后最大的体会是它彻底改变了 Android 系统级功能的开发测试流程。将原本需要真机集群才能完成的兼容性测试、压力测试搬到了可版本化、可自动化的云端虚拟集群中。虽然初期搭建和问题排查有一定门槛但一旦跑通其带来的效率提升和成本节约是巨大的。对于任何从事 Android 框架、HAL、系统定制或深度自动化测试的工程师来说投入时间掌握 Cuttlefish 都是一笔非常划算的投资。
函数详解：从原理到实践，生成高质量随机数的正确姿势)
)
