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-avds。emulator 指令位於 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

將檔案複製到/複製裝置

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

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

adb pull remote local

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

adb push local remote

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

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 指令列說明文件」。