Android Debug Bridge (ADB)

Android Debug Bridge (ADB) 是一種多功能的指令列工具,可讓您與裝置通訊。ADB 指令會執行各種裝置動作 (例如安裝應用程式及偵錯應用程式),並且提供 Unix 殼層,可讓您在裝置上執行各種指令。這是一個用戶端伺服器程式,內含三個元件:

  • 用戶端:傳送指令。用戶端會在您的開發機器上執行。您可以發出 ADB 指令,透過指令列終端機叫用用戶端。
  • daemon (adbd) 負責在裝置上執行指令。在每個裝置上,Demem 都會做為背景程序執行。
  • 伺服器:管理用戶端與 Daemon 之間的通訊。伺服器會在開發機器上做為背景程序執行。

adb 已納入 Android SDK Platform-Tools 套件中,您可以下載此套件並使用 SDK Manager,就會將其安裝在 android_sdk/platform-tools/。若您想使用獨立的 Android SDK Platform-Tools 套件,可以前往這裡下載

如要瞭解如何透過 ADB 連結裝置來使用 (包括如何使用 Connection Assistant 排解常見問題),請參閱「在硬體裝置上執行應用程式」。

ADB 的運作方式

當您啟動 ADB 用戶端時,用戶端會先檢查是否有 ADB 伺服器程序已在執行。如果沒有,系統就會啟動伺服器程序。伺服器啟動時,會繫結至本機 TCP 通訊埠 5037,並監聽從 ADB 用戶端傳送的指令;所有 ADB 用戶端都會透過通訊埠 5037 與 ADB 伺服器進行通訊。

伺服器隨後會設定所有運作中裝置的連線。做法是掃描前 16 個模擬器使用的 5555 至 5585 範圍中的奇數編號通訊埠,以找出模擬器。在伺服器找到 ab Daemon (adbd) 時,就會設定該通訊埠的連線。請注意,每個模擬器使用一組序列通訊埠,一個用於主控台連線的雙數編號通訊埠,以及一個用於 ADB 連線的奇數編號通訊埠。例如:

模擬器 1,主控台:5554
模擬器 1,ADB:5555
模擬器 2,主控台:5556
模擬器 2,ADB:5557
依此類推...

如上所示,模擬器連線至 ADB 通訊埠 5555 的模擬器,與主機在通訊埠 5554 上監聽的模擬器相同。

伺服器為所有裝置設定連線後,即可使用 ADB 指令存取這些裝置。伺服器會管理裝置的連線,並處理多個 ADB 用戶端的指令,因此您可以從任何用戶端 (或指令碼) 控制任何裝置。

在裝置上啟用 ADB 偵錯

如要在透過 USB 連線的裝置中使用 ADB,您必須在「Developer options」下的裝置系統設定中啟用「USB debugging」。如要在透過 Wi-Fi 連線的裝置上使用 ADB,請參閱「透過 Wi-Fi 連線至裝置」。

在 Android 4.2 以上版本中,開發人員選項畫面會預設為隱藏。如要將其顯示出來,請依序前往「Settings」>「About phone」,然後輕觸「Build number」七次。返回上一個畫面,然後在底部找到「Developer options」

在某些裝置上,「Developer options」畫面的位置或名稱可能有所不同。

你現在可以使用 USB 連結裝置。您可以在 android_sdk/platform-tools/ 目錄中執行 adb devices,確認裝置已連線。如果成功連線,裝置名稱會顯示為「裝置」。

注意:當您連接搭載 Android 4.2.2 以上版本的裝置時,系統會顯示對話方塊,詢問您是否接受 RSA 金鑰,以允許這部電腦進行偵錯。這個安全性機制會保護使用者裝置,因為除非您能解鎖裝置並確認對話方塊,否則無法執行 USB 偵錯和其他 ADB 指令。

如要進一步瞭解如何透過 USB 連線至裝置,請參閱「在硬體裝置上執行應用程式」。

透過 Wi-Fi 連線至裝置 (Android 11 以上版本)

注意:下方的操作說明不適用於搭載 Android 11 的 Wear 裝置。詳情請參閱「對 Wear OS 應用程式進行偵錯」指南。

Android 11 以上版本支援使用 Android Debug Bridge (adb) 從工作站無線部署應用程式,並進行偵錯。舉例來說,您無須透過 USB 實際連線到裝置,即可將可偵錯的應用程式部署至多個遠端裝置上。這樣就不必處理常見的 USB 連線問題,例如安裝驅動程式。

開始使用無線偵錯功能前,您必須完成下列步驟:

  1. 確認工作站和裝置已連上同一個無線網路。

  2. 確認您的裝置搭載 Android 11 以上版本。詳情請參閱「檢查及更新 Android 版本」。

  3. 確認已安裝 Android Studio Bumblebee。如要下載,請按這裡

  4. 將工作站更新至最新版本的 SDK Platform-Tools

如要使用無線偵錯功能,您必須使用 QR 圖碼或配對碼將裝置與工作站配對。工作站和裝置必須連上同一個無線網路。如要連線至裝置,請按照下列步驟操作:

  1. 在裝置上啟用開發人員選項:

    1. 在裝置上找到「Build number」選項。您可以在這些位置找到下列裝置的這項資訊:

      裝置 設定

      Google Pixel

      「Settings」>「About phone」>「Build number」

      Samsung Galaxy S8 以後的機型

      「Settings」>「About phone」>「Software information」>「Build number」

      LG G6 以後的機型

      「Settings」>「About phone」>「Software info」>「Build number」

      HTC U11 以後的機型

      「Settings」>「About」>「Software information」>「More」>「Build number」或「Settings」>「System」>「About phone」>「Software information」>「More」>「Build number」

      OnePlus 5T 以後的機型

      「Settings」>「About phone」>「Build number」

    2. 輕觸「Build Number」選項七次,直到畫面上顯示 You are now a developer!「This enables developer options on your phone」訊息。

  2. 在裝置上啟用 Wi-Fi 偵錯功能:

    1. 在裝置上找到「Developer options」。您可以在這些位置找到下列裝置的這個選項:

      裝置 設定

      Google Pixel、OnePlus 5T 及更新的機型

      「Settings」>「System」>「Developer options」

      Samsung Galaxy S8 及更新的機型、LG G6 及更新的機型、HTC U11 及更新的機型

      「Settings」>「Developer options」

    2. 在「Developer options」中,向下捲動至「Debugging」區段,然後開啟「Wireless debugging」功能。在「Allow wireless debugging on this network?」彈出式視窗中,選取「Allow」。

  3. 開啟 Android Studio,接著在執行設定的下拉式選單中,選取「Pair Devices Using Wi-Fi」。

    執行設定下拉式選單
    圖 1. 執行設定下拉式選單。

    畫面上會隨即顯示「Pair devices over Wi-Fi」視窗,如下所示。

    透過 Wi-Fi 彈出式視窗顯示配對裝置的螢幕截圖
    圖 2:使用 QR 圖碼或配對碼配對裝置的彈出式視窗
  4. 在裝置上輕觸「Wireless debugging」,然後配對裝置:

    顯示無線偵錯系統設定的 Pixel 手機螢幕截圖。
    圖 3:Google Pixel 手機上的「Wireless debugging」設定螢幕截圖。
    1. 如要透過 QR 圖碼配對裝置,請選取「Pair device with QR code」,接著掃描上方「Pair devices over Wi-Fi」彈出式視窗中的 QR 圖碼。

    2. 如要以配對碼配對裝置,請從上方的「Pair devices over Wi-Fi」中選取「Pair device with pairing code」。在裝置上選取「Pair using pairing code」,並記下六位數的 PIN 碼。當裝置出現在「Pair devices over Wi-Fi」視窗後,您可以選取「Pair」,接著輸入裝置中顯示的六位數 PIN 碼。

      PIN 碼範例項目螢幕截圖
      圖 4. 六位數 PIN 碼輸入範例。
  5. 配對完成後,您可以試試將應用程式部署至裝置。

    如要在工作站上配對其他裝置或移除這部裝置,請前往裝置的「Wireless debugging」功能,接著在「Paired devices」底下輕觸工作站名稱,然後選取「Forget」

  6. 如要快速開啟和關閉無線偵錯功能,您可以使用「Quick settings developer」圖塊進行「無線偵錯」 (位於「Developer Options」>「Quick settings developer」圖塊)。

    Google Pixel 手機「Quick settings developer」圖塊的螢幕截圖。
    圖 5.「Quick settings developer」圖塊設定可讓您快速開啟和關閉無線偵錯功能。

    另一種方式是,在沒有 Android Studio 的情況下,可透過指令列連線至裝置,請按照下列步驟操作:

    1. 按照上述步驟啟用開發人員選項。

    2. 按照上述步驟啟用裝置的「Wireless debugging」功能。

    3. 在您的工作站上,開啟終端機視窗並前往 android_sdk/platform-tools

    4. 選取「Pair device with pairing code」,即可找到您的 IP 位址、通訊埠號碼和配對碼。記下裝置中顯示的 IP 位址、通訊埠號碼和配對碼。

    5. 在工作站的終端機上執行 adb pair ipaddr:port。使用上述的 IP 位址和通訊埠號碼。

    6. 當系統提示時,輸入配對碼,如下所示。

      使用指令列配對的螢幕截圖。
      圖 6.畫面上會顯示一則您的裝置已成功配對的訊息。

解決無線連線問題

如果您無法以無線的方式連接裝置,請嘗試依照下列疑難排解步驟解決問題。

確認工作站和裝置是否符合必要條件

如要符合無線偵錯功能的必要條件,請確認下列項目:

  1. 工作站和裝置已連上同一個無線網路。

  2. 裝置搭載 Android 11 以上版本。詳情請參閱「檢查及更新 Android 版本」。

  3. 裝置已安裝 Android Studio Bumblebee。如要下載,請按這裡

  4. 工作站已安裝最新版 SDK 平台工具

檢查其他已知問題

以下所列為目前 Android Studio 無線偵錯功能已知的問題與解決方法。

  1. 無法連上 Wi-Fi:某些 Wi-Fi 網路(例如企業 Wi-Fi 網路)可能會封鎖 p2p 連線,不允許透過 Wi-Fi 連線。請嘗試透過傳輸線或其他 Wi-Fi 網路。

  2. 透過 Wi-Fi 使用 ADB 功能有時會自動停止:如果裝置更改 Wi-Fi 網路或中斷網路連線,則可能會發生這個問題。

透過 Wi-Fi 連線至裝置 (Android 10 以下版本)

注意:下方的操作說明不適用於搭載 Android 10 以下版本的 Wear 裝置。詳情請參閱「對 Wear OS 應用程式進行偵錯」指南。

ADB 通常會透過 USB 與裝置通訊,但你也可以使用 Wi-Fi 網路。為連線至搭載 Android 10 以下版本的裝置,您必須使用 USB 進行一些初始步驟,如下所述:

  1. 將您的 Android 裝置和 ADB 主機電腦連上通用 Wi-Fi 網路 (兩者皆可存取)。請注意,並非所有存取點都適合你;您可能需要使用能正確設定防火牆的存取點,以支援 ADB。
  2. 如要連線至 Wear OS 裝置,請在與裝置配對的手機上關閉藍牙。
  3. 使用 USB 傳輸線將裝置連接至主機電腦。
  4. 設定目標裝置以監聽通訊埠 5555 的 TCP/IP 連線。
    adb tcpip 5555
    
  5. 拔除目標裝置的 USB 傳輸線。
  6. 找出 Android 裝置的 IP 位址。舉例來說,您可以在 Nexus 裝置上依序前往「Settings」>「About tablet」(或「About phone」)>「Status」>「IP address」。您也可以在 Wear OS 裝置上依序前往「Settings」>「Wi-Fi Settings」>「Advanced」>「IP address」找到 IP 位址
  7. 依據 IP 位址連線到裝置。
    adb connect device_ip_address:5555
    
  8. 確認主機電腦已連線至目標裝置:
    $ adb devices
    List of devices attached
    device_ip_address:5555 device
    

您可以開始使用了!

如果 ADB 連線中斷:

  1. 確認主機仍然與 Android 裝置連上相同的 Wi-Fi 網路。
  2. 再次執行 adb connect 步驟即可重新連線。
  3. 如果這個方法無效,請重設 ADB 主機:
    adb kill-server
    

    從頭開始。

查詢裝置

在發出 ADB 指令前,建議您先瞭解有哪些裝置執行個體已連線至 ADB 伺服器。您可以使用 devices 指令產生附加的裝置清單。

  adb devices -l
  

依回應,ADB 會針對每部裝置列印下列狀態資訊:

  • 序號:由 ADB 建立的字串,可透過通訊埠編號識別裝置。以下是序號範例:emulator-5554
  • 狀態:裝置的連線狀態可能是下列其中一種:
    • offline:裝置未連線至 ADB 或沒有回應。
    • device:裝置現已連線至 ADB 伺服器。請注意,此狀態並不表示 Android 系統已完全啟動且正常運作,因為裝置在系統仍在開機期間就會連線至 ADB。不過,裝置在開機後一般而言,是裝置處於運作的狀態。
    • no device:未連線至任何裝置。
  • 說明:如果您加入 -l 選項,devices 指令會告訴你裝置為何。當你連結多部裝置時,這項資訊非常實用,方便你區分裝置。

以下範例顯示 devices 指令及其輸出內容。有三部裝置在執行中。清單中的前兩行是模擬器,而第三行是連接至電腦的硬體裝置。

$ adb devices
List of devices attached
emulator-5556 device product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64
emulator-5554 device product:sdk_google_phone_x86 model:Android_SDK_built_for_x86 device:generic_x86
0a388e93      device usb:1-1 product:razor model:Nexus_7 device:flo

未列出模擬器

adb devices 指令具有絕對大小寫指令,會讓執行模擬器不會在 adb devices 輸出的內容中顯示出來 (不過模擬器會顯示在桌面上)。如果符合下列所有條件,就會發生這個問題:

  1. ADB 伺服器並未執行,且
  2. 請搭配 -port-ports 選項使用 emulator 指令,並在通訊埠編號介於 5554 與 5584 之間使用奇數編號。此外,
  3. 你選擇的不明編號通訊埠未忙碌,因此指定通訊埠號碼可透過指定通訊埠號碼建立。或者,如果是忙碌,則模擬器會切換至其他符合 2 要求的連接埠;
  4. 模擬器啟動後,啟動了 ADB 伺服器。

如要避免這種情況,其中一種方式是讓模擬器自行選擇通訊埠,且不會同時執行超過 16 個模擬器。或者,在使用 emulator 指令之前一律必須啟動 ADB 伺服器,如下列範例所示。

範例 1:在下方的指令序列中,adb devices 指令會啟動 ADB 伺服器,但不會顯示裝置清單。

停止 ADB 伺服器,並依序顯示以下指令。如果是 AVD 名稱,請提供有效的系統 AVD 名稱。如要取得播映資訊名稱清單,請輸入 emulator -list-avdsemulator 指令位於 android_sdk/tools 目錄中。

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5555
$ adb devices

List of devices attached
* daemon not running. starting it now on port 5037 *
* daemon started successfully *

範例 2:在下方的指令序列中,adb devices 會顯示裝置清單,因為 ADB 伺服器會先啟動。

如要查看adb devices停止 ADB 伺服器,然後在使用完emulator指令,以及使用adb devices指令,如下所示:

$ adb kill-server
$ emulator -avd Nexus_6_API_25 -port 5557
$ adb start-server
$ adb devices

List of devices attached
emulator-5557 device

如要進一步瞭解模擬器指令列選項,請參閱「使用指令列參數」。

將指令傳送到特定裝置

如果多部裝置正在執行,您必須在發出 ADB 指令時指定目標裝置。如要指定目標,請使用 devices 指令取得目標的序號。取得序號後,請使用 -s 選項和 ADB 指令來指定序號。如要發布許多 ADB 指令,您可以將 $ANDROID_SERIAL 環境變數設為包含序號。如果您同時使用 -s$ANDROID_SERIAL-s 會覆寫 $ANDROID_SERIAL

在下列範例中,系統會取得連接的裝置清單,然後利用該裝置的序號安裝helloWorld.apk

$ adb devices
List of devices attached
emulator-5554 device
emulator-5555 device

$ adb -s emulator-5555 install helloWorld.apk

注意:如果有多個可用裝置但尚未發布目標裝置時,ADB 就會產生錯誤。

如果您有多部裝置,但只有一部模擬器,請使用 -e 選項向模擬器傳送指令。而如果有多部裝置,但只連接了一個硬體裝置,請使用 -d 選項將指令傳送至硬體裝置。

安裝應用程式

您可以使用 install 方法,在模擬器或連接的裝置上安裝 APK:

adb install path_to_apk

安裝測試 APK 時,您必須使用 install 指令的 -t 選項。如需詳細資訊,請參閱「-t」。

如要進一步瞭解如何建立可在模擬器/裝置執行個體上安裝的 APK 檔案,請參閱「建構並執行應用程式」。

請注意,如果您使用的是 Android Studio,則不需要直接使用 ADB 將應用程式下載到模擬器/裝置上。而 Android Studio 會為您處理應用程式的封裝和安裝作業。

設定通訊埠轉送

您可以使用 forward 指令設定任意通訊埠轉送功能,將特定主機通訊埠的要求轉送至裝置上的其他通訊埠。以下範例設定主機通訊埠 6100 轉送至裝置通訊埠 7100:

adb forward tcp:6100 tcp:7100

以下範例說明如何將主機通訊埠 6100 轉寄至 local:logd:

adb forward tcp:6100 local:logd

將檔案複製到/複製裝置

使用 pullpush 指令在裝置之間複製檔案,或從裝置複製檔案。與 install 指令不同,後者只是將 APK 檔案複製到特定位置,而 pullpush 指令可讓您將任意目錄和檔案複製到裝置上的任何位置。

如要從裝置複製檔案或目錄及其子目錄,請按照下列步驟操作:

adb pull remote local

如要將檔案或目錄及其子目錄複製到裝置,請按照下列步驟操作:

adb push local remote

localremote 替換成開發機器 (本機) 和裝置上 (遠端) 的目標檔案/目錄的路徑。例如:

adb push foo.txt /sdcard/foo.txt

停止 ADB 伺服器

在某些情況下,您可能需要終止 ADB 伺服器程序並重新啟動,才能解決問題 (例如,ADB 沒有回應指令時)。

如要停止 ADB 伺服器,請使用 adb kill-server 指令。然後,您可以發出任何其他 ADB 指令,將伺服器重新啟動。

發布 ADB 指令

您可以使用開發機器或指令碼中的指令列發出 ADB 指令。使用方式:

adb [-d | -e | -s serial_number] command

如果只有一個執行中的模擬器或僅一部裝置連線,預設傳送 ADB 指令到該裝置。如果同時執行多個模擬器和/或多個裝置,則必須使用 -d-e-s 選項,指定指令的目標裝置。

您可以在下列指令中查看所有支援 ADB 指令的詳細清單:

adb --help

問題殼層指令

您可以使用 shell 指令透過 ADB 發出裝置指令,或是啟動互動式殼層。如要發出單一指令,請使用 shell 指令,例如:

adb [-d |-e | -s serial_number] shell shell_command

如要在裝置上啟動互動式殼層,請使用 shell 指令,如下所示:

adb [-d | -e | -s serial_number] shell

如要結束互動式殼層,請按下 Control + D 鍵或輸入 exit

注意事項:如果採用 Android Platform-Tools 23 以上版本,ADB 會以與 ssh(1) 指令相同的方式處理引數。這項變更修正了指令插入的許多問題,現在可安全地執行含有殼層中繼字元的指令,例如 adb install Let\'sGo.apk。不過,這項變更代表所有包含殼層中繼字元的指令都能解讀,舉例來說,adb shell setprop foo 'a b' 指令現為錯誤,因為本機殼層會套用單引號 ('),且裝置顯示 adb shell setprop foo a b。如要讓指令正常運作,請針對本機殼層加上兩個引號,一次則用於執行遠端殼層,做法和使用 ssh(1) 相同。例如:adb shell setprop foo "'a b'"

Android 提供了大多數常見的 Unix 指令列工具。如需可用工具清單,請使用下列指令:

adb shell ls /system/bin

大多數指令可透過 --help 引數取得說明,許多殼層指令是由 toybox 提供。如要取得所有玩具方塊指令的一般問題,請前往 toybox --help

另請參閱「Logcat 指令列工具」,以便監控系統記錄。

呼叫活動管理員 (am)

在 ADB 殼層中,您可以透過活動管理員 (am) 工具發出指令,以執行各種系統動作,例如啟動活動、停止停止程序、廣播意圖、修改裝置螢幕等設定。在殼層中,語法如下:

am command

您也可以在不輸入遠端殼層的情況下,直接透過 ADB 發出活動管理員指令。例如:

adb shell am start -a android.intent.action.VIEW

表 2. 可用的活動管理員指令

指令 說明
start [options] intent 啟動 intent 指定的 Activity

請參閱「意圖引數規格」。

選項如下:

  • -D:啟用偵錯功能。
  • -W:等待發布作業完成。
  • --start-profiler file:啟動分析器並將結果傳送至 file
  • -P file:類似 --start-profiler,但當應用程式處於閒置狀態時,剖析作業會停止。
  • -R count:重複活動啟動 count 次。在每次重複前,系統都會完成重要活動。
  • -S:在活動開始前強制停止目標應用程式。
  • --opengl-trace:啟用 OpenGL 函式追蹤功能。
  • --user user_id | current:指定執行的使用者;如未指定,則以目前使用者的身分執行。
startservice [options] intent 啟動 intent 指定的 Service

請參閱「意圖引數規格」。

選項如下:

  • --user user_id | current:指定執行的使用者;如未指定,則以目前使用者的身分執行。
force-stop package 強制停止與 package (應用程式套件名稱) 相關聯的所有內容,
kill [options] package 終止與 package (應用程式套件名稱) 相關聯的所有程序。這個指令只會終止可以安全終止,且不會影響使用者體驗的程序。

選項如下:

  • --user user_id | all | current:指定終止程序的使用者;未指定使用者。
kill-all 停止所有背景程序。
broadcast [options] intent 發送廣播意圖。

請參閱「意圖引數規格」。

選項如下:

  • [--user user_id | all | current]:指定要傳送郵件的使用者;如未指定,則傳送給所有使用者。
instrument [options] component 透過 Instrumentation 執行個體開始監控。目標 component 通常是 test_package/runner_class 的形式。

選項如下:

  • -r:列印原始結果 (否則要解碼 report_key_streamresult)。搭配 [-e perf true] 使用,即可產生原始測量結果的原始輸出內容。
  • -e name value:將引數 name 設為 value。測試執行器的常見格式為 -e testrunner_flag value[,value...]
  • -p file:將設定檔資料寫入 file
  • -w:等待檢測作業完成後再傳回。測試執行者為必填欄位。
  • --no-window-animation:在執行期間關閉視窗動畫。
  • --user user_id | current:指定執行使用者檢測的環境 (如未指定,系統會指定目前的使用者)。
profile start process file process 啟動分析器,將結果寫入 file
profile stop process 停止 process 中的分析器。
dumpheap [options] process file 傾印 process 的堆積,寫入 file

選項如下:

  • --user [user_id | current]:提供程序名稱時,請指定憑證的傾印使用者;如未指定,則使用目前使用者。
  • -n:傾印原生的堆積,而非受管的堆積。
set-debug-app [options] package 將應用程式 package 設為偵錯。

選項如下:

  • -w:等待應用程式啟動時啟動偵錯工具。
  • --persistent:保留這個值。
clear-debug-app 清除 set-debug-app 中用於偵錯的套件。
monitor [options] 開始監控當機或 ANR 情形。

選項如下:

  • --gdb:在當機/ANR 時於指定通訊埠啟動 gdbserv。
screen-compat {on | off} package 控制 package螢幕相容性模式。
display-size [reset | widthxheight] 覆寫裝置的顯示大小。這個指令可以在有大螢幕的裝置上模擬小螢幕解析度,反之亦然,藉此針對不同螢幕大小測試應用程式,反之亦然。

範例:
am display-size 1280x800

display-density dpi 覆寫裝置的顯示密度。這個指令可以在低密度螢幕環境的螢幕密度下,測試應用程式是否使用低密度螢幕,反之亦然。

範例:
am display-density 480

to-uri intent 將指定的意圖規格列印為 URI。

請參閱「意圖引數規格」。

to-intent-uri intent 將指定的意圖規格列印為 intent: URI。

請參閱「意圖引數規格」。

意圖引數規格

如果是需要 intent 引數的活動管理員指令,您可以透過以下選項指定意圖:

呼叫檔案包管理員 (pm)

在 ADB 殼層中,您可以使用套件管理員 (pm) 工具發出指令,對裝置上安裝的應用程式套件執行動作及查詢查詢。在殼層中,語法如下:

pm command

您也可以在不輸入遠端殼層的情況下,直接透過 ADB 發出套件管理員指令。例如:

adb shell pm uninstall com.example.MyApp

表 3. 可用的套件管理員指令。

指令 說明
list packages [options] filter 列印所有套件,包括只有套件名稱包含 filter 文字的套件。

選項:

  • -f:查看相關聯的檔案。
  • -d:進行篩選,只顯示停用的套件。
  • -e:進行篩選,只顯示已啟用的套件。
  • -s:進行篩選,只顯示系統套件。
  • -3:進行篩選,僅顯示第三方套件。
  • -i:請查看套件的安裝程式。
  • -u:一併包含已解除安裝的套件。
  • --user user_id:要查詢的使用者空間。
list permission-groups 列印所有已知的權限群組。
list permissions [options] group 列印所有已知的權限,但僅限 group 中的權限。

選項:

  • -g:依群組分類。
  • -f:列印所有資訊。
  • -s:簡短摘要。
  • -d:請列出危險權限。
  • -u:只列出使用者會看到的權限。
list instrumentation [options] 列出所有測試套件。

選項:

  • -f:列出測試套件的 APK 檔案。
  • target_package:只列出這個應用程式的測試套件。
list features 列印系統的所有功能。
list libraries 列印目前裝置支援的所有程式庫。
list users 列印系統的所有使用者。
path package 列印指定 package 的 APK 路徑。
install [options] path 將套件 (由 path 指定) 安裝至系統。

選項:

  • -r:重新安裝現有應用程式,並保留其資料。
  • -t:允許安裝測試 APK。若您僅執行應用程式或進行偵錯,或是使用 Android Studio 「Build」>「Build APK」 指令,Gradle 就會產生測試 APK。如果 APK 是透過開發人員預覽 SDK 建立 (如果 targetSdkVersion 是字母,而不是數字),則您必須加入 -t 選項 (如要安裝測試 APK),請使用 install 指令。
  • -i installer_package_name:指定安裝程式套件名稱。
  • --install-location location:請使用下列其中一個值設定安裝位置:
    • 0:使用預設的安裝位置
    • 1:安裝在內部裝置儲存空間上
    • 2:安裝在外部媒體上
  • -f:在內部系統記憶體上安裝套件。
  • -d:允許降級版本代碼。
  • -g:授予應用程式資訊清單中列出的所有權限。
  • --fastdeploy:只需更新已變更的 APK 部分,即可快速更新已安裝的套件。
  • --incremental:安裝足夠的 APK 並啟動應用程式,同時繼續在背景串流播放剩餘資料。如要使用這項功能,您必須簽署 APK,建立 APK 簽名配置 v4 檔案,然後將這個檔案放在與 APK 相同的目錄中。這項功能僅支援特定裝置。這個選項會強制 ADB 使用此功能,或不支援該功能,但不會顯示詳細原因。請附加 --wait 選項,直到 APK 安裝完成,再授予 APK 存取權。

    --no-incremental 會禁止 ADB 使用這項功能。

uninstall [options] package 從系統中移除套件。

選項:

  • -k:移除套件後,保留資料與快取目錄。
clear package 刪除與套件相關聯的所有資料。
enable package_or_component 啟用指定的套件或元件 (以「套件/類別」寫入)。
disable package_or_component 停用指定的套件或元件 (以「套件/類別」寫入)。
disable-user [options] package_or_component

選項:

  • --user user_id:要停用的使用者。
grant package_name permission 將權限授予應用程式。在搭載 Android 6.0 (API 層級 23) 以上版本的裝置中,該權限可以是應用程式資訊清單中宣告的任何權限。在搭載 Android 5.1 (API 層級 22) 以下版本的裝置上,必須是由應用程式定義的選用權限。
revoke package_name permission 撤銷應用程式的權限。在搭載 Android 6.0 (API 層級 23) 以上版本的裝置中,權限可以是應用程式資訊清單中宣告的任何權限。在搭載 Android 5.1 (API 層級 22) 以下版本的裝置上,必須是由應用程式定義的選用權限。
set-install-location location 變更預設安裝位置。位置值:
  • 0:自動:讓系統判斷最適合的位置。
  • 1:內部:安裝在內部裝置儲存空間上。
  • 2:外部:外部媒體。

注意:這只會用於偵錯;因為這樣會導致應用程式無法運作,以及其他不良行為。

get-install-location 傳回目前的安裝位置。傳回值︰
  • 0 [auto]:讓系統決定最佳位置
  • 1 [internal]:安裝於內部裝置儲存空間
  • 2 [external]:安裝在外部媒體上
set-permission-enforced permission [true | false] 指定是否要強制執行指定權限。
trim-caches desired_free_space 請快取快取檔案以達到指定的免費空間。
create-user user_name 以指定的 user_name 建立新的使用者,列印該使用者的新使用者 ID。
remove-user user_id 移除具備指定 user_id 的使用者,並刪除與該使用者相關聯的所有資料
get-max-users 列印裝置支援的使用者人數上限。

通話裝置政策管理員 (dpm)

為了協助您開發及測試裝置管理 (或其他企業) 應用程式,您可以向裝置政策管理員 (dpm) 工具發出指令。這項工具可讓您控管使用中的管理員應用程式,或變更裝置上的政策狀態資料。在殼層中,語法如下:

dpm command

您也可以在不輸入遠端殼層的情況下,直接從 ADB 發出裝置政策管理員指令:

adb shell dpm command

表 4. 可用的裝置政策管理員指令

指令 說明
set-active-admin [options] component component 設為有效的管理員。

選項如下:

  • --user user_id:指定目標使用者。您也可以傳遞 --user current,選取目前的使用者。
set-profile-owner [options] component component 設為有效的管理員,且其套件設為現有使用者的設定檔擁有者。

選項如下:

  • --user user_id:指定目標使用者。您也可以傳遞 --user current 來選取目前的使用者。
  • --name name:指定使用者可理解的機構名稱。
set-device-owner [options] component component 設為有效的管理員,且其套件設為裝置擁有者。

選項如下:

  • --user user_id:指定目標使用者。您也可以傳遞 --user current,選取目前的使用者。
  • --name name:指定使用者可理解的機構名稱。
remove-active-admin [options] component 停用有效管理員。應用程式必須在資訊清單中宣告 android:testOnly。這個指令也會移除裝置和設定檔擁有者。

選項如下:

  • --user user_id:指定目標使用者。您也可以傳遞 --user current,選取目前的使用者。
clear-freeze-period-record 清除裝置先前設定的系統 OTA 更新凍結記錄。這有助於在開發可管理凍結期的應用程式時,避免裝置的排程限制。請參閱「管理系統更新」。

支援搭載 Android 9.0 (API 層級 28) 以上版本的裝置。

force-network-logs 強制系統準備任何現有的網路記錄供 DPC 擷取。如果有連線或 DNS 記錄,DPC 會收到 onNetworkLogsAvailable() 回呼。請參閱「網路活動記錄」。

這個指令有頻率限制。支援搭載 Android 9.0 (API 層級 28) 以上版本的裝置。

force-security-logs 強制系統向 DPC 提供任何現有的安全性記錄。如果有可用的記錄檔,DPC 會收到 onSecurityLogsAvailable() 回呼。請參閱「記錄企業裝置活動」。

這個指令有頻率限制。支援搭載 Android 9.0 (API 層級 28) 以上版本的裝置。

擷取螢幕畫面

screencap 指令是殼層公用程式,用於擷取裝置螢幕的螢幕截圖。在殼層中,語法如下:

screencap filename

如要透過指令列使用 screencap,請輸入以下內容:

adb shell screencap /sdcard/screen.png

以下是螢幕截圖工作階段範例,使用 ADB 殼層擷取螢幕截圖,並使用 pull 指令從裝置下載檔案:

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

錄製影片

screenrecord 指令是殼層公用程式,用於記錄搭載 Android 4.4 (API 層級 19) 以上版本的裝置螢幕。公用程式會將螢幕活動記錄成 MPEG-4 檔案。您可以使用這個檔案製作宣傳或訓練影片,或進行偵錯和測試。

在殼層中使用下列語法:

screenrecord [options] filename

如要透過指令列使用 screenrecord,請輸入以下內容:

adb shell screenrecord /sdcard/demo.mp4

按下 Control + C 鍵 (Mac 使用者為 Command + C 鍵);如未設定,系統將在三分鐘後自動停止記錄,或是設定 --time-limit 所設定的時間限制。

如要開始錄製裝置螢幕畫面,請執行 screenrecord 指令錄製影片。接著,執行 pull 指令,將影片從裝置下載至主機電腦。以下是錄製工作階段的範例:

$ adb shell
shell@ $ screenrecord --verbose /sdcard/demo.mp4
(press Control + C to stop)
shell@ $ exit
$ adb pull /sdcard/demo.mp4

screenrecord 公用程式可以依照您要求的任何支援解析度和位元率記錄影片,同時保留裝置的螢幕長寬比。根據公用程式會記錄原生顯示解析度和螢幕方向,預設最長可達三分鐘。

screenrecord 公用程式的限制:

  • 影片檔案不會錄製音訊。
  • 搭載 Wear OS 的裝置無法使用錄影功能。
  • 部分裝置可能無法以原始顯示解析度錄製影片。如果無法順利錄製螢幕畫面,請嘗試調降螢幕解析度。
  • 無法在錄製期間旋轉畫面。如果螢幕在錄影時旋轉,某些螢幕畫面會在錄製中遭截斷。

表 5. screenrecord 選項

選項 說明
--help 顯示指令語法和選項
--size widthxheight 設定影片大小:1280x720。預設值為裝置的原始顯示解析度 (如支援),預設值為 1280x720。為達到最佳效果,請使用裝置進階視訊編碼 (AVC) 編碼器支援的尺寸。
--bit-rate rate 設定影片的影片位元率 (以百萬位元/秒為單位)。預設值為 4Mbps。如要提高視訊品質,你可以提高位元率,但產生較大的電影檔案。以下範例將錄音位元率設為 6Mbps:

screenrecord --bit-rate 6000000 /sdcard/demo.mp4
--time-limit time 設定時間上限 (以秒為單位)。預設值為 180 (3 分鐘)。
--rotate 將輸出旋轉 90 度。這個功能是實驗性質。
--verbose 在指令列畫面上顯示記錄資訊。如未設定這個選項,公用程式不會在執行過程中顯示任何資訊。

讀取應用程式的 ART 設定檔

從 Android 7.0 (API 層級 24) 開始,Android 執行階段 (ART) 會針對已安裝的應用程式收集執行設定檔,藉此改善應用程式效能。建議您檢查收集到的設定檔,瞭解系統頻繁執行哪些方法,以及應用程式啟動時採用的類別。

如要產生設定檔資訊的文字格式,請使用下列指令:

adb shell cmd package dump-profiles package

如要擷取產生的檔案,請使用:

adb pull /data/misc/profman/package.txt

重設測試裝置

在多個測試裝置上測試應用程式時,建議您在測試期間重設裝置,例如移除使用者資料並重設測試環境。您可以使用 testharness adb 殼層指令(如下所示)將搭載 Android 10 (API 層級 29) 以上版本的測試裝置恢復原廠設定。

adb shell cmd testharness enable

使用 testharness 還原裝置時,裝置會自動備份 RSA 金鑰,讓金鑰永久傳輸至永久位置中的工作站。也就是說,裝置重設完畢後,工作站就可以繼續偵錯及發出 ADB 指令,而不必手動註冊新的金鑰。

此外,為了簡化應用程式測試程序,請使用 testharness 還原裝置,並變更下列裝置設定:

  • 裝置已完成特定系統設定,因此不會顯示初始裝置的設定精靈。也就是說,裝置會進入可快速安裝、偵錯及測試應用程式的狀態。
  • 設定︰
    • 停用螢幕鎖定功能
    • 停用緊急警報
    • 停用帳戶的自動同步功能
    • 停用系統更新
  • 其他:
    • 停用預先安裝的安全性應用程式

如果應用程式需要偵測及調整 testharness 指令的預設設定,您可以使用 ActivityManager.isRunningInUserTestHarness()

SQLite

sqlite3 會啟動 SQLite 指令列工具來檢查 SQLite 資料庫。包含 .dump 等指令可用來列印資料表的內容,.schema 則可用來列印現有資料表的 SQL CREATE 陳述式。您也可以透過指令列執行 SQLite 指令,如下所示。

$ adb -s emulator-5554 shell
$ sqlite3 /data/data/com.example.app/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions

詳情請參閱「sqlite3 指令列說明文件」。