Escrcpy 與 scrcpy v3.2 完整指南Android 投屏鏡像、無線控制與源碼級落地【免費下載鏈接】escrcpy優(yōu)雅而強大的跨平臺 Android 設備控制工具基于 Scrcpy 的 Electron 應用,支持無線連接和多設備管理,讓您的電腦成為 Android 的完美伴侶。項目地址: https://gitcode.com/viarotel-org/escrcpy本文以 Escrcpy 倉庫內(nèi)置的 scrcpy v3.2 官方參考文檔docs/en/reference/scrcpy/index.md為骨架展開先系統(tǒng)梳理 scrcpy 的核心能力、前置條件、安裝方式與高頻用法再結(jié)合 Escrcpy 倉庫中真實的中介層源碼scrcpy 進程封裝、參數(shù)生成與偏好模型說明這些命令行能力如何被一個 Electron 桌面應用在工程上落地。讀完本文你將能獨立完成設備連接、參數(shù)調(diào)優(yōu)、無線投屏并理解 GUI 配置項與 scrcpy 命令行參數(shù)之間的映射關(guān)系。scrcpy 是什么scrcpy 的發(fā)音是 screencopy由 Genymobile 團隊開源維護。它可以將通過 USB 或 TCP/IP無線連接的 Android 設備畫面視頻與音頻實時鏡像到電腦并允許你用電腦的鍵盤和鼠標直接控制設備。它具備幾個關(guān)鍵特性據(jù)官方文檔表述無需 root也無需在設備上安裝任何 App——它只是把一段服務端程序臨時推送到設備并執(zhí)行鏡像結(jié)束后設備上不留任何殘留跨平臺支持 Linux、Windows、macOS專注輕量原生實現(xiàn)只顯示設備屏幕沒有多余 UI 負擔性能出色30~120fps取決于設備、清晰度可達 1920×1080 或以上、延遲約 35~70ms、從啟動到顯示第一幀約 1 秒非侵入不在 Android 設備上安裝任何東西純凈無需賬號、無廣告、無需聯(lián)網(wǎng)自由開源免費開源軟件Apache License 2.0。功能全景官方文檔列舉的能力包括音頻轉(zhuǎn)發(fā)Android 11API 30錄制MP4/MKV虛擬顯示在設備屏幕熄滅狀態(tài)下繼續(xù)鏡像雙向復制粘貼可配置的畫面質(zhì)量分辨率、碼率、幀率、編碼器攝像頭鏡像Android 12以虛擬攝像頭V4L2方式對外輸出僅 Linux物理鍵盤與鼠標的 HID 模擬游戲手柄支持OTG 模式不依賴 adb 調(diào)試前置條件與設備準備系統(tǒng)與 API 版本要求Android 設備至少需要API 21Android 5.0音頻轉(zhuǎn)發(fā)要求API 30Android 11使用前請確保已在設備上開啟USB 調(diào)試開發(fā)者選項中。小米等設備的常見報錯部分設備尤其是小米/Xiaomi在注入輸入事件時可能遇到如下錯誤java.lang.SecurityException: Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.解決辦法在開發(fā)者選項中額外開啟USB 調(diào)試安全設置——注意這是與USB 調(diào)試不同的一項。設置完成后必須重啟設備才能用鍵盤和鼠標正?？刂圃O備。OTG 模式的例外在 OTG 模式下運行 scrcpy不需要開啟 USB 調(diào)試它繞過 adb直接通過 USB 以 HID 方式模擬鍵鼠。獲取 scrcpy按官方文檔不同平臺安裝方式分別見LinuxWindows注意閱讀如何運行一節(jié)macOS在 Escrcpy 項目中scrcpy 并不是被直接打包的源碼而是作為外部依賴被調(diào)用。項目在設置中允許用戶指定 scrcpy 的安裝目錄common.scrcpyDir并在偏好重置時支持一鍵清空該路徑見 desktop/src/store/preference/index.js 中的resetDeps。也就是說Escrcpy 通過 shell 直接執(zhí)行系統(tǒng)中的scrcpy可執(zhí)行文件。連接設備USB 與無線 TCP/IP設備選擇規(guī)則如果adb devices只列出了一臺設備scrcpy 會自動選中它多設備時則必須顯式指定有 4 種方式按序列號scrcpy --serial0123456789abcdef scrcpy -s 0123456789abcdef # 短寫法 # 無線連接時序列號即 ip:port與 adb 行為一致 scrcpy --serial192.168.1.1:5555USB 連接的那臺恰好只有一臺時scrcpy --select-usb scrcpy -d # 短寫法TCP/IP 連接的那臺恰好只有一臺時scrcpy --select-tcpip scrcpy -e # 短寫法指定已在 TCP/IP 監(jiān)聽的設備scrcpy --tcpip192.168.1.1:5555 scrcpy --tcpip192.168.1.1 # 默認端口 5555序列號也可以通過環(huán)境變量ANDROID_SERIAL提供adb也讀取該變量# bash export ANDROID_SERIAL0123456789abcdef scrcpy:: cmd set ANDROID_SERIAL0123456789abcdef scrcpy# PowerShell $env:ANDROID_SERIAL 0123456789abcdef scrcpy無線連接自動方式scrcpy 的--tcpip選項可以自動完成無線連接配置有兩種變體設備 adb TCP/IP 模式未開啟或不知道 IP時先用 USB 連接設備然后執(zhí)行scrcpy --tcpip # 不帶參數(shù)它會自動找到設備 IP 與 adb 端口必要時先開啟 TCP/IP 模式再連接設備后啟動。設備已在某端口通常是 5555監(jiān)聽 adb 連接時scrcpy --tcpip192.168.1.1 # 默認端口 5555 scrcpy --tcpip192.168.1.1:5555在地址前加可強制重連scrcpy --tcpip192.168.1.1無線連接手動方式按官方文檔手動流程如下用 USB 將設備連接到電腦讓設備與電腦處于同一 Wi-Fi 網(wǎng)絡獲取設備 IP設置 → 關(guān)于手機 → 狀態(tài)或執(zhí)行adb shell ip route | awk {print $9}開啟 adb TCP/IPadb tcpip 5555拔掉 USB 線連接設備adb connect DEVICE_IP:5555替換為實際 IP正常執(zhí)行scrcpy結(jié)束后執(zhí)行adb disconnect斷開。自 Android 11 起系統(tǒng)的無線調(diào)試選項可以讓你完全繞開物理 USB 連接。自動啟動官方文檔還提到作者的另一小工具 AutoAdb可在新 Android 設備接入時自動執(zhí)行任意命令例如自動拉起 scrcpyautoadb scrcpy -s {}必知技巧Must-know Tips官方文檔給出的高頻技巧降低分辨率可大幅提升性能scrcpy -m1024詳細見 Video 的 Size 一節(jié)_右鍵點擊觸發(fā)BACK中鍵點擊觸發(fā)HOME**鼠標按鍵綁定詳見 MouseAltf切換全屏還有大量其他快捷鍵可用?？旖萱I速查快捷鍵修飾鍵MOD默認為左Alt或左Super即 Windows/Cmd 鍵可通過--shortcut-mod修改可選lctrl、rctrl、lalt、ralt、lsuper、rsuper可組合scrcpy --shortcut-modrctrl # 用右 Ctrl scrcpy --shortcut-modlctrl,lsuper # 左 Ctrl 或左 Super 均可常用快捷鍵摘自 shortcuts.md動作快捷鍵切換全屏MODf顯示左/右旋轉(zhuǎn)MOD←/MOD→水平/垂直翻轉(zhuǎn)MODShift←/→與MODShift↑/↓暫停/繼續(xù)畫面MODz/MODShiftz重置視頻捕獲/編碼MODShiftr窗口 1:1像素級MODg去掉黑邊MODw或雙擊黑邊HOME / BACK / APP_SWITCHMODh/MODb或右鍵/MODs音量 ± / 電源MOD↑/↓/MODp息屏保持鏡像/ 亮屏MODo/MODShifto展開通知/快捷設置面板MODn/MODnn復制/剪切/粘貼到設備MODc/MODx/MODv復制粘貼僅 Android 7開關(guān) FPS 計數(shù)器MODi雙指縮放/旋轉(zhuǎn)Ctrl按住拖動拖入 APK從電腦安裝 APK拖入非 APK 文件推送到設備所有Ctrl按鍵 組合會原樣轉(zhuǎn)發(fā)到設備由設備端應用處理。高頻用法示例官方文檔給出了以下典型示例均可在終端直接復制運行1. H.265 編碼、限 1920 寬、限 60fps、關(guān)音頻、用 UHID 模擬物理鍵盤畫質(zhì)更好scrcpy --video-codech265 --max-size1920 --max-fps60 --no-audio --keyboarduhid scrcpy --video-codech265 -m1920 --max-fps60 --no-audio -K # 短寫法2. 在獨立虛擬顯示上啟動 VLC與設備主屏幕分離scrcpy --new-display1920x1080 --start-apporg.videolan.vlc3. 用 H.265 錄制設備攝像頭1920x1080并采集麥克風到 MP4scrcpy --video-sourcecamera --video-codech265 --camera-size1920x1080 --recordfile.mp44. 把設備前置攝像頭作為電腦的網(wǎng)絡攝像頭輸出Linuxscrcpy --video-sourcecamera --camera-size1920x1080 --camera-facingfront --v4l2-sink/dev/video2 --no-playback5. 不鏡像畫面僅用物理鍵盤鼠標模擬方式控制設備無需 USB 調(diào)試scrcpy --otg6. 用接入電腦的游戲手柄控制設備scrcpy --gamepaduhid scrcpy -G # 短寫法視頻參數(shù)深入以官方 Video 文檔為準圍繞可配置質(zhì)量官方 Video 文檔給出的關(guān)鍵參數(shù)如下供日常調(diào)優(yōu)參考尺寸默認按設備原生分辨率鏡像--max-size1024或-m 1024限制寬高最大值另一維按比例自動計算如 1920×1080 會被縮放為 1024×576。編碼失敗時 scrcpy 會自動降級分辨率重試除非指定--no-downsize-on-error。碼率默認 8 Mbps。scrcpy --video-bit-rate2M等價于--video-bit-rate2000000短寫-b 2M。幀率--max-fps15限制采集幀率--print-fps打印實際采集幀率幀率本質(zhì)上是可變的——只有當屏幕內(nèi)容變化時才產(chǎn)生新幀。編碼器視頻編碼器可選h264默認、h265、av1。H265 畫質(zhì)更好但延遲略高AV1 編碼器在現(xiàn)役 Android 設備上不常見。--list-encoders可列出設備可用編碼器當默認編碼器異常時可手動指定例如scrcpy --video-codech264 --video-encoderOMX.qcom.video.encoder.avc方向三個層級——快捷鍵MODr請求設備切換橫豎屏--capture-orientation改變服務端采集方向影響錄制--orientation在客戶端應用影響顯示與錄制可用快捷鍵動態(tài)調(diào)整。取值支持0/90/180/270及flip0/flip90/flip180/flip270加前綴可鎖定如--capture-orientation90物理旋轉(zhuǎn)設備不會改變畫面方向。裁剪--crop1224:1440:0:0只鏡像屏幕局部寬:高:x:y按設備自然方向取值。多顯示--display-id1選擇鏡像的顯示--list-displays列出所有 display idAndroid 10 以下副屏只能只讀鏡像。緩沖默認零緩沖以追求最低延遲--video-buffer50可加 50ms 緩沖補償抖動--audio-buffer200、--v4l2-buffer300同理可同時疊加。不播放--no-playback僅采集不播放錄制或 V4L2 場景常用也可單獨--no-video-playback/--no-audio-playback--no-video則完全關(guān)閉視頻轉(zhuǎn)發(fā)只保留音頻。用戶文檔全景scrcpy 的完整功能與配置項按主題分布在獨立文檔中均已同步到本倉庫docs/en/reference/scrcpy/目錄以下為全局相對路徑Connection — 設備選擇與無線連接Video — 視頻源、尺寸、碼率、幀率、編碼、方向、裁剪、多顯示、緩沖Audio — 音頻轉(zhuǎn)發(fā)與緩沖Control — 控制消息、復制粘貼、文件推送Keyboard — 鍵盤注入與 HID 物理鍵盤模擬Mouse — 鼠標按鍵綁定與 HID 物理鼠標模擬Gamepad — 游戲手柄Device — 設備相關(guān)操作如息屏鏡像Window — 窗口模式與全屏Recording — 錄制 MP4/MKVVirtual display — 虛擬顯示Tunnels — 連接隧道OTG — OTG 模式Camera — 攝像頭鏡像Video4Linux — V4L2 虛擬攝像頭LinuxShortcuts — 全部快捷鍵其它資源還包括 FAQ鏡像問題排查、構(gòu)建說明開發(fā)者向等。Escrcpy 中的源碼級落地GUI 配置如何變成 scrcpy 參數(shù)Escrcpy 本質(zhì)上是一個把上述命令行能力圖形化、桌面化的 Electron 應用。閱讀其源碼可以清楚看到GUI 配置 → 命令行參數(shù) → scrcpy 進程的完整鏈路。1. 進程封裝createScrcpyProcess在 desktop/electron/middleware/scrcpy/index.js 中所有 scrcpy 調(diào)用都經(jīng)過createScrcpyProcess通過sheller以 shell 方式執(zhí)行scrcpy ${command}字符串支持readyPattern就緒探測默認用正則/Renderer:|Texture:|\[server\]\sINFO:\sDevice:/i匹配 scrcpy 輸出判定鏡像已真正就緒后才 resolve而不是進程一 spawn 就認為成功進程被ProcessManager統(tǒng)一登記應用退出quit-beforeIPC 事件時會統(tǒng)一kill()清理避免殘留進程。2. 各功能場景的參數(shù)拼裝同一文件中每個業(yè)務動作對應一段拼參邏輯與原文檔命令一一對應mirror()--serialserial --window-titletitle并追加來自偏好配置的argsrecord()在鏡像參數(shù)基礎(chǔ)上追加--recordsavePath對應文檔的錄制用法launch()實現(xiàn)虛擬顯示 啟動應用組合——默認追加--new-display可帶分辨率如--new-display1920x1080指定包名時追加--start-apppackageName還處理了--flex-display與橫屏landscape的互斥替換邏輯就緒信號使用/New display:.?\(id(\d)\)/i并解析出虛擬顯示 idhelper()追加--no-window --no-video --no-audio用于執(zhí)行純輔助命令如剪貼板同步、控制類操作對應文檔中無界面模式的思想。3. 輔助信息獲取與解析Escrcpy 還在 UI 中直接復用了 scrcpy 的探測類命令并在 desktop/electron/middleware/scrcpy/helper.js 中編寫了對應的輸出解析器--list-apps→parseScrcpyAppList以*前綴區(qū)分系統(tǒng)應用、-前綴區(qū)分用戶應用解析出應用名與包名--list-encoders→parseScrcpyCodecList解析出video-codec/video-encoder、audio-codec/audio-encoder鍵值對歸類為視頻/音頻編碼器列表--list-displays→parseDisplayIds用/--display-id(\d)/g提取并去重排序所有 display id--list-cameras→parseScrcpyCameras解析每個攝像頭的--camera-id、朝向facing、分辨率、fps 列表與 zoom-range并支持按朝向分辨率fps去重保留變焦范圍更大的。4. 偏好模型圖形化配置項即命令行參數(shù)desktop/src/models/preference/launch/index.js 直接以 scrcpy 參數(shù)名作為字段名建模例如--new-display、--flex-display、--display-ime-policy默認local、--no-vd-destroy-content。其中--new-display的下拉選項內(nèi)置了數(shù)十種真實設備分辨率含 dpi格式寬x高/dpi分為 DesktopHD/FHD/QHD/4K/WXGA…、Mac、Ultrawide、iPad、iPhone、Samsung、Pixel、Surface、Fold 等分組方便用戶一鍵創(chuàng)建符合某臺設備規(guī)格的虛擬顯示。5. 參數(shù)序列化從對象到命令行desktop/src/utils/command/index.js 的stringify()負責把偏好對象轉(zhuǎn)成 scrcpy 命令行駝峰鍵自動轉(zhuǎn) kebab-case如maxSize→--max-size布爾true輸出為裸 flag如--no-audio不帶值false/null/空串直接跳過字符串值含空格或引號時自動加引號并轉(zhuǎn)義數(shù)組值以逗號連接。6. 參數(shù)過濾與追加desktop/src/store/preference/index.js 的scrcpyParameter()是組裝最終參數(shù)的總?cè)肟诎磖ecordKeys/cameraKeys/launchKeys分組在非對應場景如非錄制、非攝像頭下自動剔除相關(guān)參數(shù)過濾掉null/undefined//false值以及黑名單鍵scrcpyExcludeKeys特殊處理--window-y疊加標題欄高度 titleBarHeight開啟--flex-display時刪除--window-width/--window-height支持scrcpyAppend追加自定義參數(shù)行——這相當于給高級用戶留了一條直通 scrcpy 原生命令的后門可以手寫文檔里的任意參數(shù)。這說明原文檔中的所有命令行參數(shù)--max-size、--video-codec、--new-display、--record、--v4l2-sink等在 Escrcpy 中都有對應的圖形化入口或高級自定義通道兩者語義完全一致。開發(fā)者視角客戶端/服務端架構(gòu)與協(xié)議在 develop.md原文檔 Resources 一節(jié)指向的開發(fā)者文檔中scrcpy 被拆成兩部分serverscrcpy-server運行在 Android 設備上的 Java 應用負責屏幕/音頻采集與編碼、輸入事件注入clientscrcpy二進制運行在電腦上的客戶端負責推送并啟動 server、解碼與渲染畫面、捕獲鍵鼠輸入。兩者通過獨立的 socket 分別承載video、audio、controls三種數(shù)據(jù)流任一可禁用但不能全禁因此 socket 數(shù)為 1、2 或 3。值得注意的設計是默認情況下網(wǎng)絡層角色是反轉(zhuǎn)的——客戶端先監(jiān)聽端口server 主動連回來從而避免輪詢競態(tài)除非顯式指定--force-adb-forward。server 的啟動本質(zhì)上是三條命令adb push scrcpy-server /data/local/tmp/scrcpy-server.jar adb forward tcp:27183 localabstract:scrcpy adb shell CLASSPATH/data/local/tmp/scrcpy-server.jar app_process / com.genymobile.scrcpy.Server 2.1第一個參數(shù)是客戶端版本號server 要求與自身完全同版本否則直接失敗協(xié)議無前后兼容。后續(xù)以keyvalue形式攜帶任意數(shù)量的配置項例如scrcpy -m1920 --no-audio實際會展開為adb shell CLASSPATH/data/local/tmp/scrcpy-server.jar app_process / com.genymobile.scrcpy.Server 2.1 scid12345678 log_levelinfo audiofalse max_size1920scid是隨機數(shù)用于同一設備上多個 scrcpy 實例的區(qū)分。服務端還提供raw_streamtrue等獨立模式可把原始 H.264 流直接暴露到 TCP 端口供 VLC 等外部播放器消費。協(xié)議細節(jié)與調(diào)試方法server_debuggertrueadb jdwp Android Studio 遠程調(diào)試均可在 develop.md 中繼續(xù)深入。許可與致謝scrcpy 采用 Apache License 2.0 授權(quán)Copyright (C) 2018 GenymobileCopyright (C) 2018-2025 Romain Vimont。Escrcpy 基于這些開源項目構(gòu)建本文所依據(jù)的官方參考文檔在倉庫中以按原樣提供、定期更新的方式收錄見 docs/en/reference/scrcpy/index.md 開頭的 IMPORTANT 聲明。結(jié)語本文從 scrcpy v3.2 官方參考文檔出發(fā)完整覆蓋了設備前置條件、USB/無線連接、高頻命令、視頻調(diào)優(yōu)參數(shù)與快捷鍵體系并進一步對照 Escrcpy 的源碼展示了這些能力在桌面應用中的工程落地進程封裝、就緒探測、輸出解析、參數(shù)序列化與偏好模型映射。無論是直接使用 scrcpy 命令行還是通過 Escrcpy 的圖形界面管理多臺 Android 設備你都可以把這篇文章當作一份可檢索、可引用的技術(shù)索引?！久赓M下載鏈接】escrcpy優(yōu)雅而強大的跨平臺 Android 設備控制工具基于 Scrcpy 的 Electron 應用,支持無線連接和多設備管理,讓您的電腦成為 Android 的完美伴侶。項目地址: https://gitcode.com/viarotel-org/escrcpy創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考