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