Android Debug Bridge (adb)

Android Debug Bridge (adb) 是一種多功能的指令列工具，可讓您與裝置通訊。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 範圍中的奇數編號通訊埠，以找出模擬器。在伺服器找到 adb 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」。在 Android 4.2 (API 級別 17) 以������本中，「Developer options」���面會預設為隱藏，如要顯示該畫面，請啟用開發人員選項。

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

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

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

透過 Wi-Fi 連線至裝置

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

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

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

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

  • 確認您的手機搭載 Android 11 (API 級別 30) 以上版本；若使用電視和 WearOS，則請確認裝置搭載 Android 13 (API 級別 33) 以上版本。詳情請參閱「檢查及更新 Android 版本」。

  • 如果您使用 IDE，請確認已安裝最新版的 Android Studio。如要下載，請按這裡。

  • 在工作站上，將 SDK Platform Tools 更新至最新版本。

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

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

  2. 開啟 Android Studio，接著在執行設定選單中選取「Pair Devices Using Wi-Fi」。

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

    畫面上會隨即顯示「Pair devices over Wi-Fi」彈出式視窗，如圖 2 所示。

    透過 Wi-Fi 彈出式視窗顯示配對裝置的螢幕截圖
    圖 2. 提示使用者運用 QR code 或配對碼配對裝置的彈出式視窗

  3. 在裝置上輕觸「無線偵錯」，然後配對裝置：

    顯示無線偵錯系統設定的 Pixel 手機螢幕截圖。
    圖 3Google Pixel 手機上的「Wireless debugging」設定螢幕截圖。

    1. 如要透過 QR code 配對裝置，請選取「Pair device with QR code」，接著掃描圖 2 顯示的「Pair devices over Wi-Fi」彈出式視窗中的 QR code。

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

      PIN 碼範例項目螢幕截圖
      圖 4六位數程式碼輸入範例。

  4. 配對完成後，您可以試試將應用程式部署至裝置。

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

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

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

使用指令列進行 Wi-Fi 連線

另一種方式是，在沒有 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.畫面上會顯示一則您的裝置已成功配對的訊息。

解決無線連線問題

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

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

確認工作站和裝置符合本節開頭列出的必要條件。

檢查其他已知問題

以下列出目前無線偵錯功能 (使用 ADB 或 Android Studio) 的已知問題和解決方法：

  • 無法連上 Wi-Fi：安全的 Wi-Fi 網路 (例如企業 Wi-Fi 網路) 可能會封鎖 P2P 連線，進而導致您無法透過 Wi-Fi 連線。請嘗試使用傳輸線或其他 (非公司) Wi-Fi 網路連線。使用 adb connect ip:port 透過 TCP/IP 進行無線連線 (在初始 USB 連線之後) 是另一個選項，如果可以使用非公司網路，這會是個不錯的選擇。

  • 透過 Wi-Fi 使用 adb 功能有時會自動停止：如果裝置更改 Wi-Fi 網路或中斷網路連線，則可能會發生這個問題。如要解決這個問題，請重新連線至網路。

  • 裝置在配對成功後未連線：adb 會使用 mDNS 來探索並自動連線至已配對的裝置。如果網路或裝置設定不支援 mDNS，或已停用 mDNS，您就必須使用 adb connect ip:port 手動連線至裝置。

在初始 USB 連線後，以無線方式連線至裝置 (僅適用於 Android 10 以下版本)

注意：這項工作流程也適用於 Android 11 (及以上版本)，但請注意，這項流程也涉及透過實體 USB 進行的 *初始* 連線。

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

adb 通常會透過 USB 與裝置通訊，但您也可以透過 Wi-Fi 網路使用 adb。如要連線至搭載 Android 10 (API 級別 29) 以下版本的裝置，請透過 USB 進行以下初始步驟：

  1. 將您的 Android 裝置和 adb 主機電腦連上通用 Wi-Fi 網路。

    2. 注意：請注意，並非所有存取點都適合您；您可能需要使用能正確設定防火牆的存取點，以支援 adb。

  2. 使用 USB 傳輸線將裝置連接至主機電腦。
  3. 設定目標裝置以監聽通訊埠 5555 的 TCP/IP 連線： 
    adb tcpip 5555
  4. 拔除目標裝置的 USB 傳輸線。
  5. 找出 Android 裝置的 IP 位址。舉例來說，您可以在 Nexus 裝置上依序前往「設定」>「關於平板電腦」(或「關於手機」) >「狀態」>「IP 位址」找到 IP 位址。
  6. 依據 IP 位址連線到裝置： 
    adb connect device_ip_address:5555
  7. 確認主機電腦已連線至目標裝置： 
    $ adb devices
List of devices attached
device_ip_address:5555 device

您的裝置現已連線至 adb。

如果與裝置的 adb 連線中斷：

  • 確認主機仍然與 Android 裝置連上相同的 Wi-Fi 網路。
  • 再次執行 adb connect 步驟即可重新連線。
  • 如果問題仍未解決，請重設 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 輸出的內容中顯示出來 (不過模擬器會顯示在桌面上)。如果符合下列所有條件，就會發生這個問題：

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

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

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

停止 adb 伺服器，並依序顯示以下指令。如果是 AVD 名稱，請提供系統中有效的 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 指令時指定目標裝置。如要指定目標，請按照下列步驟操作：

  1. 使用 devices 指令取得目標的序號。
  2. 取得序號後，請使用 -s 選項和 adb 指令來指定序號。
    1. 如要發布許多 adb 指令，您可以將 $ANDROID_SERIAL 環境變數設為包含序號。
    2. 如果您同時使用 -s 和 $ANDROID_SERIAL，-s 會覆寫 $ANDROID_SERIAL。

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

$ adb devices
List of devices attached
emulator-5554 device
emulator-5555 device
0.0.0.0:6520  device

# To install on emulator-5555
$ adb -s emulator-5555 install helloWorld.apk
# To install on 0.0.0.0:6520
$ adb -s 0.0.0.0:6520 install helloWorld.apk

注意：如果有多個可用裝置但尚未指定目標裝置時，adb 就會顯示錯誤「adb: more than one device/emulator」。

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

安裝應用程式

您可以使用 adb 方法在模擬器上安裝 APK，或使用 install 指令在連結的裝置上安裝 APK：

adb install path_to_apk

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

如要安裝多個 APK，請使用 install-multiple。如果您從 Play 管理中心下載應用程式特定裝置的所有 APK，並想在模擬器或實體裝置上安裝這些 APK，這項功能就非常實用。

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

注意：如果您使用的是 Android Studio，則不需要直接使用 adb 在模擬器或裝置上安裝應用程式。而 Android Studio 會為您處理應用程式的封裝和安裝作業。

設定通訊埠轉送

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

adb forward tcp:6100 tcp:7100

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

adb forward tcp:6100 local:logd

如果您想確認將哪些內容傳送到裝置上的特定通訊埠，這個方法就非常實用。系統會將所有收到的資料寫入系統記錄 Daemon，並顯示在裝置記錄中。

將檔案複製到裝置/從裝置複製檔案

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

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

adb pull remote local

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

adb push local remote

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

adb push myfile.txt /sdcard/myfile.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 提供了大多數常見的 Unix 指令列工具。如需可用工具清單，請使用下列指令：

adb shell ls /system/bin

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

如果採用 Android Platform Tools 23 以上版本，adb 會透過與 ssh(1) 指令相同的方式處理引數。這項變更修正了指令插入的許多問題，現在可安全地執行含有殼層中繼字元的指令，例如 adb install Let\'sGo.apk。這項變更代表所有包含殼層中繼字元的指令都能解讀。

舉例來說，adb shell setprop key 'two words' 指令現為錯誤，因為本機殼層會套用引號，且裝置顯示 adb shell setprop key two words。為了讓指令正常運作，請針對本機殼層加上兩次引用兩次，一次用於遠端殼層，就像使用 ssh(1) 一樣。舉例來說，adb shell setprop key "'two words'" 可運作，是因為本機殼層會採用外層引號，而裝置仍會看到內層引號：setprop key 'two words'。您也可以使用轉義，但通常兩次引號會比較簡單。

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

呼叫活動管理員

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

在殼層中，am 語法如下：

am command

您也可以在不輸入遠端殼層的情況下，直接從 adb 發出活動管理員指令。例如：

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

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

指令 說明
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]：提供程序名稱時，請指定憑證的傾印使用者。如未指定，則使用目前使用者。
  • -b [| png | jpg | webp]：從圖形記憶體中轉儲點陣圖 (API 級別 35 以上)。您可以視需要指定要轉儲的格式 (預設為 PNG)。
  • -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 語法如下：

pm command

您也可以在不輸入遠端殼層的情況下，直接從 adb 發出套件管理員指令。例如：

adb shell pm uninstall com.example.MyApp

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

指令 說明
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 所建構，而且您要安裝測試 APK，請務必在 install 指令中加入 -t 選項。
  • -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：移除套件後，保留資料與快取目錄。
  • --user user_id：指定要為哪位使用者移除套件。
  • --versionCode version_code：只有在應用程式具有指定的版本代碼時，才會解除安裝。
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 列印裝置支援的使用者人數上限。
get-app-links [options] [package]

列印指定 package 的網域驗證狀態；如未指定，則列印所有套件的網域驗證狀態。狀態碼定義如下：

  • none：尚未記錄這個網域的資料
  • verified：網域已成功通過驗證
  • approved：強制獲准，通常會使用殼層
  • denied：強制拒絕，通常會使用殼層
  • migrated：已從舊版回應中保留驗證
  • restored：已從還原的使用者資料中保留驗證
  • legacy_failure：遭到舊版驗證器拒絕，原因不明
  • system_configured：由裝置設定自動核准
  • >= 1024：裝置驗證器專屬的自訂錯誤代碼

選項如下：

  • --user user_id：包括使用者選項。包括所有網域，不只是 autoVerify 網域。
reset-app-links [options] [package]

重設指定套件的網域驗證狀態；如未指定，則會重設所有套件的網域驗證狀態。

  • package：要重設的套件；也可指定「all」來重設所有套件

選項如下：

  • --user user_id：包括使用者選項。包括所有網域，不只是 autoVerify 網域。
verify-app-links [--re-verify] [package]

播送指定 package 的驗證要求；如未指定，則會播送所有套件的驗證要求。只有在套件先前未記錄回應時，才會傳送要求。

  • --re-verify：即使套件已記錄回應，仍傳送要求
set-app-links [--package package] state domains

手動設定套件的網域狀態。套件必須將網域宣告為 autoVerify，這項指令才能運作。此指令不會針對無法套用的網域回報失敗。

  • --package package：要設定的套件；也可指定「all」來設定所有套件
  • state：用來設定網域的程式碼，有效值如下：
    • STATE_NO_RESPONSE (0)：���照不曾記錄回應的情況進行重設。
    • STATE_SUCCESS (1)：將網域視為已通過網域驗證代理程式的驗證。請注意，網域驗證代理程式可以覆寫這項設定。
    • STATE_APPROVED (2)：將網域一律視為已核准，防止網域驗證代理程式變更該設定。
    • STATE_DENIED (3)：將網域一律視為已拒絕，防止網域驗證代理程式變更該設定。
  • domains：以空格分隔的清單，當中列有要變更的網域；也可指定「all」來變更所有網域。
set-app-links-user-selection --user user_id [--package package] enabled domains

手動設定套件的主機使用者選取狀態。套件必須宣告網域，這項指令才能運作。此指令不會針對無法套用的網域回報失敗。

  • --user user_id：要變更哪一位使用者的選取狀態
  • --package package：要設定的套件
  • enabled：是否核准網域
  • domains：以空格分隔的清單，當中列有要變更的網域；也可指定「all」來變更所有網域
set-app-links-user-selection --user user_id [--package package] enabled domains

手動設定套件的主機使用者選取狀態。套件必須宣告網域，這項指令才能運作。此指令不會針對無法套用的網域回報失敗。

  • --user user_id：要變更哪一位使用者的選取狀態
  • --package package：要設定的套件
  • enabled：是否核准網域
  • domains：以空格分隔的清單，當中列有要變更的網域；也可指定「all」來變更所有網域
set-app-links-allowed --user user_id [--package package] allowed

切換套件的自動驗證連結處理設定。

  • --user user_id：要變更哪一位使用者的選取狀態
  • --package package：要設定的套件；也可指定「all」來設定所有套件；如未指定任何套件，系統會重設套件
  • allowed：true 表示允許套件開啟自動驗證連結，false 則表示停用這項功能
get-app-link-owners --user user_id [--package package] domains

針對某位使用者，根據由低至高的優先順序列印特定網域的擁有者。

  • --user user_id：要查詢的使用者
  • --package package：可選擇一併列印套件宣告的所有網域，也可指定「all」來列印所有套件
  • domains：以空格分隔的清單，當中列有要查詢的網域

呼叫裝置政策管理員 (dpm)

為了協助您開發及測試裝置管理應用程式，請向裝置政策管理員 (dpm) 工具發出指令。這項工具可讓您控管使用中的管理員應用程式，或變更裝置上的政策狀態資料。

在殼層中，dpm 語法如下：

dpm command

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

adb shell dpm command

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

指令 說明
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 語法如下：

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 鍵停止螢幕錄影。否則，系統將在三分鐘後自動停止錄製，或是設定 --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 的裝置無法使用錄影功能。
  • 部分裝置可能無法以原始顯示解析度錄製影片。如果無法順利錄製螢幕畫面，請嘗試調降螢幕解析度。
  • 無法在錄製期間旋轉畫面。如果螢幕在錄影時旋轉，某些螢幕畫面會在錄製中遭截斷。

表 4. screenrecord 選項

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

注意：您必須具備檔案系統的根目錄存取權 (例如在模擬器上)，才能存取 SQLite 資料庫。

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

ADB USB 後端

ADB 伺服器可以透過兩個後端與 USB 堆疊互動。它可以使用 OS (Windows、Linux 或 macOS) 的原生後端，也可以使用 libusb 後端。部分功能 (例如 attach、detach 和 USB 速度偵測) 僅適用於使用 libusb 後端的情況。

您可以使用 ADB_LIBUSB 環境變數選擇後端。如果未設定，adb 會使用預設後端。預設行為會因作業系統而異。自 ADB 34 版起，系統預設會在所有作業系統上使用 liubusb 後端，但 Windows 會預設使用原生後端。如果已設定 ADB_LIBUSB，則會決定是否使用原生後端或 libusb。如要進一步瞭解 ADB 環境變數，請參閱 adb 手動頁面。

ADB mDNS 後端

ADB 可使用多點傳送 DNS 通訊協定，自動連線至伺服器和裝置。ADB 伺服器隨附兩個後端：Bonjour (Apple 的 mdnsResponseer) 和 Openscreen。

Bonjour 後端需要在主機上執行 Daemon。在 macOS 上，Apple 內建的守護程序一律會執行，但在 Windows 和 Linux 上，使用者必須確保 mdnsd 守護程序已啟用並執行。如果指令 adb mdns check 傳回錯誤，表示 ADB 正在使用 Bonjour 後端，但沒有 Bonjour 守護程序在執行。

Openscreen 後端不需要在電腦上執行 Daemon。自 ADB v35 起，macOS 即可支援 Openscreen 後端。自 ADB v34 起，系統支援 Windows 和 Linux。

根據預設，ADB 會使用 Bonjour 後端。您可以使用 ADB_MDNS_OPENSCREEN 環境變數 (設為 1 或 0) 變更這項行為。詳情請參閱 ADB 手動頁面。