从命令行启动模拟器

Android SDK 包含一个 Android 设备模拟器,这是一台在您的计算机上运行的虚拟设备。有了 Android 模拟器,在您开发和测试 Android 应用时就不需要使用实体设备。

本页面介绍了可与 Android 模拟器一起使用的命令行功能。 如需了解如何使用 Android 模拟器界面,请参阅在 Android 模拟器上运行应用

启动模拟器

除了在运行的项目中启动模拟器通过 AVD 管理器启动模拟器,您还可以使用 emulator 命令启动模拟器。

以下是从终端提示符启动虚拟设备的基本命令行语法:

emulator -avd avd_name [ {-option [value]} … ]

emulator @avd_name [ {-option [value]} … ]

例如,如果从 Mac 上运行的 Android Studio 启动模拟器,则默认命令行将类似如下:

/Users/janedoe/Library/Android/sdk/emulator/emulator -avd Pixel8_API_34 -netdelay none -netspeed full -qt-hide-window -grpc-use-token -idle-grpc-timeout

请注意,参数 -qt-hide-window -grpc-use-token -idle-grpc-timeout 仅用于在 Android Studio 中运行模拟器窗口。如果您想在自己的窗口中运行模拟器,则不应使用这些额外参数。

您可以在启动模拟器时指定启动选项,但启动后就无法指定。

如需查看 AVD 名称的列表,请输入以下命令:

emulator -list-avds

使用此选项可显示 Android 主目录中的 AVD 名称列表。 您可以通过将 ANDROID_SDK_HOME 环境变量设为以下目录来替换默认主目录:一个存储了所有配置和 AVD 内容的用户专属目录的根目录。

您可以在启动虚拟设备之前在终端窗口中设置该环境变量,也可以通过操作系统中的用户设置进行设置。例如,在 Linux 上的 .bashrc 文件中。

如需停止 Android 模拟器,请关闭模拟器窗口。

安装应用

除通过 Android Studio 或模拟器界面安装应用外,您还可以使用 adb 实用程序在虚拟设备上安装应用。

如需使用 adb 安装、运行和测试您的应用,请按以下常规步骤操作:

  1. 按照构建和运行应用中的说明,构建应用并将其打包到 APK 中。
  2. 使用任何必要的启动选项,按照上一部分中的说明从命令行启动模拟器。
  3. 使用 adb 安装您的应用。
  4. 在模拟器上运行并测试您的应用。
    在模拟器运行时,您可以根据需要使用模拟器控制台发出命令。

如要卸载应用,请像在 Android 设备上一样操作。

每次重启时,虚拟设备都会在用户数据磁盘分区 (userdata-qemu.img) 中保留应用及其状态数据。如需清除此数据,请使用 -wipe-data 选项启动模拟器或在 AVD 管理器中擦除相关数据。如需详细了解用户数据分区和其他存储空间,请参阅以下部分。

注意adb 实用程序将虚拟设备视为实际的实体设备。因此,您可能必须搭配 -d 标记使用一些常见的 adb 命令,例如 install。借助 -d 标记,您可以指定将哪个连接的设备用作命令的目标。如果您未指定 -d,则模拟器将以列表中的第一个设备为目标。

了解默认目录和文件

模拟器使用多个关联文件,其中 AVD 系统和数据目录是最重要的。在指定命令行选项时,了解模拟器目录结构和文件会很有帮助,但通常不需要修改默认目录或文件。

Android 模拟器使用 (QEMU) Hypervisor。

AVD 系统目录

系统目录包含模拟器用于模拟操作系统的 Android 系统映像。此目录具有由所有相同类型的 AVD 共享的特定于平台的只读文件,包括 API 级别、CPU 架构和 Android 变体。默认位置如下:

  • macOS 和 Linux - ~/Library/Android/sdk/system-images/android-apiLevel/variant/arch/
  • Windows - C:\Users\user\Library\Android\sdk\system-images\android-apiLevel\variant\arch\

其中:

  • apiLevel 是一个代表 API 级别的数字,或者是一个字母(适用于预览版)。例如,android-V 表示 Android VanillaIceCream 预览版。在发布时,它变成了 API 级别 35,即 android-35
  • variant 是与系统映像实现的特定功能相对应的名称。例如 google_apisandroid-wear
  • arch 是目标 CPU 架构。例如 x86

使用 -sysdir 选项为 AVD 指定其他系统目录。

模拟器从系统目录中读取以下文件:

表 1. Android 模拟器读取的系统目录文件

文件 说明 用于指定其他文件的选项
kernel-qemukernel-ranchu AVD 的二进制内核映像。kernel-ranchu的计算依据是 QEMU 模拟器。 -kernel
ramdisk.img 启动分区映像。这是 system.img(在装载系统映像之前最初由内核加载)的一个子集。它通常只包含一些二进制文件和初始化脚本。 -ramdisk
system.img 系统映像的只读初始版本。具体而言,包含与 API 级别和变体对应的系统库和数据的分区。 -system
userdata.img 数据分区的初始版本,在模拟系统中显示为 data/,包含 AVD 的所有可写入数据。当您创建新 AVD 或使用 ‑wipe-data 选项时,模拟器会使用此文件。如需了解详情,请参阅以下部分中的 userdata-qemu.img 文件说明。 -initdata
-init-data

AVD 数据目录

AVD 数据目录(也称为内容目录)特定于单个 AVD 实例,包含 AVD 的所有可修改数据。

默认位置如下,其中 name 是 AVD 名称:

  • macOS 和 Linux - ~/.android/avd/name.avd/
  • Windows 10 及更高版本 - C:\Users\user\.android\name.avd\

使用 -datadir 选项指定其他 AVD 数据目录。

下表列出了此目录中包含的最重要文件:

表 2. AVD 数据目录中的重要文件

文件 说明 用于指定其他文件的选项
userdata-qemu.img

数据分区的内容,在模拟系统中显示为 data/。当您创建新 AVD 时,或使用 -wipe-data 选项将 AVD 重置为出厂默认设置时,模拟器会复制系统目录中的 userdata.img 文件以创建此文件。

每个虚拟设备实例使用可写入的用户数据映像来存储特定于用户和会话的数据。例如,它使用该映像存储唯一身份用户的已安装应用数据、设置、数据库和文件。每个用户都有一个不同的 ANDROID_SDK_HOME 目录,用于存储该用户创建的 AVD 的数据目录。每个 AVD 都有一个 userdata-qemu.img 文件。

-data
cache.img 缓存分区映像,在模拟系统中显示为 cache/。当您首次创建 AVD 或使用 -wipe-data 选项时,该映像为空。它存储临时下载文件,由内容下载管理器(有时是系统)填充。例如,在模拟器正在运行时,浏览器使用它来缓存下载的网页和映像。您关闭虚拟设备电源后,该文件会被删除。您可以使用 -cache 选项保留该文件。 -cache
sdcard.img

(可选)SD 卡分区映像,让您可以模拟虚拟设备上的 SD 卡。您可以在 AVD 管理器中或使用 mksdcard 工具创建 SD 卡映像文件。该文件存储在开发计算机上,并且必须在启动时加载。

在 AVD 管理器中定义 AVD 时,您可以选择使用自动托管的 SD 卡文件或您通过 mksdcard 工具创建的文件。您可以在 AVD 管理器中查看与 AVD 关联的 sdcard.img 文件。-sdcard 选项 会替换 AVD 中指定的 SD 卡文件。 请注意,此 SD 卡选项不适用于装有 Apple Silicon 的 Mac。

虚拟设备正在运行时,您可以使用模拟器界面或 adb 实用程序浏览、发送文件到模拟 SD 卡,以及从模拟 SD 卡中复制和移除文件。您无法从正在运行的虚拟设备中移除模拟 SD 卡。

如需在加载 SD 卡文件之前将文件复制到其中,可以将映像文件作为循环设备安装,然后复制文件。或者使用 mtools 软件包等实用程序将文件直接复制到映像。

模拟器将文件视为字节池,因此 SD 卡格式无关紧要。

-wipe-data 选项不会影响此文件。如果要清除该文件,请删除该文件,然后使用 AVD 管理器或 mksdcard 工具重新创建它。更改文件大小也会删除该文件并创建新文件。

-sdcard

列出模拟器使用的目录和文件

您可以通过两种方式发现文件的位置:

  • 从命令行启动模拟器时,请使用 -verbose-debug init 选项。查看输出内容。
  • 使用 emulator -help-option 命令列出默认目录。例如:
    emulator -help-datadir
    Use '-datadir <dir>' to specify a directory where writable image files will be searched. On this system, the default directory is: /Users/me/.android See '-help-disk-images' for more information about disk image files.

命令行启动选项

本部分列出了在启动模拟器时可以在命令行中提供的选项。

注意:Android 模拟器正在不断开发中,以提高可靠性。如需了解针对各种命令行选项报告的问题的状态,以及如何报告 bug,请参阅 Android 问题跟踪器

常用选项

下表列出了您可能更常用的命令行启动选项:

表 3. 常用的命令行选项

命令行选项 说明
快速启动
-no-snapshot-load 执行冷启动,并在退出时保存模拟器状态。
-no-snapshot-save 如果可能,执行快速启动,但在退出时不保存模拟器状态。
-no-snapshot 完全停用快速启动功能,并且不会加载或保存模拟器状态。
设备硬件
-camera-back mode
-camera-front mode
设置后置或前置相机的模拟模式。这会替换 AVD 中的任何相机设置。

mode 可以是以下任何值:

  • emulated - 模拟器在软件中模拟相机。
  • webcamn - 模拟器使用连接到开发计算机的摄像头,由数字指定。如需查看相机列表,请使用 -webcam-list 选项。例如 webcam0
  • none - 在虚拟设备中停用相机。

例如:

emulator @Pixel8_API_34 -camera-back webcam0
-webcam-list 列出开发计算机上可用于模拟的摄像头。例如:
emulator @Pixel8_API_34 -webcam-list
        List of web cameras connected to the computer:
        Camera 'webcam0' is connected to device 'webcam0'
        on channel 0 using pixel format 'UYVY'

在该示例中,第一个 webcam0 是您在命令行中使用的名称。 第二个 webcam0 是开发计算机上的操作系统使用的名称。第二个名称因操作系统而异。

从 SDK 工具 25.2.4 开始,AVD 名称为必填项。

磁盘映像和内存
-memory size

指定物理 RAM 大小,范围为 1536 MB 到 8192 MB。例如:

emulator @Pixel8_API_34 -memory 2048

此值将替换 AVD 设置。

-sdcard filepath 指定 SD 卡分区映像文件的文件名和路径。例如:

emulator @Pixel8_API_34 -sdcard C:/sd/sdcard.img

如果找不到该文件,模拟器仍会启动,但没有 SD 卡。该命令返回 No SD Card Image 警告。

如果您未指定此选项,则默认为数据目录中的 sdcard.img(除非 AVD 指定了不同的值)。 如需详细了解模拟 SD 卡,请参阅 AVD 数据目录

-wipe-data 删除用户数据并从初始数据文件中复制数据。此选项会清除虚拟设备的数据,并将其恢复到首次定义时的状态。所有已安装应用和设置会被移除。例如:

emulator @Pixel8_API_34 -wipe-data

默认情况下,用户数据文件是 userdata-qemu.img,初始数据文件是 userdata.img。这两个文件都位于数据目录中。 -wipe-data 选项不会影响 sdcard.img 文件。如需详细了解用户数据,请参阅了解默认目录和文件部分。

调试
-debug tags 启用或停用一个或多个标记的调试消息显示。 用空格、英文逗号或列分隔符分隔多个标记。例如:

$ emulator @Pixel8_API_34 -debug init,metrics

如需停用标记,请在其前面放置一个短划线 (-)。例如,以下选项会显示所有调试消息,但与网络套接字和指标相关的消息除外:

-debug all,-socket,-metrics

如需查看标记和说明的列表,请使用 -help-debug-tags 选项。例如:

emulator -help-debug-tags

您可以在 ANDROID_VERBOSE 环境变量中定义默认调试标记。以逗号分隔列表的形式定义要使用的标记。 以下示例显示了如何指定 socketgles 标记:

ANDROID_VERBOSE=socket,gles

它相当于使用:

-debug-socket -debug-gles

-debug socket,gles

-debug-tag
-debug-no-tag
启用特定的调试消息类型。使用 no 形式停用调试消息类型。例如:

emulator @Pixel8_API_34 -debug-all -debug-no-metrics

如需查看标记列表,请使用 emulator -help-debug-tags 命令。

-logcat logtags 启用一个或多个标记的 logcat 消息显示,并将其写入终端窗口。例如,以下命令启用来自所有组件的错误消息:

emulator @Pixel8_API_34 -logcat *:e

logtags 使用与 adb logcat logtags 命令相同的格式。如需了解详情,请输入 adb logcat -help。 它是 componentName:logLevel 格式的以空格或逗号分隔的日志过滤器列表。 componentName 是星号通配符 (*)或组件名称,例如 ActivityManagerSystemServerInputManagerWindowManager

logLevel 是以下值之一:

  • v - 详细
  • d - 调试
  • i - 信息
  • w - 警告日志级别
  • e - 错误
  • s - 静默

以下示例显示了信息日志级别的 GSM 组件消息:

emulator @Pixel8_API_34 -logcat '*:s GSM:i'

如果您未在命令行中提供 -logcat 选项,则模拟器将查找 ANDROID_LOG_TAGS 环境变量。如果 ANDROID_LOG_TAGS 使用有效 logtags 值定义且不为空,则模拟器默认使用其值来启用向终端的 Logcat 输出。您还可以通过 adb 将相同日志消息或其他日志消息重定向到终端。

如需详细了解 Logcat 和 adb,请参阅 Logcat 命令行工具使用 Logcat 查看和写入日志Log 类以及发出 adb 命令

-show-kernel 在终端窗口中显示内核调试消息。例如:

emulator @Pixel8_API_34 -show-kernel

此选项的一个用途是检查启动过程是否正常运行。

-verbose 将模拟器初始化消息输出到终端窗口。例如:

emulator @Pixel8_API_34 -verbose

它显示在启动 AVD 中定义的虚拟设备时实际选择的文件和设置。此选项与指定 -debug-init 相同。

网络
-dns-server servers 使用指定的 DNS 服务器。servers 是一个逗号分隔列表,最多包含四个 DNS 服务器名称或 IP 地址。例如:
emulator @Pixel8_API_34 -dns-server 192.0.2.0,
192.0.2.255

默认情况下,模拟器会尝试检测您正在使用的 DNS 服务器,并在模拟防火墙网络中设置特殊别名,以允许 Android 系统直接连接到这些 DNS 服务器。使用 -dns-server 选项指定其他 DNS 服务器列表。

-http-proxy proxy 通过指定的 HTTP/HTTPS 代理进行所有 TCP 连接。如果您的模拟器必须通过代理服务器访问互联网,您可以使用此选项或 http_proxy 环境变量来设置相应的重定向。例如:

emulator @Pixel8_API_34 -http-proxy myserver:1981

proxy 可以是以下项之一:

http://server:port
http://username:password@server:port

http:// 前缀可以省略。

如果未提供此选项,则模拟器将查找 http_proxy 环境变量并自动使用与 proxy 格式匹配的任何值。 如需了解详情,请参阅结合使用模拟器和代理

-netdelay delay

将网络延迟模拟设置为以下 delay 值之一(以毫秒为单位):

  • gsm - GSM/CSD(最小值 150,最大值 550)。
  • hscsd - HSCSD(最小值 80,最大值 400)。
  • gprs - GPRS(最小值 35,最大值 200)。
  • edge - EDGE/EGPRS(最小值 80,最大值 400)。
  • umts - UMTS/3G(最小值 35,最大值 200)。
  • hsdpa - HSDPA(最小值 0,最大值 0)。
  • lte - LTE(最小值 0,最大值 0)。
  • evdo - EVDO(最小值 0,最大值 0)。
  • none - 无延迟时间,默认值(最小值 0,最大值 0)。
  • num - 指定确切的延迟时间。
  • min:max - 分别指定最小延迟时间和最大延迟时间。

例如:

emulator @Pixel8_API_34 -netdelay gsm

模拟器支持网络节流以及更高的连接延迟。 您可以通过皮肤配置或使用 ‑netspeed-netdelay 选项来定义它。

-netfast 停用网络节流功能。例如:

emulator @Pixel8_API_34 -netfast

此选项与指定 -netspeed full -netdelay none 相同。这些是选项的默认值。

-netspeed speed

设置网络速度模拟。使用以下 speed 值(以 kbps 为单位)之一,指定最大网络上传和下载速度:

  • gsm - GSM/CSD(上传:14.4,下载:14.4)。
  • hscsd - HSCSD(上传:14.4,下载:57.6)。
  • gprs - GPRS(上传:28.8,下载:57.6)。
  • edge - EDGE/EGPRS(上传:473.6,下载:473.6)。
  • umts - UMTS/3G(上传:384.0,下载:384.0)。
  • hsdpa - HSDPA(上传:5760.0,下载:13,980.0)。
  • lte - LTE(上传:58,000,下载:173,000)。
  • evdo - EVDO(上传:75,000,下载:280,000)。
  • full - 无限制,默认值(上传:0.0,下载:0.0)。
  • num - 同时指定上传和下载速度。
  • up:down - 分别指定上传速度和下载速度。

例如:

emulator @Pixel8_API_34 -netspeed edge

模拟器支持网络节流以及更高的连接延迟。 您可以通过皮肤配置或使用 ‑netspeed-netdelay 选项来定义它。

-port port 设置用于控制台和 adb 的 TCP 端口号。例如:

emulator @Pixel8_API_34 -port 5556

对于计算机上运行的第一个虚拟设备实例,默认值为 5554。虚拟设备通常占用一对相邻端口:控制台端口和 adb 端口。在特定计算机上运行的第一个虚拟设备的控制台使用控制台端口 5554 和 adb 端口 5555。后续实例使用的端口号递增 2。例如:5556/5557、5558/5559,等等。范围是 5554 到 5682,可用于 64 个并发虚拟设备。

端口分配通常与指定 -ports port,{port + 1} 相同。{port + 1} 必须处于空闲状态,并且预留给 adb。如果任何控制台或 adb 端口已被使用,模拟器将无法启动。

‑port 选项可报告虚拟设备正在使用的端口和序列号,并在您提供的值出现问题时发出警告。在模拟器界面中,您可以在窗口标题中看到控制台端口号,并可以通过选择 Help > About 来查看 adb 端口号。

请注意,若 port 值在 5554 到 5584 范围内但不是偶数,则如果 adb server 在模拟器之后启动,当您使用 adb devices 命令时,虚拟设备将启动但不可见。因此,我们建议使用偶数控制台端口号。

-ports
console-port,adb-port
设置用于控制台和 adb 的 TCP 端口。例如:

emulator @Pixel8_API_34 -ports 5556,5559

有效端口范围是 5554 到 5682,可用于 64 个并发虚拟设备。-ports 选项可报告模拟器实例正在使用的端口和序列号,并在您提供的值出现问题时发出警告。

我们建议尽可能使用 -port 选项。-ports 选项适用于需要特殊设置的网络配置。

如需详细了解如何设置控制台端口和 adb 端口,请查看 -port 选项。

-tcpdump filepath 捕获网络数据包并将其存储在文件中。例如:

emulator @Pixel8_API_34 -tcpdump /path/dumpfile.cap

使用该选项开始捕获通过模拟器的虚拟以太网 LAN 发送的所有网络数据包。然后,您可以使用 Wireshark 之类的工具来分析流量。

请注意,此选项会捕获所有以太网数据包,不限于 TCP 连接。

系统
-accel mode 配置模拟器虚拟机加速。例如:

emulator @Pixel8_API_34 -accel auto

加速模拟仅适用于 x86 和 x86_64 系统映像。在 Linux 上,它依赖于 KVM。在 Windows 和 Mac 上,它依赖于 Intel CPU 和 Intel HAXM 驱动程序。如果您未在模拟 x86 或 x86_64 设备,此选项会被忽略。

有效的 mode 值如下:

  • auto - 自动确定是否支持加速并尽可能使用此值(默认值)。
  • off - 完全停用加速,这主要用于调试。
  • on - 强制加速。如果 KVM 或 HAXM 未安装或无法使用,则模拟器将无法启动并输出错误消息。

如需了解详情,请参阅为 Android 模拟器配置硬件加速

-accel-check 检查是否已安装模拟器虚拟机加速所需的 Hypervisor(HAXM 或 KVM)。例如:

emulator -accel-check

如需了解详情,请参阅检查是否安装了 Hypervisor

-engine engine

指定模拟器引擎:

  • auto - 自动选择引擎(默认)。
  • classic - 使用较旧的 QEMU 1 引擎(已废弃)。
  • qemu2 - 使用较新的 QEMU 2 引擎。

例如:

emulator @Pixel8_API_34 -engine auto

自动检测功能应该能够选择在模拟特定 AVD 时可提供最佳性能的值。请将 -engine 选项用于调试和比较目的。

-gpu mode 选择 GPU 模拟模式。例如:

emulator @Pixel8_API_34 -gpu swiftshader_indirect

如需了解详情,请参阅配置图形加速

-no-accel 在使用 x86 或 x86_64 系统映像时停用模拟器虚拟机加速。它只适用于调试,与指定 -accel off 相同。例如:

emulator @Pixel8_API_34 -no-accel

如需了解详情,请参阅为 Android 模拟器配置硬件加速

-nojni
-no-jni
在 Android Dalvik 或 ART 运行时中停用扩展 Java 原生接口 (JNI) 检查。例如:

emulator @Pixel8_API_34 -nojni

当您启动虚拟设备时,扩展 JNI 检查会默认启用。如需了解详情,请参阅 JNI 提示

-selinux {disabled|permissive} 在 Linux 操作系统上,将安全增强型 Linux (SELinux) 安全模块设置为 disabledpermissive 模式。例如:

me-linux$ emulator @Pixel8_API_34 -selinux permissive

默认情况下,SELinux 处于 enforcing 模式,这意味着强制执行安全政策。permissive 模式会加载 SELinux 政策,但不强制执行.此选项只是记录违反政策的情况。disabled 模式会停用对 SELinux 的内核支持。

-timezone timezone

将虚拟设备的时区设置为 timezone,而不是主机时区。例如:

emulator @Pixel8_API_34 -timezone Europe/Paris

默认情况下,模拟器使用开发计算机的时区。如果自动检测无法正常运行,使用此选项指定其他时区。timezone 值必须采用 zoneinfo 格式,即 area/locationarea/subarea/location。例如:

  • America/Los_Angeles
  • Europe/Paris
  • America/Argentina/Buenos_Aires

指定的时区必须位于 zoneinfo 数据库中。

-version 显示模拟器版本号。例如:

emulator @Pixel8_API_34 -version

emulator -version
界面
-no-boot-anim 在模拟器启动期间停用启动动画以加快启动速度。 例如:

emulator @Pixel8_API_34 -no-boot-anim

在速度较慢的计算机上,此选项可以显著加快启动序列。

-screen mode 设置模拟触摸屏模式。例如:

emulator @Pixel8_API_34 -screen no-touch

mode 可以是以下任何值:

  • touch - 模拟触摸屏(默认)。
  • multi-touch - 模拟多点触控屏幕。
  • no-touch - 停用触摸屏和多点触控屏幕模拟。

高级选项

开发者可以使用下表中的命令行启动选项,但普通应用开发者并不会经常使用这些选项。

在说明中,工作目录是您正在输入命令的终端中的当前目录。如需了解 AVD 系统目录和数据目录以及存储在其中的文件,请参阅默认目录和文件的相关部分。

其中一些选项适合外部应用开发者,一些主要由平台开发者使用。应用开发者创建 Android 应用并在特定 AVD 上运行这些应用。平台开发者使用 Android 系统,并且在无预先创建的 AVD 的模拟器内运行该系统。

表 4. 高级命令行选项

高级选项 简介
-bootchart timeout

启用 bootchart,设有超时(以秒为单位)。一些 Android 系统映像具有经过修改的 init 系统,该系统集成了 bootchart 设备。您可以使用此选项将 bootchart 超时期限传给系统。如果您的 init 系统没有激活 bootchart,则该选项不执行任何操作。此选项主要适用于平台开发者,而非外部应用开发者。

例如:

emulator @Pixel8_API_34 -bootchart 120
-cache filepath

指定缓存分区映像文件。提供文件名,以及绝对路径或相对于数据目录的路径,以设置永久性缓存文件。如果该文件不存在,则模拟器会将其创建为空文件。

例如:

emulator @Pixel8_API_34 -cache
   ~/.android/avd/Pixel8_API_34.avd/cache_persistent.img

如果您不使用此选项,则默认为名为 cache.img 的临时文件。如需了解详情,请参阅 AVD 数据目录

-cache-size size

设置缓存分区大小(以 MB 为单位)。

例如:

emulator @Pixel8_API_34 -cache-size 1000

如果您未指定此选项,则默认为 66 MB。通常,大多数应用开发者不需要此选项,除非他们需要下载大于默认缓存的超大文件。如需详细了解缓存文件,请参阅 AVD 数据目录

-data filepath

设置用户数据分区映像文件。提供文件名,以及绝对路径或相对于工作目录的路径,以设置永久性用户数据文件。如果该文件不存在,则模拟器会从默认 userdata.img 文件创建映像,以您指定的文件名存储该映像,并在关闭时将用户数据保留到该映像。

例如:

emulator @Pixel8_API_34 -data
   ~/.android/avd/Pixel8_API_34.avd/userdata-test.img

如果您不使用此选项,则默认为名为 userdata-qemu.img 的文件。如需详细了解用户数据文件,请参阅 AVD 数据目录

-datadir dir

使用绝对路径指定数据目录。如需了解详情,请参阅 AVD 数据目录

例如:

emulator @Pixel8_API_34 -datadir
   ~/.android/avd/Pixel8_API_34.avd/mytest
-force-32bit

在 64 位平台上使用 32 位模拟器。有时,此选项对测试或调试很有用。例如,有一个问题,模拟器有时不能在 64 位 Windows 上运行,但能在 32 位 Windows 上运行。此选项有助于执行比较以调试问题。示例如下:

emulator @Pixel8_API_34 -force-32bit
-help-disk-images

获取有关磁盘映像的帮助。此选项提供与应用开发者和平台开发者相关的信息。例如:

emulator -help-disk-images
-help-char-devices

获取有关字符 device 规范的帮助。某些模拟器选项需要 device 参数。 例如:

emulator -help-char-devices
-help-sdk-images

获取与应用开发者相关的磁盘映像的帮助。可通过此选项了解使用 SDK 工具创建的 AVD 的映像文件所在的位置。例如:

emulator -help-sdk-images
-help-build-images

获取与平台开发者相关的磁盘映像的帮助。例如:

emulator -help-build-images
-initdata filepath
-init-data filepath

指定数据分区的初始版本。擦除用户数据后,模拟器会将指定文件的内容复制到用户数据(默认为 userdata-qemu.img 文件),而不是使用默认 userdata.img 文件作为初始版本。指定文件名,以及绝对路径或相对于工作目录的路径。

例如:

emulator @Pixel8_API_34 -initdata
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/userdata-test.img

如果您未指定路径,它会将文件放在系统目录中。如需了解详情,请参阅 AVD 系统目录

-kernel filepath

使用特定的模拟内核。如果您未指定路径,则模拟器将在系统目录中查找。

使用 ‑show‑kernel 选项查看内核调试消息。

例如:

emulator @Pixel8_API_34 -kernel
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/kernel-test.img -show-kernel

如果您未指定此选项,则默认为 kernel-ranchu。如需了解详情,请参阅 AVD 系统目录

-noaudio
-no-audio

停用对此虚拟设备的音频支持。某些 Linux 和 Windows 计算机的音频驱动程序故障会导致不同的症状,例如阻止模拟器启动。在这种情况下,请使用此选项来解决此问题。或者,您也可以使用 QEMU_AUDIO_DRV 环境变量来更改音频后端。

例如:

emulator @Pixel8_API_34 -noaudio
-nocache
-no-cache

启动没有缓存分区的模拟器。如果您不使用此选项,则默认为名为 cache.img 的临时文件。此选项仅适用于平台开发者。如需了解详情,请参阅 AVD 数据目录

例如:

emulator @Pixel8_API_34 -nocache
-no-snapshot

禁止自动加载和保存操作,从而导致模拟器执行完整启动序列并在关闭时丢失状态。它会替换 -snapshot 选项。

例如:

emulator @Pixel8_API_34 -no-snapshot
-no-snapshot-load

阻止模拟器从快照存储加载 AVD 状态。 执行完全启动。

例如:

emulator @Pixel8_API_34 -no-snapshot-load
-no-snapshot-save

阻止模拟器在退出时将 AVD 状态保存到快照存储,这意味着所有更改都将丢失。

例如:

emulator @Pixel8_API_34 -no-snapshot-save
-no-snapshot-update-time

快照恢复时,不尝试立即更正 AVD 时钟时间。此选项在测试期间非常有用,因为它可以避免突然的时间跳跃。 时间更新仍会大约每 15 秒向 AVD 发送一次。

例如:

emulator @Pixel8_API_34 -no-snapshot-update-time
-no-snapstorage

启动模拟器而不安装文件来存储或加载状态快照,从而强制执行完整启动并停用状态快照功能。此选项会替换 -snapstorage-snapshot 选项。

例如:

emulator @Pixel8_API_34 -no-snapstorage
-no-window

停用模拟器上的图形窗口显示。在没有显示器的服务器上运行模拟器时,此选项很有用。您可以通过 adb 或控制台访问模拟器。例如:

emulator @Pixel8_API_34 -no-window
-partition-size size

指定系统数据分区大小(以 MB 为单位)。例如:

emulator @Pixel8_API_34 -partition-size 1024
-prop name=value

在启动时在模拟器中设置 Android 系统属性。 name 必须是最多 32 个字符的属性名称,标记为 qemu_propvalue 必须是最多 92 个字符的字符串。如需查看示例,请参阅 property_contexts 文件。您可以在一个命令行中指定多个 ‑prop 选项。此选项对调试可能很有用。 例如:

emulator @Pixel8_API_34 -prop qemu.name=value -prop qemu.abc=xyz
-qemu args 将参数传递到 QEMU 模拟器软件。使用此选项时,请确保它是指定的最后一个选项,因为它之后的所有选项都会被解读为特定于 QEMU 的选项。这是高级选项,只应由非常熟悉 QEMU 和 Android 模拟的开发者使用。
-qemu -h

显示 -qemu 帮助。例如:

emulator -qemu -h
-ramdisk filepath

指定 ramdisk 启动映像。指定文件名,以及绝对路径或相对于工作目录的路径。

例如:

emulator @Pixel8_API_34 -ramdisk
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/ramdisk-test.img

如果您不使用此选项,则默认为系统目录中的 ramdisk.img 文件。如需了解详情,请参阅 AVD 系统目录

-report-console socket

在开始模拟之前,将控制台端口报告给远程第三方。它对自动化测试脚本可能很有用。 socket 必须使用以下格式之一:

  • tcp:port[,server][,max=seconds][,ipv6]
  • unix:port[,server][,max=seconds][,ipv6]

如需了解详情,请使用 -help-report-console 选项,如特定选项相关帮助部分中所述。

-shell

在当前终端上创建根 shell 控制台。此选项在以下方面与 adb shell 命令有差异:

  • 它会创建一个根 shell,可允许您修改系统的许多部分。
  • 即使模拟系统中的 adb daemon 无法使用,它也能工作。
  • 按 Ctrl+C(在 macOS 上,按 Command-C)停止模拟器,而不是停止 shell。

例如:

emulator @Pixel8_API_34 -shell
-snapshot name

在快照存储文件中指定快照的名称,以进行自动启动和保存操作。

模拟器可以从早前状态快照继续执行,而不是执行完整启动序列,这通常要快得多。您提供此选项时,模拟器会从快照映像加载该名称的快照,并在退出时以相同的名称进行保存。

如果您不使用此选项,则默认为完整启动序列。如果指定的快照不存在,则模拟器会改为执行完整启动序列,并执行保存操作。

如需了解如何指定快照存储文件和默认文件,请查看 -snapstorage 选项。

emulator @Pixel8_API_34 -snapshot snapshot2

请注意,在加载快照的过程中,系统、用户数据和 SD 卡映像的所有内容都会被快照创建时所拥有的内容覆盖。除非您将此信息保存在其他快照中,否则此后的任何更改都将丢失。

您还可以使用 avd snapshot save name 命令从模拟器控制台创建快照。如需了解详情,请参阅发送模拟器控制台命令

-snapshot-list

显示可用快照的列表。此命令会输出一个快照表,这些快照存储在模拟器启动所用的快照存储文件中,然后退出。如果您同时指定 -snapstorage file,此命令将输出在文件中存储的快照表。

例如:

emulator @Pixel8_API_34 -snapshot-list -snapstorage
   ~/.android/avd/Pixel8_API_34.avd/snapshots-test.img

您可以使用输出中的 ID 和 TAG 列值作为 -snapshot 选项的参数。

-snapstorage filepath

指定包含所有状态快照的代码库文件。执行期间创建的所有快照都保存在此文件中。在模拟器运行期间,只能恢复此文件中的快照。

例如:

emulator @Pixel8_API_34 -snapstorage
   ~/.android/avd/Pixel8_API_34.avd/snapshots-test.img

如果您未指定此选项,则默认为数据目录中的 snapshots.img。如果指定的文件不存在,则模拟器将启动,但不支持保存或加载状态快照。

-sysdir dir

使用绝对路径指定系统目录。如需了解详情,请参阅 AVD 系统目录。 例如:

emulator @Pixel8_API_34 -sysdir
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/test
-system filepath

指定初始系统文件。提供文件名,以及绝对路径或相对于工作目录的路径。

例如:

emulator @Pixel8_API_34 -system
   ~/Library/Android/sdk/system-images/android-34/
   google_apis/x86_64/system-test.img

如果您不使用此选项,则默认为系统目录中的 system.img 文件。如需了解详情,请参阅 AVD 系统目录

-use-system-libs

在 Linux 上,使用系统 libstdc++,而不是与模拟器系统捆绑在一起的版本。仅当模拟器无法正常启动时才使用此选项,但请注意它并非始终有效。或者,将 ANDROID_EMULATOR_USE_SYSTEM_LIBS 环境变量设置为 1。

例如:

me-linux$ emulator @Pixel8_API_34 -use-system-libs
-writable-system

使用此选项在模拟会话期间创建可写系统映像。为此,请执行以下操作:

  1. 使用 -writable-system 选项启动虚拟设备。
  2. 从命令终端输入 adb remount 命令,让模拟器以读/写方式重新装载 system/。默认情况下,模拟器会采用只读方式装载。

使用此标记会创建系统映像的临时副本,该副本可能非常大(数百 MB),但在模拟器退出时将被销毁。

已废弃的选项

以下命令行选项已废弃:

  • -audio-in
  • -audio-out
  • -charmap
  • -code-profile
  • -cpu-delay
  • -dpi-device
  • -dynamic_skin
  • -enable-kvm
  • -gps
  • -image
  • -keyset
  • -help-keys
  • -help-keyset-file
  • -nand-limits
  • -noskin
  • -no-skin
  • -onion
  • -onion-alpha
  • -onion-rotation
  • -radio
  • -ranchu
  • -raw-keys
  • -scale
  • -shared-net-id
  • -shell-serial
  • -skin
  • -skindir
  • -trace
  • -useaudio

获取有关命令行选项的帮助

本部分介绍了如何获取有关命令行选项的帮助。其中提供了有关在启动模拟器时提供的常用模拟器命令行选项的更深入信息。

列出所有模拟器选项

如需输出所有模拟器选项(包括简短说明)的列表,请输入以下命令:

emulator -help

获取有关特定选项的详细帮助

如需输出有关特定启动选项的帮助,请输入以下命令:

emulator -help-option

例如:

emulator -help-netspeed

此帮助比 -help 选项提供的说明更详细。

获取有关所有选项的详细帮助

如需获取有关所有模拟器选项的详细帮助,请输入以下命令:

emulator -help-all

列出模拟器环境变量

如需获取模拟器环境变量的列表,请输入以下命令:

emulator -help-environment

您可以在启动虚拟设备之前在终端窗口中设置环境变量,也可以通过操作系统中的用户设置进行设置。例如,在 Linux 上的 .bashrc 文件中进行设置。

列出调试标记

如需输出 -debug 选项的标记列表,请输入以下命令:

emulator -help-debug-tags

借助 -debug 选项,您可以通过标记指定要启用或停用哪些模拟器组件的调试消息。