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) 以上版本；若使用電視和 Wear OS，則請確認這類裝置搭載 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：傾印原生的堆積，而非受管的堆積。
dumpbitmaps [options] [-p process] 從 process 傾印點陣圖資訊 (API 級別 36 以上)。

選項如下：

  • -d|--dump [format]：在指定的 format 中轉儲點陣圖內容，可為 png、jpg 或 webp 之一，如果未指定，則預設為 png。系統會使用位圖建立 dumpbitmaps-<time>.zip ZIP 檔案。
  • -p process：從 process 傾印位圖，可指定多個 -p process。
如果未指定 process，系統會轉儲所有程序的位圖。
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：指定安裝程式套件名稱。
  • --user user_id：指定要為哪位使用者安裝套件。根據預設，系統會為裝置上現有的所有使用者安裝套件。
  • --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-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 的 mdnsResponder) 和 Openscreen。

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

Openscreen 後端不需要在電腦上執行 Daemon。從 ADB 35 版開始，macOS 就支援 Openscreen 後端。自 ADB 34 版起，Windows 和 Linux 皆已受支援。

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

adb 連發模式 (自 ADB 36.0.0 起)

連拍模式是實驗性功能，可讓 ADB 持續將封包傳送至裝置，即使裝置尚未回應先前的封包也沒關係。這可大幅提升 ADB 在傳輸大型檔案時的總處理量，並縮短偵錯時的延遲時間。

連拍模式預設為停用。如要啟用這項功能，請執行下列任一操作：

  • 將環境變數 ADB_DELAYED_ACK 設為 1。
  • 在 Android Studio 中，依序前往「File」 (或 macOS 上的「Android Studio」) >「Settings」>「Build, Execution, Deployment」>「Debugger」，然後將「ADB Server Burst Mode」設為「Enabled」。