透過指令列啟動模擬器

Android SDK 提供 Android 裝置模擬器,也就是可在電腦上執行的虛擬裝置。Android Emulator 可讓您在不需使用實體裝置的情況下,也能開發及測試 Android 應用程式。

本頁將說明可用於 Android Emulator 的指令列功能。如要進一步瞭解如何使用 Android Emulator UI,請參閱「在 Android Emulator 上執行應用程式」。

啟動模擬器

使用 emulator 指令啟動模擬器,做為執行專案透過 AVD Manager 啟動模擬器的替代方案。

以下是從終端機提示中,啟動虛擬裝置的基本指令列語法:

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 Emulator,只要關閉模擬器視窗即可。

安裝應用程式

除了透過 Android Studio 或模擬器 UI 安裝應用程式,您還可以使用 adb 公用程式,在虛擬裝置上安裝應用程式。

如要使用 adb 安裝、執行及測試應用程式,請按照下列一般步驟操作:

  1. 按照「建構並執行應用程式」中的說明,建構應用程式並封裝為 APK。
  2. 如上一節所述,透過指令列啟動模擬器,並使用任何必要的啟動選項。
  3. 使用 adb 安裝應用程式。
  4. 在模擬器上執行及測試應用程式。
    在模擬器執行期間,您可以使用模擬器主控台,視需要發出指令。

解除安裝應用程式的做法與在 Android 裝置上相同。

虛擬裝置會在重新啟動應用程式時,於使用者資料磁碟分區中保留應用程式,以及其狀態資料 (userdata-qemu.img)。如要清除這項資料,請使用 -wipe-data 選項啟動模擬器,或是抹除 AVD Manager 中的資料。如要進一步瞭解使用者資料分區和其他儲存空間,請參閱下列章節。

注意:adb 公用程式會將虛擬裝置視為實際的實體裝置。因此,您可能必須搭配某些常見的 adb 指令使用 -d 旗標,例如 install-d 旗標可用來指定要使用哪些已連結的裝置做為指令的目標。如未指定 -d,模擬器會鎖定清單中的第一部裝置。

瞭解預設目錄和檔案

模擬器會使用相關的檔案,其中最重要的是 AVD 系統和資料目錄。雖然通常不需要修改預設目錄或檔案,但在指定指令列選項時,建議您先瞭解模擬器目錄結構和檔案。

Android Emulator 採用 (QEMU) 管理程序。

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 預先發布版。但在發布時變成 android-35 指定的 API 級別 35。
  • variant 是系統映像檔執行的對應特定功能的名稱。例如 google_apisandroid-wear
  • arch 是目標 CPU 架構。例如 x86

使用 -sysdir 選項指定用於 AVD 的不同系統目錄。

模擬器會從系統目錄中讀取下列檔案:

表 1. Android Emulator 讀取的系統目錄檔案

檔案 說明 指定不同檔案的選項
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 Manager 或使用 mksdcard 工具建立 SD 卡映像檔。檔案會儲存在開發電腦上,且必須在啟動時載入。

在 AVD Manager 中定義 AVD 時,您可以選擇使用系統自動管理的 SD 卡檔案,或是使用 mksdcard 工具建立的檔案。您可以在 AVD Manager 中查看與 AVD 相關聯的 sdcard.img 檔案。-sdcard 選項會覆寫 AVD 中指定的 SD 卡檔案。請注意,這個 SD 卡選項不適用於搭載 Apple Silicon 的 Mac。

在虛擬裝置執行期間,您可以使用模擬器 UI 或 adb 公用程式,瀏覽、傳送、複製及移除模擬 SD 卡中的檔案。您無法從執行中的虛擬裝置移除模擬的 SD 卡。

如要在載入 SD 卡前將檔案複製到 SD 卡檔案中,請將映像檔掛接為迴圈裝置,然後再複製檔案。或者,使用 mtools 套件等公用程式,將檔案直接複製到映像檔中。

模擬器會將檔案視為位元組集區,因此 SD 卡格式沒有任何影響。

-wipe-data 選項不會影響這個檔案。如要清除這個檔案,請刪除檔案,然後使用 AVD Manager 或 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 Emulator 會持續處於開發階段,目的是不斷提高其穩定性。如要瞭解各種指令列選項相關回報問題的狀態及回報錯誤,請參閱 Android Issue Tracker

常用選項

下表列出經常使用的指令列啟動選項:

表 3. 常用的指令列選項

指令列選項 說明
Quick Boot
-no-snapshot-load 執行冷啟動,並在結束時儲存模擬器狀態。
-no-snapshot-save 盡可能執行 Quick Boot,但不會在結束時儲存模擬器狀態。
-no-snapshot 完全停用 Quick Boot 功能,且不會載入或儲存模擬器狀態。
裝置硬體
-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 Tools 25.2.4 為止,您必須提供 AVD 名稱。

磁碟映像檔和記憶體
-memory size

指定 1536 至 8192 MB 的實體 RAM 大小。舉例來說:

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-server 選項指定不同的 DNS 伺服器清單。

-http-proxy proxy 透過指定的 HTTP/HTTPS Proxy 建立所有 TCP 連線。如果模擬器必須透過 Proxy 伺服器存取網際網路,您可以使用這個選項或 http_proxy 環境變數來設定適當的重新導向。例如:

emulator @Pixel8_API_34 -http-proxy myserver:1981

proxy 可以是下列任一值:

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

http:// 前置字元可以省略。

如未提供此選項,模擬器會查詢 http_proxy 環境變數,並自動採用任何符合 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 值 (以 kbp 為單位) 指定最大網路上傳和下載速度:

  • 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 選項會回報虛擬裝置正在使用的通訊埠和序號,並在您提供的值發生問題時發出警告。在模擬器 UI 中,您可以在視窗標題中看到主控台的通訊埠編號,然後依序選取「Help」 >「About」來查看 adb 通訊埠編號。

請注意,如果 port 值非偶數,且位於 5554 到 5584 的範圍內,而您在模擬器啟動後使用 adb devices 指令啟動 adb server,則虛擬裝置會啟動,但是無法顯示。因此,我們建議您使用偶數的主控台通訊埠編號。

-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 設定模擬器 VM 加速功能。例如:

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 Emulator 的硬體加速功能」一文。

-accel-check 檢查是否已安裝用於模擬器 VM 加速功能的必要管理程序 (HAXM 或 KVM)。例如:

emulator -accel-check

詳情請參閱「檢查是否已安裝管理程序」一文。

-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 系統映像檔時,請停用模擬器 VM 加速功能。這項功能僅適用於偵錯,且效果與指定 -accel off 相同。例如:

emulator @Pixel8_API_34 -no-accel

詳情請參閱「設定 Android Emulator 的硬體加速功能」一文。

-nojni
-no-jni
停用 Android Dalvik 或 ART 執行階段中的擴充 Java Native Interface (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

UI
-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 系統目錄和資料目錄,以及其中所儲存檔案的相關資訊,請參閱預設目錄和檔案相關章節。

其中部分選項適合外部應用程式開發人員使用,部分選項則主要供平台開發人員使用。應用程式開發人員會在特定的 AVD 上建立與執行 Android 應用程式。平台開發人員是在 Android 系統上作業,並於不含任何預建 AVD 的模擬器中執行。

表 4. 進階指令列選項

進階選項 簡短說明
-bootchart timeout

啟用 bootcharting,並以秒為單位設定逾時。部分 Android 系統映像檔中含有經過修改的 init 系統,其中整合了 bootcharting 功能。您可以使用此選項將 bootcharting 逾時期間傳送到系統。如果您的 init 系統未啟用 bootcharting,則這個選項不會有任何作用。此選項主要適用於平台開發人員,而非外部應用程式開發人員。

例如:

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 位元確實執行,對此問題進行偵錯時,就能使用這個選項執行比較。範例如下:

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 必須是標示為 qemu_prop 的屬性名稱 (最多 32 個字元且不含任何空格),而 value 必須是最多 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

在目前的終端機上建立根層級的殼層主控台。與 adb shell 指令的差別在於,這個選項具有以下特性:

  • 此項目會建立一個可讓您修改系統多個部分的根層級殼層,。
  • 即使模擬系統中的 adb daemon 發生中斷情形,還是可以正常運作。
  • 按下 Control + C 鍵 (或在 macOS 為 Command + C) 即可停止模擬器,而非殼層。

例如:

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 選項可讓您依標記指定項目,啟用或停用來自特定模擬器元件的偵錯訊息。