簡介platform-tools.zip 是面向 Android 開發(fā)與調試人員的官方平臺工具壓縮包專門解決 adb 版本不匹配典型報錯如 server version (31) doesn’t match this client (36)以及 no devices/emulators found 等設備連接問題。壓縮包共包含 22 個文件核心是可執(zhí)行的 adb.exe、fastboot.exe 等工具同時提供 AdbWinApi.dll、AdbWinUsbApi.dll 動態(tài)庫保證 Windows 環(huán)境下的正常調用并附有 systrace.py 等 Python 腳本用于性能追蹤以及少量 HTML/CSS/JS 輔助文檔與配置文件整體僅 1.74MB部署非常輕量。該資源由作者 codehxy 上傳目前已有 2599 人瀏覽學習是 Android 開發(fā)者維護調試環(huán)境的常用選擇。下載后可直接替換或補充本地工具鏈快速消除版本沖突其中 fastboot、sqlite3、dmtracedump 等組件可進一步支持刷機、數(shù)據(jù)庫查看、堆棧分析等任務適合遇到 adb 異常報錯或需要搭建完整調試套件的初中級開發(fā)者。1. 從 platform-tools.zip 認識 adb 與 fastboot一個壓縮包解決設備調試入口platform-tools.zip 這個名字做 Android 調試的人幾乎都見過一個幾十 MB 的壓縮包解壓后是 adb、fastboot 等命令行工具卻能完成裝包、抓日志、刷分區(qū)這些繞不開的操作。很多人第一次下載它是因為不想為一條 adb 命令裝整套開發(fā)環(huán)境或者手頭設備需要進 fastboot 刷機、救磚必須用到這幾個程序。它的定位很純粹不依賴集成開發(fā)環(huán)境解壓即用適合 Android 應用開發(fā)、測試、ROM 維護、三方工具鏈集成以及終端維修場景。下面的內(nèi)容按「裝什么、怎么用、哪里翻車」的順序展開新手能照著跑通熟手可以直接看參數(shù)和邊界。2. 解壓即用platform-tools.zip 的文件構成與最小可運行環(huán)境2.1 核心文件逐個看adb、fastboot、aapt2 的分工解壓 platform-tools.zip 之后先把里面的文件認全。常見構成如下表文件/目錄作用說明adb.exe / adb調試橋客戶端與服務端裝應用、拉日志、shell、傳文件都走它fastboot.exe / fastboot刷機工具在 bootloader 模式寫分區(qū)救磚和系統(tǒng)級寫入靠它aapt2.exe / aapt2APK 信息解析安裝前讀包名、版本號、權限AdbWinApi.dll / AdbWinUsbApi.dlladb 在 Windows 下的運行庫缺失會導致 adb 起不來不要單獨刪lib64/部分架構的動態(tài)庫一般不用管source.properties / NOTICE.txt版本與許可信息排查工具版本時看這里表格里最需要理解的是前三個。adb 是三端結構你敲的命令是客戶端電腦后臺常駐的 adb server 負責轉發(fā)手機里的 adbd 負責執(zhí)行。server 默認監(jiān)聽本機 5037 端口所以當電腦上存在多個 adb 版本時誰先啟動了 server誰就決定了后續(xù)的協(xié)議版本這也是第 5 章版本沖突的根源。fastboot 和 adb 走的是完全不同的通道。它在 bootloader 階段工作此時設備系統(tǒng)還沒起來因此可以寫 boot、recovery、vbmeta 這類底層分區(qū)。日常調試用 adb 就夠刷機、救磚必須在 fastboot 模式完成。兩者的驅動接口也不一樣這是后面「fastboot 認不到設備」的常見原因。aapt2 是 APK 解析器不依賴設備。用它可以在安裝前確認包名、版本號避免裝錯包# 查看 APK 基本信息包名、版本號、權限 aapt2 dump badging app-release.apk | findstr package versionName # macOS/Linux 下把最后的 findstr 換成 grep說明輸出里的 package 行是包名和版本號uses-permission 行是權限列表。三方渠道來的測試包經(jīng)常出現(xiàn)包名對不上、版本高于線上包的情況先 dump badging 再決定裝不裝能省很多溝通成本。2.2 第一次跑通解壓、配環(huán)境變量、驗證最小命令Windows 上最常見的做法是把解壓目錄加進 PATH。很多人直接用setx PATH %PATH%;C:\platform-tools但 setx 有 1024 字符截斷問題原 PATH 很長時會丟掉后半截導致其他命令失效。我習慣用 PowerShell 只改用戶級 PATH# PowerShell把 platform-tools 追加到用戶級 PATH避免 setx 截斷 $tools C:\platform-tools $userPath [Environment]::GetEnvironmentVariable(Path, User) [Environment]::SetEnvironmentVariable(Path, $userPath;$tools, User) # 重開終端后驗證 adb version adb devices -l這段只做追加不覆蓋原變量持久化在注冊表用戶區(qū)不影響系統(tǒng)級 PATH。改完必須重開終端當前會話讀不到新 PATH。不習慣命令行的在「系統(tǒng)屬性 → 高級 → 環(huán)境變量」里編輯 Path 追加同一目錄也一樣。macOS/Linux 下命令名沒有 .exe 后綴解壓后如果提示權限不足先給執(zhí)行權限再配置# macOS/Linux把解壓目錄加入 PATH 并寫入 shell 配置 chmod x $HOME/platform-tools/adb $HOME/platform-tools/fastboot echo export PATH$HOME/platform-tools:$PATH ~/.zshrc source ~/.zshrc adb version用 bash 的話把 .zshrc 換成 .bashrc。不想改 PATH 也完全可以進到解壓目錄里執(zhí)行.\adb或./adb一次性使用足夠。2.3 設備端前置條件開發(fā)者選項與 USB 模式的組合工具就緒后設備端還要開兩個開關。開發(fā)者選項默認隱藏在「設置 → 關于」里連點版本號 7 次左右就會出現(xiàn)。進去打開 USB 調試插線后通知欄會彈 USB 用途選擇務必選「文件傳輸/MTP」。選「僅充電」時很多機型不會暴露 adbd 的調試接口電腦上看到的設備要么 offline要么干脆不出現(xiàn)。Windows 首次插線會自動裝 ADB 接口驅動如果設備管理器里出現(xiàn)黃色感嘆號需要裝廠商提供的 USB 驅動。macOS 和 Linux 一般免驅但部分 Linux 發(fā)行版要配 udev 規(guī)則才能以普通用戶訪問 USB 設備否則會報 no permissions臨時驗證可以用 sudo長期使用建議寫 udev 規(guī)則。手機端彈「允許 USB 調試嗎」時要勾選「始終允許」并確認此時手機處于亮屏解鎖狀態(tài)。鎖屏狀態(tài)下不少機型不會彈窗這也是第 5 章 unauthorized 的常見誘因。3. adb 高頻操作裝包、傳文件、抓日志的實戰(zhàn)命令3.1 設備連接檢查在線狀態(tài)、序列號與異常輸出環(huán)境跑通后的第一件事是確認設備在線adb devices -l # -l 會額外顯示型號、傳輸通道標識多設備管理時很有用輸出分兩列第一列是序列號第二列是狀態(tài)。狀態(tài)為 device 才能執(zhí)行操作emulator-5554 開頭的是模擬器offline 或 unauthorized 分別對應第 5 章的 5.1 和 5.2。多設備同時連接時任何命令都要用-s 序列號指定目標否則 adb 會拒絕執(zhí)行并提示 multiple devices。連接異常時先做低成本的重置動作不動設備數(shù)據(jù)adb kill-server adb start-server這兩條只是重啟電腦端的調試服務。連接狀態(tài)奇怪時先跑一遍很多偶發(fā)問題到這里就結束了。3.2 安裝、卸載與覆蓋安裝的參數(shù)選擇裝包是最高頻的操作參數(shù)選不對會直接報錯adb install -r -d app-debug.apk # 覆蓋安裝并允許降級 adb install -r -t app-test.apk # 覆蓋安裝允許 testOnly 標記 adb install-multiple base.apk split1.apk split2.apk # 分片安裝 adb uninstall com.example.app # 卸載 adb push ./app-debug.apk /sdcard/Download/ adb pull /sdcard/Download/log.txt ./backup/常用參數(shù)的作用如下參數(shù)作用典型場景-r覆蓋安裝升級調試包-d允許版本降級從測試版回退舊版-t允許安裝 testOnly 的 APK跑自動化測試包-g安裝后授予所有運行時權限免手動點權限彈窗-s將應用裝入 SD 卡老設備新設備基本用不上adb install-multiple用于 split APK 場景一個 base 包加若干 split 包必須一起裝單獨 install 會失敗。push/pull 沒有確認提示pull 時同名文件會直接覆蓋批量導出前先在目標目錄看一眼。遇到 INSTALL_FAILED_UPDATE_INCOMPATIBLE通常是已安裝版本簽名不一致此時 -r 無效只能先卸載再裝遇到 INSTALL_FAILED_TEST_ONLY是缺了 -t 參數(shù)。3.3 logcat 抓日志按進程過濾與崩潰緩沖區(qū)抓日志最常踩的坑是日志量太大刷屏所以過濾參數(shù)要熟練adb logcat -v threadtime -s MyTag:V *:S # 只看 MyTag忽略其余輸出 adb logcat -v threadtime --pid 12345 # 按進程過濾pid 用 pidof 拿 adb logcat -b crash # 只看崩潰緩沖區(qū) adb logcat -c # 清空日志后重新抓-v threadtime會帶進程號、線程名和時間戳定位并發(fā)問題時比默認的 brief 格式清晰得多。-s MyTag:V *:S的含義是只放行 MyTag 的任意級別其余全部靜默。--pid適合只想看自己應用的場景pid 可以用adb shell pidof -s 包名拿到。-b crash在不少機型上比全量抓取再 grep 更容易命中崩潰現(xiàn)場。-c清空后立刻復現(xiàn)問題拿到的就是從崩潰前到崩潰后的完整鏈路。Windows 下想要文本過濾直接重定向到文件再搜索adb logcat -v threadtime app.log # 日志量大時終端會丟幀落盤最穩(wěn)3.4 截屏、錄屏與 dumpsys 快速定位定位 UI 問題時截圖和錄屏比口頭描述可靠adb shell screencap -p /sdcard/screen.png adb pull /sdcard/screen.png ./ adb shell screenrecord --bit-rate 4000000 --time-limit 10 /sdcard/demo.mp4 adb shell dumpsys activity activities | findstr mResumedActivity adb shell getprop ro.product.model adb shell dumpsys meminfo com.example.appscreencap 的-p表示輸出 png 格式有些設備不加會得到裸 RGB 數(shù)據(jù)。screenrecord 默認碼率高達 20Mbps錄出來文件巨大壓到 4Mbps 足夠看清操作路徑time-limit 上限 180 秒。dumpsys activity 看當前前臺 Activitygetprop 查型號和系統(tǒng)版本meminfo 看內(nèi)存占用排查內(nèi)存泄漏時配合多次采樣對比。4. fastboot 刷機與分區(qū)寫入從解鎖到刷入的完整邊界4.1 fastboot 模式進入方式與設備識別adb 管的是系統(tǒng)里的應用和數(shù)據(jù)fastboot 管的才是系統(tǒng)本身。進入方式最可靠的是命令觸發(fā)adb reboot bootloader fastboot devices fastboot getvar all按鍵組合進 bootloader 因廠商而異等設備停留在 bootloader 界面后fastboot devices會輸出序列號和 fastboot 狀態(tài)。fastboot getvar all返回 product、security state、current-slot 等關鍵變量刷機前先讀一遍相當于把設備底細摸清。Linux 部分發(fā)行版 fastboot 需要 root 或 udev 規(guī)則表現(xiàn)為一直 waiting for device。4.2 解鎖、分區(qū)寫入與臨時引導的操作fastboot 的核心操作圍繞分區(qū)讀寫常用命令如下fastboot flashing unlock # 解鎖 bootloader會清空數(shù)據(jù) fastboot --slot all flash boot boot.img fastboot flash recovery recovery.img fastboot flash vbmeta vbmeta.img # 動 vbmeta 要格外謹慎 fastboot boot boot.img # 臨時引導不寫入分區(qū) fastboot set_active a # 切換 A/B 槽位 fastboot reboot提示解鎖 bootloader 會清除設備全部數(shù)據(jù)且部分廠商設備解鎖后系統(tǒng)更新鏈路會變化。操作前必須備份并確認這樣做是自己能承擔后果的。--slot all只對 A/B 分區(qū)設備有意義雙槽同時寫入可以避免另一槽版本不匹配只有單槽設備時該參數(shù)會直接報錯。fastboot boot是刷機前的后悔藥先把鏡像臨時引導起來驗證一次確認沒問題再 flash 寫入能避免把壞鏡像固化到分區(qū)里。廠商對 vbmeta 的校驗很嚴格亂刷會導致開機進 warning 或反復重啟遇到驗證失敗先想清楚是否真的需要動它。4.3 版本匹配與刷機失敗時的檢查順序fastboot 的報錯普遍簡短但每條信息都很具體。高頻報錯整理如下fastboot 報錯常見原因處理建議FAILED (remote: not allowed)bootloader 未解鎖先執(zhí)行 flashing unlockFAILED (remote: partition not found)分區(qū)名寫錯或廠商命名不同getvar all 查看實際分區(qū)表FAILED (remote: antirollback check fail)鏡像版本低于設備防回滾基線換同版本或更高版本官方鏡像waiting for device驅動未裝 / 未真正進入 fastboot檢查設備管理器并確認模式刷機失敗的檢查順序我一般這樣走fastboot getvar all確認設備型號、當前槽位、安全狀態(tài)。對照鏡像來源和版本確認防回滾基線是否滿足。確認 bootloader 解鎖狀態(tài)未解鎖時一切 flash 都會被拒。換線、換 USB 2.0 口、重裝 bootloader 驅動。最后才懷疑工具包本身必要時解壓一份新的 platform-tools 覆蓋。這套順序能覆蓋九成以上的刷機失敗。核心原則只有一條fastboot 模式下任何 flash 操作都可能造成不可逆損壞動手前備份數(shù)據(jù)動手時逐條驗證。5. platform-tools 高頻翻車現(xiàn)場5 個常見問題與排查路徑前面的鏈路都正常時問題反而集中在環(huán)境層面。下面 5 條是社區(qū)問答和日常排查里反復出現(xiàn)的真實翻車點。5.1 adb 顯示 offlineUSB 鏈路與 adb server 的排查順序現(xiàn)象adb devices能看到序列號但狀態(tài)一直 offline所有命令超時。原因數(shù)據(jù)線只有充電線芯USB 口供電或信號不穩(wěn)設備端 USB 模式停在僅充電電腦上殘留了舊版 adb server。解決按順序做。先adb kill-server再重插線換一根確認能傳數(shù)據(jù)的數(shù)據(jù)線插主板原生 USB 口而不是擴展塢手機 USB 用途切成文件傳輸還不行就在開發(fā)者選項里關掉 USB 調試再重新打開。玄學的一點是部分擴展塢就是不行換到機箱原生口立刻恢復。5.2 unauthorized 彈窗與 RSA 指紋授權失效現(xiàn)象設備狀態(tài)為 unauthorized所有命令提示需要授權但手機沒有彈窗。原因息屏或鎖屏狀態(tài)下彈窗不顯示之前點過僅充電把彈窗吞了曾經(jīng)勾選過不再提示。解決拔線手機解鎖亮屏進「開發(fā)者選項 → 撤銷 USB 調試授權」重插后在彈窗上勾選「始終允許」。電腦換了系統(tǒng)重裝之后授權需要重新確認一次這是 RSA 指紋機制在正常工作不是故障。5.3 adb server 版本沖突多個 adb 共存時的黑匣子現(xiàn)象敲 adb 命令時報adb server version (xx) doesnt match this client (yy)。原因PATH 里同時存在多個 adb。模擬器、某跨平臺調試工具、舊版平臺包各自帶了一套先被找到的那一個啟動了舊 server后續(xù)客戶端版本對不上。解決Windows 用where adbmacOS/Linux 用which adb找到實際命中的路徑把解壓的 platform-tools 目錄在 PATH 里前移或刪掉其他冗余 adb清掉后臺 server 再重新adb start-server。血淚經(jīng)驗不要在系統(tǒng)目錄里平鋪散裝 exe時間一長自己都分不清哪個在用。5.4 fastboot 認不到設備驅動與 USB 模式的組合問題現(xiàn)象fastboot devices輸出為空但 Windows 設備管理器里出現(xiàn)帶黃色感嘆號的未知設備。原因fastboot 和 adb 走的是兩套驅動接口裝過 adb 驅動不代表 fastboot 驅動可用另有部分機型按鍵進入的不是 bootloader而是 recovery。解決先看屏幕確認是 bootloader 界面安裝廠商的 bootloader 驅動或通用 fastboot 驅動換 USB 2.0 口部分設備要求按住音量鍵再插線。fastboot 模式比 adb 挑剔得多優(yōu)先從驅動層排除再懷疑工具包。5.5 環(huán)境變量路徑被搶占where adb 定位真實可執(zhí)行文件現(xiàn)象明明解壓了 platform-tools新開終端敲 adb 還是提示不是內(nèi)部或外部命令。原因PATH 目錄寫錯、setx 截斷了超長變量或者 PATH 里另一個目錄的舊版 adb 優(yōu)先生效。解決用系統(tǒng)屬性環(huán)境變量 GUI 檢查目錄是否真實存在重開終端where adb看實際解析到哪個路徑把目標目錄前移如果系統(tǒng) PATH 被截斷過在 GUI 里手動補回被丟掉的條目。這類坑和代碼無關但出現(xiàn)頻率最高排查時先看一眼環(huán)境再懷疑代碼能省一晚上。6. 進階用法無線調試與把 adb 寫進批量腳本6.1 無線調試的 pair 流程與連接參數(shù)Android 11 及之后的設備支持無線調試不用插線也能裝包抓日志。首次連接要先配對adb pair 192.168.1.23:37001 # 配對端口和配對碼在無線調試界面里看 adb connect 192.168.1.23:5555 # 調試端口通常固定 5555 adb devices注意 pair 端口是動態(tài)分配的每次開啟無線調試都可能變化而 connect 端口一般固定。兩個端口不一樣經(jīng)常有人把 pair 端口填進 connect 里然后翻車。配對成功后拔線也能用斷開重連只需 connect不需要再 pair。公司網(wǎng)絡開了 AP 隔離時無線調試會一直連不上那是網(wǎng)絡策略問題不是工具問題。6.2 多設備場景下的批量安裝腳本設備多了之后逐臺手敲命令不現(xiàn)實。Windows 下批量安裝當前目錄所有 APKecho off for %%f in (*.apk) do ( echo installing %%f adb install -r %%f )Linux/macOS 下要同時處理多臺設備時需要顯式指定設備序列號# 多設備批量安裝只取狀態(tài)為 device 的設備 for dev in $(adb devices | awk NR1 $2device {print $1}); do echo $dev adb -s $dev install -r app-release.apk adb -s $dev shell getprop ro.build.version.release done-s后面跟設備序列號多設備時不加會直接報錯。awk 的作用是過濾掉 offline 和 unauthorized 的行避免對沒就緒的設備執(zhí)行命令。getprop 的 ro.product.model 是型號ro.build.version.release 是 Android 版本腳本開頭先打印這兩項確認設備沒問題再繼續(xù)安裝。我現(xiàn)在的習慣是新環(huán)境第一件事就是把 platform-tools 解壓到一個固定目錄用where adb確認 PATH 只解析到這一處再把常用命令整理成腳本。這個習慣幫我少踩了很多次版本沖突和認不到設備的坑。希望幫到你。本文還有配套的精品資源點擊獲取