1. 项目缘起为什么要在WSL里折腾ADB最近在折腾一个Android自动化脚本主力开发环境是Windows 11但很多脚本和工具链比如一些Python库、Makefile在纯Windows下跑起来总有些别扭环境配置堪称玄学。于是Windows Subsystem for Linux (WSL) 就成了我的首选——既能享受Linux命令行的高效和生态又无需离开Windows桌面环境。然而当我想用ADBAndroid Debug Bridge连接真机调试时问题来了ADB服务端adb server本质上是一个守护进程它需要直接与USB硬件层通信。在纯粹的Linux或Windows上这都不是问题但在WSL这个“子系统”里它默认是无法直接“看到”和操作宿主Windows的USB设备的。这就形成了一个典型的“混合开发环境”痛点开发环境在WSL调试目标Android设备通过USB连接在Windows上。难道要我在WSL里装一套ADB再在Windows里也装一套然后手动来回切换这显然太不优雅了。经过一番摸索我发现了一条更顺畅的路在WSL中安装ADB客户端但让它连接到运行在Windows宿主上的ADB服务端。这样一来所有命令都在熟悉的WSL终端里执行而底层的USB通信则由Windows端的ADB服务搞定两全其美。这篇文章就记录下这个方案的完整实现过程、背后的原理以及我踩过的几个坑。2. 核心原理理解ADB的客户端-服务端架构与WSL的网络互通在开始动手之前有必要先搞清楚ADB是怎么工作的以及WSL和Windows之间如何通信。这能帮你理解后续每一步操作的意义而不是机械地复制命令。2.1 ADB的C/S架构解析ADB并非一个单一的工具它采用了标准的客户端-服务端Client-Server模型ADB服务端Server这是一个后台守护进程名为adb。它的核心职责是管理所有与Android设备包括通过USB连接的实体机和通过TCP/IP连接的模拟器或网络设备的连接。服务端启动后会绑定到本地的TCP端口默认是5037并监听来自客户端的命令。ADB客户端Client我们平时在命令行里敲的adb devices、adb shell等命令都是客户端。客户端本身不直接与设备对话而是将指令发送给本机的ADB服务端即连接到localhost:5037由服务端去执行具体的设备通信操作。ADB守护进程Daemon即adbd这个进程运行在Android设备内部。当设备通过USB连接或网络启动ADB调试时设备上的adbd会被激活并与主机上的ADB服务端建立连接。关键在于一个系统里通常只需要运行一个ADB服务端实例。多个客户端可以同时连接同一个服务端来管理设备。2.2 WSL1与WSL2的网络模式差异WSL有两个主要版本它们的网络架构不同这直接影响我们的方案WSL1采用了一种翻译层架构与Windows共享同一个网络接口。在WSL1中localhost和 Windows的localhost是直接互通的。也就是说在WSL1里访问127.0.0.1:5037就能直接访问到Windows宿主机上监听在该端口的ADB服务端。这是最简单的情况。WSL2这是一个真正的、轻量化的Linux虚拟机拥有独立的Linux内核和虚拟网络。WSL2中的Linux系统有自己的IP地址比如172.x.x.x与Windows宿主不在同一个网络平面。因此从WSL2内部直接访问127.0.0.1只能访问到WSL2虚拟机自己访问不到Windows宿主。对于WSL2我们需要一种机制让WSL2内的ADB客户端能连接到Windows宿主上的ADB服务端。幸运的是Windows主机为WSL2提供了一个特殊的“出口”host.docker.internal这个主机名在较新版本的WSL2中也支持hostname.local的形式例如YourPcName.local它会解析到Windows宿主机的IP地址。同时我们需要确保Windows防火墙允许来自WSL2子网的入站连接针对ADB的5037端口。我们的方案核心就是确保Windows宿主机上运行着ADB服务端然后在WSL中配置ADB客户端使其指向Windows宿主机的IP和5037端口。3. 环境准备检查与安装必要的组件在开始安装和配置之前我们需要先确认几个基础环境的状态。3.1 确认WSL版本与Linux发行版打开Windows终端PowerShell或CMD运行wsl --list --verbose这会列出已安装的WSL发行版及其版本。记下你的发行版名称例如Ubuntu-22.04和版本VERSION列显示1或2。如果你还没有安装WSL可以通过在管理员权限的PowerShell中运行wsl --install来安装默认的Ubuntu发行版。如果你想安装其他发行版可以先运行wsl --install -d 发行版名。注意网上有些教程会提到修改/etc/wsl.conf来设置网络模式但对于ADB连接这个具体需求我们通常不需要去改动WSL2的默认网络架构而是采用配置客户端连接地址的方式更为清晰和可控。3.2 在Windows宿主机上安装并配置ADB这是整个方案的基石。WSL里的客户端最终要连接到这里安装的服务端。下载ADB平台工具访问 Android开发者官网的“命令行工具”页面 下载适用于Windows的“platform-tools”压缩包。解压并添加到系统PATH将压缩包解压到一个你喜欢的目录例如C:\android\platform-tools。然后将C:\android\platform-tools添加到Windows系统的环境变量PATH中。右键点击“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”部分找到并选中Path点击“编辑”。点击“新建”将上述路径添加进去。点击“确定”保存所有更改。验证Windows端ADB安装打开一个新的Windows PowerShell或CMD窗口输入adb version如果正确显示ADB版本信息说明安装成功。启动ADB服务端并连接设备可选但建议做用USB线连接你的Android设备并在设备上开启“开发者选项”和“USB调试”。在刚才的PowerShell窗口运行adb devices此时设备上可能会弹出“允许USB调试吗”的授权对话框点击“允许”。再次运行adb devices你应该能看到设备列表状态为device。这证明了Windows宿主机的ADB服务端工作正常并且能识别你的设备。至此Windows端的准备工作就完成了。请保持这个PowerShell窗口打开或者至少确保ADB服务端在运行通常adb devices命令会自动启动服务端。你可以通过adb start-server显式启动它。4. 在WSL中安装ADB客户端现在我们切换到WSL环境。启动你的WSL发行版例如Ubuntu。4.1 通过包管理器安装ADB在大多数Linux发行版中ADB被打包为android-tools-adb这个软件包。以Ubuntu/Debian为例# 首先更新软件包列表 sudo apt update # 安装ADB客户端 sudo apt install android-tools-adb -y安装完成后在WSL终端里运行adb version你应该能看到ADB的版本信息。但此时如果你运行adb devices很可能会报错或者显示一个空的设备列表。这是因为WSL中的ADB客户端默认尝试连接localhost:5037即WSL内部的5037端口而那里并没有运行ADB服务端。4.2 关键配置将WSL的ADB客户端指向Windows宿主我们需要告诉WSL里的ADB“别找本地的服务端了去连接另一台机器即Windows宿主上的服务端。” 这通过设置环境变量ADB_SERVER_SOCKET来实现。对于WSL2最常见的情况我们需要找到Windows宿主机的IP地址。如前所述最可靠的方法是使用host.docker.internal。我们可以先测试一下ping host.docker.internal -c 2如果能够ping通并显示一个IP地址通常是192.168.x.x或172.x.x.x那就没问题。接下来在WSL的shell配置文件如~/.bashrc或~/.zshrc取决于你使用的shell末尾添加以下行# 设置ADB客户端连接到Windows宿主机的ADB服务端 export ADB_SERVER_SOCKETtcp:$(host.docker.internal):5037原理说明ADB_SERVER_SOCKET环境变量定义了ADB客户端连接服务端时使用的套接字。格式为tcp:主机名或IP:端口。这里我们使用host.docker.internal这个主机名它由WSL/WSL2自动管理指向宿主机比硬编码IP地址更可靠因为WSL2的虚拟网络IP可能会变。对于WSL1 理论上因为网络共享你可以直接使用localhost。但为了配置的统一性和可移植性尤其是当你可能切换WSL版本时也可以采用同样的配置因为host.docker.internal在WSL1中通常也能解析到127.0.0.1。或者你可以直接设置export ADB_SERVER_SOCKETtcp:localhost:5037添加配置后执行source ~/.bashrc或source ~/.zshrc使配置立即生效。4.3 配置Windows防火墙WSL2必需步骤这是WSL2用户最容易忽略而导致失败的一步。Windows防火墙默认会阻止来自WSL2虚拟网络通常是一个私有子网的入站连接。我们需要为ADB服务端监听在5037端口添加一条防火墙入站规则。以管理员身份打开Windows PowerShell。运行以下命令添加一条允许规则New-NetFirewallRule -DisplayName WSL2 ADB Inbound -Direction Inbound -LocalPort 5037 -Protocol TCP -Action Allow -RemoteAddress $(Get-NetIPConfiguration | Where-Object {$_.IPv4DefaultGateway -ne $null}).InterfaceAlias命令解释-DisplayName “WSL2 ADB Inbound”给规则起个名字。-Direction Inbound入站规则。-LocalPort 5037本地端口号。-Protocol TCP协议类型。-Action Allow允许连接。-RemoteAddress …这一串是为了动态获取WSL2网络接口的别名并只允许来自该接口即WSL2子网的连接比简单的“允许任何”更安全。如果你觉得上述命令复杂也可以暂时采用一种快速但安全性稍低的测试方法暂时完全关闭Windows防火墙不推荐长期使用或者手动在“高级安全Windows Defender 防火墙”中创建一条规则允许任何IP对本地端口5037的TCP入站连接。测试成功后请务必恢复或调整为更精确的规则。5. 测试与验证打通WSL到Windows的ADB连接完成所有配置后让我们进行最终测试。确保Windows端ADB服务端正在运行回到之前那个Windows PowerShell窗口运行adb devices确认服务端已启动并能看到设备。在WSL终端中测试连接首先让WSL终端应用新的环境变量source ~/.bashrc。运行adb devices。理想情况你应该能看到与Windows PowerShell窗口中完全相同的设备列表。这标志着WSL中的ADB客户端已经成功连接到了Windows宿主机的ADB服务端并获取了设备信息。执行一个简单的ADB命令尝试在WSL中执行一个需要与设备交互的命令例如adb shell getprop ro.product.model这条命令会查询设备的型号。如果成功返回你的手机型号那么恭喜你整个链路已经完全打通你现在可以在WSL的终端里使用所有你熟悉的adb、fastboot命令来管理连接在Windows主机上的Android设备了。6. 常见问题排查与实战心得在实际操作中你可能会遇到一些问题。下面是我在配置过程中遇到的一些典型情况及其解决方法。6.1 连接失败cannot connect to daemon at tcp:host.docker.internal:5037这是最常见的错误意味着WSL客户端无法连接到Windows的ADB服务端。请按以下顺序排查确认Windows端服务端状态在Windows PowerShell中运行adb nodaemon server。这个命令会在前台启动ADB服务端并输出日志。观察它是否成功启动并绑定到0.0.0.0:5037或127.0.0.1:5037。如果启动失败可能是5037端口被占用。尝试adb kill-server后再启动。验证网络连通性在WSL终端中运行nc -zv $(host.docker.internal) 5037。这个命令会尝试与Windows宿主机的5037端口建立TCP连接。如果连接失败显示“Connection refused”或超时问题很可能出在Windows防火墙上。请回头仔细检查第4.3节的防火墙规则是否已正确添加并启用。如果host.docker.internal无法解析可以尝试直接使用Windows宿主机的IP地址。在Windows PowerShell中运行ipconfig找到“以太网适配器 vEthernet (WSL)”或类似名称的适配器记下其IPv4地址例如172.24.0.1。然后在WSL的~/.bashrc中将ADB_SERVER_SOCKET设置为tcp:172.24.0.1:5037替换成你的实际IP。检查环境变量在WSL中运行echo $ADB_SERVER_SOCKET确认输出是否正确。确保你source了正确的配置文件并且没有在其他地方如shell会话中覆盖这个变量。6.2 设备列表为空或状态为offline如果在WSL中运行adb devices能看到设备但状态是offline或者设备序列号与Windows端看到的不一致这通常意味着授权问题。重新授权这是最可能的原因。断开USB线重连或者直接在Windows端的PowerShell里运行adb kill-server然后adb devices此时设备上应该会再次弹出授权对话框。务必在Windows主机上进行授权操作因为授权信息adbkey是存储在Windows用户目录下的%USERPROFILE%\.android。一旦在Windows端授权成功WSL端连接同一服务端时就会继承这个授权状态。服务端重启有时服务端状态异常。在Windows端执行adb kill-server后再重新通过adb devices启动服务端。6.3 性能与稳定性考量文件传输通过adb push/pull在WSL文件系统和设备间传输文件时数据流路径是设备 - Windows ADB服务端 - Windows文件系统 - WSL文件系统通过9P协议。对于大文件这可能会比直接在Windows下操作稍慢一些因为多了一次WSL的虚拟文件系统转换。但对于日常的APK安装、日志抓取等操作感知差异不大。保持服务端活跃ADB服务端有时会因为长时间无活动或系统休眠而断开。如果你发现WSL端突然连不上了首先去Windows端运行一下adb devices唤醒服务端。多设备管理当连接多个设备时在WSL中使用adb -s 设备序列号 命令来指定设备这与在纯Linux或Windows下完全一致。6.4 个人实战心得脚本化与自动化为了让这个环境开箱即用我做了两件小事编写连接检查脚本在WSL的~/.bashrc或~/.zshrc里我添加了一个简单的函数function adbwsl() { # 检查ADB_SERVER_SOCKET是否设置如果没有尝试设置默认值 if [ -z ${ADB_SERVER_SOCKET} ]; then export ADB_SERVER_SOCKETtcp:$(host.docker.internal):5037 echo “ADB_SERVER_SOCKET was not set, now set to: ${ADB_SERVER_SOCKET}” fi # 执行adb命令 command adb “$” } # 可以设置别名用 adbwsl 替代 adb或者直接覆盖 adb谨慎 # alias adbadbwsl这样即使在新开的终端里忘记source也能自动初始化连接配置。将Windows平台工具路径加入WSL的PATH备用方案虽然不推荐作为主要方式因为涉及跨系统文件访问性能有损耗但有时为了使用与Windows端完全一致的ADB版本特别是当Linux包管理器里的版本较旧时可以将Windows的platform-tools目录通过/mnt/c/挂载点添加到WSL的PATH中。不过直接运行/mnt/c/android/platform-tools/adb.exe会遇到文件权限和可执行格式问题通常需要配合ADB_SERVER_SOCKET环境变量一起使用且体验不如原生Linux包安装的adb命令流畅。7. 方案总结与延伸思考回顾一下在WSL中使用ADB调试连接在Windows上的Android设备其核心思路是“客户端在WSL服务端在Windows通过TCP/IP连接”。我们通过设置ADB_SERVER_SOCKET环境变量巧妙地绕过了WSL尤其是WSL2无法直接访问USB硬件的限制。这个方案的优势非常明显开发环境统一所有的脚本编写、版本控制、编译构建都可以在WSL的Linux环境中完成无需切换上下文。工具链一致可以使用Linux下丰富的命令行工具grep,awk,jq等来处理ADB的输出构建复杂的自动化流程。配置一次长期受益完成初始配置后日常使用与在原生Linux下几乎没有区别。当然它也有一些前提和局限需要Windows端作为“桥梁”你必须确保Windows主机上的ADB服务端正在运行。防火墙配置WSL2用户需要额外配置Windows防火墙规则这是一个小小的门槛。非USB设备对于想通过Wi-Fi调试的设备你需要在Windows端先用USB线执行adb tcpip 5555等命令开启网络调试端口然后WSL端才能通过adb connect 设备IP:5555来连接。此时连接的是Windows ADB服务端管理下的网络设备链路依然是通的。最后这个模式其实是一种“混合环境”网络互通的典型实践。理解了ADB的C/S架构和WSL的网络特性后你可以将类似的思路应用到其他需要跨Windows/WSL通信的工具上比如某些数据库的客户端/服务端或者自定义的TCP服务。关键在于找准服务监听的端口并正确配置客户端的目标地址和防火墙规则。希望这篇详细的踩坑记录能帮你彻底搞定WSL下的ADB调试环境。