WSABuilds 故障排查：修复 WSA 的 “Target machine actively refused it (10061)“ ADB 连接错误-平芜编程栈

WSABuilds 故障排查：修复 WSA 的 "Target machine actively refused it (10061)" ADB 连接错误

【免费下载链接】WSABuildsRun Windows Subsystem For Android on your Windows 10 and Windows 11 PC using prebuilt binaries with Google Play Store (MindTheGapps) and/or Magisk or KernelSU (root solutions) built in.项目地址: https://gitcode.com/GitHub_Trending/ws/WSABuilds

导读

本文是 WSABuilds 项目 Post-Install Issues 故障排查系列的核心篇章，专门解决使用 WSA（Windows Subsystem for Android）过程中最常见的连接类报错：No connection could be made because the target machine actively refused it (10061)。该错误会阻断 ADB 调试、WSA-Sideloader、WSAPacman 等一切基于 ADB 的 APK 侧载操作。读完本文，你将理解该错误的根因（Hyper-V 无法为 WSA 的 ADB 端口 58526 保留专属范围），并掌握一套由浅入深、可复现的修复流程，包括重启恢复、禁用/启用 Hyper-V、使用netsh手动排除端口范围等完整命令。

1. 错误全景：报错信息与适用场景

1.1 典型报错文本

当 Hyper-V 无法正确预留 WSA 的 ADB 端口时，ADB 客户端会返回如下错误（本文档原文即以此为核心）：

cannot connect to ||127.0.0.1:58526:|| No connection could be made because the target machine actively refused it. (10061)

127.0.0.1:58526：WSA 在 Windows 宿主机上暴露 ADB 服务的默认回环地址与端口。
(10061)：Windows Socket 错误码（WSAECONNREFUSED），表示连接请求被目标主机关闭，即目标端口上没有任何服务在监听。

1.2 哪些操作会触发该错误

该错误并非 WSABuilds 特有的构建缺陷，而是微软 WSA 子系统自身的已知问题（对应 microsoft/WSA issue #136）。以下三类场景最容易触发：

场景	说明
WSA-Sideloader 安装 APK	侧载工具内部通过 ADB 连接 WSA，连接失败即报 10061。相关使用说明见 WSA-Sideloader 使用指南
WSAPacman 安装 APK	同样依赖 ADB 通道，报错时"Install"按钮会灰掉或直接提示连接失败，详见 WSAPacman 指南
手动执行 ADB 命令	使用 Android SDK Platform Tools 中的`adb.exe`执行`adb connect 127.0.0.1:58526`时失败

1.3 相关文档中的交叉引用

该问题在仓库多处文档中均有呼应，属于高频问题，可以从以下入口对照查看：

FAQ：I cannot adb connect localhost:58526：官方 FAQ 给出的快速建议——确认开发者模式已开启；若仍失败，打开 WSA 设置 → Developer 页面查看实际 IP 地址，改用adb connect ip:5555连接。
ADB-Sideloading 指南：标准的adb pair/adb connect侧载流程。
WSA-Sideloader 使用指南：其 Troubleshooting 小节明确指出：若出现No connection could be made because the target machine actively refused it，请参照本文档解决。

2. 根因分析：Hyper-V 与端口 58526 的冲突

2.1 WSA 依赖 Hyper-V 运行

WSA 本质上是运行在 Windows Hypervisor 平台之上的一台 Android 虚拟机。WSABuilds 的安装脚本正是基于这一事实：

MagiskOnWSA/installer/Install.ps1 会检测VirtualMachinePlatform可选功能，未启用时自动执行Enable-WindowsOptionalFeature -Online -NoRestart -FeatureName 'VirtualMachinePlatform'；
MagiskOnWSA/installer/x64/Install.ps1 与 arm64 版本包含相同的逻辑；
MagiskOnWSA/installer/Run.bat 负责在安装前辅助开启虚拟化支持，重启后再运行Install.ps1完成安装。

因此，Hyper-V 相关的网络栈行为会直接决定 WSA 的 ADB 端口是否可用。

2.2 端口冲突的本质

Windows 的 Hyper-V 服务在启动时会动态保留一段 TCP 端口范围（Excluded Port Ranges）供其 NAT/WinNAT 机制使用。在某些系统状态下，这段保留范围会覆盖 WSA 默认的 ADB 端口 58526，导致子系统内的 ADB 服务无法在该端口监听，宿主机一侧的adb connect自然得到"actively refused"。

从源码结构看，这属于子系统与 Windows 网络栈的运行时冲突，WSABuilds 构建包本身无法静态规避，只能通过本文提供的运行期修复手段解决。

3. 修复方案：由浅入深的完整步骤

前置准备：以下命令需要管理员权限运行。在开始菜单搜索 PowerShell / CMD，右键选择"以管理员身份运行"。

3.1 第一步：先做最简单的尝试——重启电脑

由于这是 WSA 子系统自身的 bug，重启电脑通常即可恢复Hyper-V 的动态端口保留行为，使 58526 端口重新可用。这是零成本、最先应该尝试的步骤。

3.2 第二步：关闭 WSA 并禁用其开机自启

若重启后仍报错，继续执行本方案。先确保修复期间 WSA 处于完全关闭状态，避免端口被占用或系统重新保留：

关闭 Windows Subsystem for Android（可从开始菜单退出，或通过设置中的关闭按钮）。
打开任务管理器 →启动应用（Startup Apps）标签页。
找到 WSA 相关项并禁用自启动，防止它在后续重启时抢先占用端口。

3.3 第三步：禁用 Hyper-V

以管理员身份打开 PowerShell，执行：

dism.exe /Online /Disable-Feature:Microsoft-Hyper-V

该命令会关闭 Hyper-V 功能。执行后重启电脑，让系统的网络栈以非 Hyper-V 状态重新初始化。

3.4 第四步：使用 netsh 排除端口范围，锁定 58526

重启完成后，以管理员身份打开 CMD，执行：

netsh int ipv4 add excludedportrange protocol=tcp startport=58526 numberofports=1

参数说明：

参数	含义	本例取值
`protocol`	协议类型	`tcp`（ADB over TCP）
`startport`	排除范围的起始端口	`58526`（WSA 默认 ADB 端口）
`numberofports`	排除的连续端口数量	`1`（仅排除单个端口）

这样就把 58526 端口"钉死"在排除列表之外——即便 Hyper-V 之后再次启动，也不会再动态保留该端口，从根源上防止冲突复现。

3.5 第五步：重新启用 Hyper-V 并重启

如果之前系统本来就启用了 Hyper-V（本修复方案的第三/四步只是为了重置端口保留状态），需要将其恢复，否则 WSA 无法运行：

dism.exe /Online /Enable-Feature:Microsoft-Hyper-V /All

注意：/All开关会连同 Hyper-V 管理工具等子功能一并启用。如果之前从未启用过 Hyper-V（例如仅依赖 VirtualMachinePlatform），可跳过本步骤，保持现状即可。

执行完成后再次重启电脑，然后重新打开 WSA 与开发者模式，使用 ADB 或侧载工具验证连接。

4. 验证修复效果

4.1 用 ADB 验证连接

修复后按 ADB-Sideloading 指南的标准流程验证：

启动 WSA，进入Advanced Settings → Developer mode，开启开发者模式。
查看开发者模式页面显示的IP 地址与端口。
使用无线调试配对（新版平台工具）：
```
adb pair 127.0.0.1:58526
```
连接设备：
```
adb connect 127.0.0.1:58526
```
确认设备在线：
```
adb devices
```

若上述命令不再报 10061，说明端口已恢复正常。需要说明的是，adb pair仅在新版 Android/WSA 的无线调试配对流程中需要；旧版本直接adb connect即可。

4.2 替代验证：检查端口状态

还可以在管理员 CMD 中确认 58526 是否已排除 Hyper-V 保留：

netsh int ipv4 show excludedportrange protocol=tcp

在输出中检查是否存在以 58526 开头的排除段。如果列表中的排除范围与 58526 重叠，说明 Hyper-V 仍在保留该端口，需要复查第三至第五步是否完整执行。

4.3 备选方案：改用 WSA 动态 IP 连接

如果上述完整修复流程仍无法奏效，可以绕过固定端口：打开 WSA 设置 → Developer 页面，查看 WSA 当前的实际 IP 地址，然后连接：

adb connect <ip>:5555

此备选方案同样记录于 FAQ.md 与 MagiskOnWSA 文档，适用于端口冲突无法彻底清除时的应急场景。

5. 常见问题与注意事项

Q1：执行dism.exe /Online /Disable-Feature:Microsoft-Hyper-V会影响其他虚拟机吗？

会。Hyper-V 是 WSA 及 Hyper-V 虚拟机、WSL2（若依赖 Hyper-V 架构）的底层支撑，禁用期间这些功能均不可用。因此务必在第三步之后、第五步及时重新启用，并规划好重启窗口。

Q2：第五步一定要加/All吗？

不一定。/All会启用 Hyper-V 的全部子功能（含管理工具）。若你只需要 WSA 运行所需的最小功能集，可去掉/All；文档默认建议使用/All以完整恢复原状。

Q3：netsh排除端口后需要重启吗？

本修复流程中第三步已包含一次重启（禁用 Hyper-V 后重启）。排除端口命令本身通常即时生效，但为保证 Hyper-V 重新启用后的状态干净，文档流程建议在第五步后再重启一次。

Q4：我在 MagiskOnWSA 目录下也看到了相同文档，以哪个为准？

仓库中 Documentation/Fix Guides/Post-Install Issues/TargetMachineActivelyRefusedConnection.md 与 MagiskOnWSA/docs/Fixes/TargetMachineActivelyRefusedConnection.md、MagiskOnWSA/DLL/docs/Fixes/TargetMachineActivelyRefusedConnection.md 内容一致，属于同一修复指南在顶层文档与构建产物文档中的同步副本，任选其一执行即可。

6. 小结：三步核心记忆点

先重启：这是 WSA 官方已知 bug，多数情况下重启即可恢复 Hyper-V 的端口保留行为。
再锁定端口：netsh int ipv4 add excludedportrange protocol=tcp startport=58526 numberofports=1是防止复现的关键，把 58526 从 Hyper-V 的动态保留池中永久排除。
最后恢复环境：记得重新启用 Hyper-V（/All）并重启，随后用adb devices验证修复成果。

若完成上述全部步骤后问题依旧，可在 WSABuilds 仓库的 Troubleshooting 与 FAQ 中查找更多排查入口，并携带完整的报错信息与执行日志向项目维护者反馈。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考