Escrcpy 远程设备隧道连接指南:基于 scrcpy Tunnels 的 ADB 与 SSH 组网方案
Escrcpy 远程设备隧道连接指南:基于 scrcpy Tunnels 的 ADB 与 SSH 组网方案
本文对应仓库文档 docs/en/reference/scrcpy/tunnels.md,讲解如何借助 scrcpy 的隧道(Tunnel)机制,将本机
adb客户端连到远程adbserver,从而镜像并控制不在同一局域网内的 Android 设备。读完本文,你将掌握「远程 ADB server +ADB_SERVER_SOCKET环境变量」和「SSH 隧道加密转发」两套方案的完整命令、关键参数(--tunnel-host、--tunnel-port、--force-adb-forward)及它们在 Escrcpy 中的落地方式。
为什么需要隧道:从局域网镜像到跨网控制
scrcpy 的设计初衷是镜像本地 Android 设备:adb 客户端与 adb server 运行在同一台电脑上,通过 USB 或同一 Wi-Fi 下的 TCP/IP 直连设备。当设备位于远程(例如另一台电脑、另一处网络甚至公网另一端)时,直接运行 scrcpy 无法找到设备。
隧道(Tunnel)解决的核心问题,是让本机的 adb 客户端与一台远程的 adb server 建立连接。只要两端 adb 使用相同版本的 adb 协议,本机 scrcpy 就能像操作本地设备一样,通过远程 adb server 发现并控制挂载在其上的设备。也就是说,隧道传输的不仅是数据,更是「adb 客户端 ⇄ adb server ⇄ Android 设备」整条链路的可达性。
scrcpy 依赖 adb forward 建立隧道:scrcpy 客户端在本地监听一个端口(默认 27183),并通过 adb 将该端口转发到设备的 scrcpy-server 端口,视频流与输入事件都经由这条隧道往返。理解了这一点,就明白为什么远程方案里反复出现 27183、--tunnel-host 与 --tunnel-port。
方案一:远程 ADB server(明文,适合可信网络)
1. 在远程电脑上启动监听所有网卡的 adb server
默认情况下 adb server 只监听 localhost:5037,无法被外部访问。要让本机 scrcpy 连上它,需要先停掉默认 server,再以监听模式显式启动:
adb kill-server
adb -a nodaemon server start
# 保持此终端开启
参数含义:
kill-server:终止当前 adb server 进程(若由其他工具占用端口会先释放);-a(listen on all network interfaces):让 adb server 监听所有网卡而非仅回环地址;nodaemon:以前台方式运行,不转入后台,因此该终端必须保持开启,关闭即断开;server start:显式启动 server。
⚠️ 安全警告:客户端与 adb server 之间的所有通信都是未加密的(对应文档原文 "all communications between clients and the adb server are unencrypted")。镜像画面、输入事件(含可能被注入的按键)、剪贴板内容都会明文经过网络,因此该方案只应在可信内网使用,跨公网请改用下文 SSH 隧道方案。
2. 在本机通过 ADB_SERVER_SOCKET 指向远程 server
假设远程 server 地址为 192.168.1.2,本机分别按三种 Shell 设置环境变量并启动 scrcpy:
# in bash
export ADB_SERVER_SOCKET=tcp:192.168.1.2:5037
scrcpy --tunnel-host=192.168.1.2
:: in cmd
set ADB_SERVER_SOCKET=tcp:192.168.1.2:5037
scrcpy --tunnel-host=192.168.1.2
# in PowerShell
$env:ADB_SERVER_SOCKET = 'tcp:192.168.1.2:5037'
scrcpy --tunnel-host=192.168.1.2
两个关键点:
ADB_SERVER_SOCKET=tcp:<host>:5037:adb 客户端与 adb server 建连的标准协议串。让本机所有 adb 相关操作(包括 scrcpy 内部的 adb forward)都走远程 server;--tunnel-host=192.168.1.2:告诉 scrcpy 建立adb forward隧道时,目标地址是远程主机,从而让本地27183端口经远程 server 转发到远端设备的 scrcpy-server 端口。
3. 调整隧道端口:--tunnel-port
默认情况下,scrcpy 使用本地 adb forward 隧道建立所用的端口(典型值 27183,对应 --port 参数)。在涉及多重转发(例如远程 server 本身还要再转发一层)等复杂场景下,可以显式强制指定不同的隧道端口:
scrcpy --tunnel-port=1234
此时本机 scrcpy 会改用 1234 作为隧道端口,需确保该端口在整条链路(含远程侧防火墙)中畅通。
方案二:SSH 隧道(加密,推荐用于公网/不可信网络)
远程 ADB server 方案不加密,因此跨公网时首选 SSH 隧道。SSH 提供加密通道,且能借助系统已有认证体系(密钥/口令),无需在 adb 协议层再做安全设计。
1. 远程电脑上启动 adb server
只需常规启动(监听本机即可,不需要 -a,因为流量由 SSH 转发):
adb start-server
2. 建立 SSH 隧道
# local 5038 --> remote 5037
# local 27183 <-- remote 27183
ssh -CN -L5038:localhost:5037 -R27183:localhost:27183 your_remote_computer
# keep this open
这条命令同时做了两件事:
-L5038:localhost:5037:本地端口转发。把本机5038端口映射到远程机的localhost:5037,使本机 adb 客户端能经由 SSH 加密通道访问远程 adb server;-R27183:localhost:27183:远程端口转发。把远程机的27183端口映射回本机localhost:27183,使远端设备侧发起的 scrcpy 视频流连接能反向穿过 SSH 隧道回到本机;-C:启用压缩,降低镜像画面的带宽开销;-N:不执行远程命令,纯端口转发。
your_remote_computer 替换为实际 SSH 主机(IP 或 SSH 配置别名)。该终端同样需要保持开启。
3. 在本机连接
# in bash
export ADB_SERVER_SOCKET=tcp:localhost:5038
scrcpy
:: in cmd
set ADB_SERVER_SOCKET=tcp:localhost:5038
scrcpy
# in PowerShell
$env:ADB_SERVER_SOCKET = 'tcp:localhost:5038'
scrcpy
注意这里用的是 localhost:5038(SSH 转发的本地端),且不需要 --tunnel-host:因为远程端口转发已把远程 27183 送回本机,scrcpy 的默认隧道建立逻辑即可工作。
4. 免远程端口转发的替代方案:--force-adb-forward
部分网络环境禁止远程端口转发(-R,需要网关支持且安全性要求更高)。此时可改为全部使用本地端口转发:
# local 5038 --> remote 5037
# local 27183 --> remote 27183
ssh -CN -L5038:localhost:5037 -L27183:localhost:27183 your_remote_computer
# keep this open
区别:第二个 -L 把本机 27183 也直接映射到远程机的 27183,走的是「本地→远程」方向,无需在远程开监听端口。相应地,本机启动 scrcpy 时必须追加 --force-adb-forward,强制 scrcpy 使用正向 adb forward(而不是默认的反向隧道)来建立连接:
# in bash
export ADB_SERVER_SOCKET=tcp:localhost:5038
scrcpy --force-adb-forward
:: in cmd
set ADB_SERVER_SOCKET=tcp:localhost:5038
scrcpy --force-adb-forward
# in PowerShell
$env:ADB_SERVER_SOCKET = 'tcp:localhost:5038'
scrcpy --force-adb-forward
两种 SSH 变体的对照:
| 变体 | SSH 参数 | scrcpy 参数 | 适用场景 |
|---|---|---|---|
| 默认(远程回传) | -L5038:localhost:5037 -R27183:localhost:27183 |
无附加参数 | 远程端口转发可用 |
| 强制正向 | -L5038:localhost:5037 -L27183:localhost:27183 |
--force-adb-forward |
禁止远程端口转发的网络 |
参数速查
| 参数 / 环境变量 | 作用 | 默认值 |
|---|---|---|
ADB_SERVER_SOCKET |
指定 adb 客户端连接的 server 地址,格式 tcp:<host>:<port> |
无(默认 localhost:5037) |
--tunnel-host=<host> |
远程方案中 adb forward 隧道的目标主机 |
无 |
--tunnel-port=<port> |
强制指定隧道端口 | 27183(即 --port 默认值) |
--force-adb-forward |
强制使用正向 adb forward 建立隧道(配合 SSH -L) |
关闭 |
adb -a nodaemon server start |
监听所有网卡、前台运行的远程 adb server | — |
ssh -CN -L… -R… |
加密转发 adb 与 scrcpy 隧道流量 | — |
与 Escrcpy 的关系:隧道参数如何进入实际运行
Escrcpy 是基于 scrcpy 的跨平台 Electron 桌面客户端,它并不自己实现隧道协议,而是把 scrcpy 作为外部进程编排调用,因此本文所有命令在 Escrcpy 中依然成立。理解 Escrcpy 的进程模型,有助于你在界面内组合出远程连接方案:
- scrcpy 进程由命令拼接生成:在 desktop/electron/middleware/scrcpy/index.js 中,
createScrcpyProcess通过sheller(\scrcpy ${command}`)启动进程,镜像命令由createMirrorProcess拼出--serial="..." --window-title="..."前缀(<a href="https://link.gitcode.com/i/d7189e80fa9cfab0685873a3d0216d6e" target="_blank">L112-L120</a>),其余参数(如--tunnel-host)以参数字符串形式并入args`; - 参数对象自动转命令行:Escrcpy 的偏好设置项最终经 desktop/src/utils/command/index.js 的
stringify把对象键值转换为--kebab-case=value形式的 CLI 参数(布尔值为纯开关、数组以逗号连接、含空格的值自动加引号),--tunnel-port这类长参数可直接按{ tunnelPort: 1234 }传入; - adb 子进程同样受环境变量影响:Escrcpy 的 adb 中间件在 desktop/electron/middleware/adb/index.js 中以
sheller(\adb ${command}`)调用 adb 二进制,而其工具链环境变量在 <a href="https://link.gitcode.com/i/8981fe428a7aaff184e5ac9e89c86901" target="_blank">desktop/electron/process/helper.js</a> 的setupToolEnv中统一注入——其中会从偏好设置读取common.environmentVariables(每行KEY=VALUE)写回process.env`; - 环境变量可通过偏好设置注入:由于
setupToolEnv会把用户配置的KEY=VALUE行写入进程环境(desktop/electron/process/helper.js),ADB_SERVER_SOCKET=tcp:192.168.1.2:5037这类隧道环境变量无需在系统级永久设置,直接在 Escrcpy 的「设置 → 通用 → 环境变量」文本域中按行填入即可生效,对应配置项定义见 desktop/src/models/preference/common/index.js; - adb 目录可指定:Escrcpy 支持通过偏好设置覆盖 adb 可执行文件目录(
common.adbDir,见 desktop/src/models/preference/common/index.js),并监听其变化后重建 adb 客户端连接(desktop/electron/middleware/adb/index.js)——若你的远程 adb server 与本地 adb 版本协议不一致,可据此调整本地 adb 版本。
需要特别说明:远程隧道涉及「本机 scrcpy → 远程 adb server → 远程设备」三层链路,Escrcpy 的设备发现、电量读取等周边功能依赖 adb 正常连通;若只做纯镜像,确保方案一或方案二中的 adb 连接成功后,在 Escrcpy 中按常规流程选择设备并镜像即可。
故障排查要点
cannot connect to 192.168.1.2:5037:确认远程adb -a nodaemon server start仍在运行、防火墙放行了5037,且本机ADB_SERVER_SOCKET拼写正确(格式为tcp:host:port);- 镜像窗口黑屏/无法建立视频流:优先检查
27183(或--tunnel-port指定的端口)在远程侧是否可达;SSH 方案中检查-R/-L方向是否与--force-adb-forward匹配; adb server version doesn't match this client:两端 adb 协议版本不一致,按文档要求保证本机与远程 adb 版本一致(在 Escrcpy 中可通过指定adbDir固定版本);- SSH 隧道中断:SSH 会话需要持续保持;网络抖动时可用
ServerAliveInterval等 SSH 保活参数增强稳定性。
总结
隧道是把 scrcpy 从「本地设备镜像」扩展到「远程设备镜像」的桥梁。两条主线:远程 ADB server 方案命令最少但明文传输,仅限可信网络;SSH 隧道方案加密可靠,是跨公网的标准姿势,并通过 --force-adb-forward 提供了免远程端口转发的兼容路径。在 Escrcpy 中,这些参数既可通过 CLI 透传,也可借助「环境变量」偏好设置注入 ADB_SERVER_SOCKET,让远程镜像与本地镜像一样顺手。