Escrcpy 远程设备隧道连接指南:基于 scrcpy Tunnels 的 ADB 与 SSH 组网方案

原创2026-09-22 13:35:391,982 阅读
文章标签:桌面应用移动开发跨平台图形学

Escrcpy 远程设备隧道连接指南:基于 scrcpy Tunnels 的 ADB 与 SSH 组网方案

本文对应仓库文档 docs/en/reference/scrcpy/tunnels.md,讲解如何借助 scrcpy 的隧道(Tunnel)机制,将本机 adb 客户端连到远程 adb server,从而镜像并控制不在同一局域网内的 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,让远程镜像与本地镜像一样顺手。

登录后查看全文
escrcpy