WSABuilds 故障排查：修复 WSA 端口 58526 连接被拒（错误 10061）的 Hyper-V 端口保留方案-平芜编程栈

WSABuilds 故障排查：修复 WSA 端口 58526 连接被拒（错误 10061）的 Hyper-V 端口保留方案

【免费下载链接】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 仓库中的官方修复指南 TargetMachineActivelyRefusedConnection.md 展开，聚焦一个高频故障：在 WSA（Windows Subsystem for Android）上使用 ADB 或侧载工具连接127.0.0.1:58526时报错 “No connection could be made because the target machine actively refused it (10061)”。读完本文，你将理解该错误的触发场景与 Hyper-V 端口争用的根因，并掌握一套完整的、可重复执行的修复流程：通过dism与netsh命令永久保留端口 58526，避免 Hyper-V 动态端口池再次抢占，使 ADB 配对与 APK 侧载恢复正常。

一、故障现象与触发场景

1.1 报错特征

当你在 Windows 上尝试连接 WSA 的 ADB 无线调试端口时，终端会返回如下错误：

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

错误码 10061 是 Windows 下典型的“目标主机会话被主动拒绝”：TCP 握手到达主机后，发现没有进程在该端口监听（或端口被其他机制占用/释放异常），于是被立即 RST 拒绝。

1.2 哪些操作会触发它

按照 MagiskOnWSA/DLL/docs/Fixes/TargetMachineActivelyRefusedConnection.md 的说明，该问题通常在以下两类场景中暴露：

使用侧载工具安装 APK：例如 WSA-Sideloader 或 WSAPacman 这类依赖 ADB 通道与 WSA 通信的应用。仓库中对应的两份使用指南 WSA-Sideloader.md 与 WSAPacman.md 都默认 WSA 的 ADB 端口可用——其中 WSA-Sideloader 指南的 Troubleshooting 一节明确写道：当出现 “No connection could be made because the target machine actively refused it” 提示时，应转去执行本文所述的修复流程。
手动执行 ADB 连接：通过 Android SDK Platform Tools 中的adb.exe对 WSA 执行配对与连接。仓库的 ADB 侧载教程 ADB-Sideloading.md 给出了正常路径下的标准操作：
```
adb pair 127.0.0.1:58526 adb connect 127.0.0.1:58526
```
当 58526 端口被争用时，上述两条命令就会直接报出 10061 错误。

此外，该仓库的 FAQ（见 MagiskOnWSA/DLL/docs/README.md 中 “I cannot adb connect localhost:58526” 条目）还给出了一个前置排查思路：先确认 WSA 设置 → Developer 页面中Developer mode（开发者模式）已开启；若仍连不上，可在开发者页面查看实际显示的 IP 与端口再尝试连接。这一点在实施本文修复流程前应先行确认，因为它能排除“根本没开开发者模式导致端口未监听”这类更简单的原因。

二、根因分析：Hyper-V 动态端口池与 58526 的争用

从修复文档的定性来看，该问题被记录为 WSA 子系统本身的一个已知缺陷（上游 WSA 项目已追踪此 bug）。文档给出的直接结论是：重启 PC 通常就能恢复——这本身就暗示问题出在运行期内核态组件（Hyper-V 网络虚拟化层）对端口的保留/释放行为上，而非 WSA 配置错误。

其技术机制可以这样理解：

WSA 本质上运行在 Hyper-V 虚拟化环境之上，其 ADB 调试服务通过宿主机的127.0.0.1:58526对外暴露（开发者模式下可在 WSA 设置中看到该 IP 与端口，ADB-Sideloading.md 的教程也要求用户“记录开发者模式区域显示的 IP 地址和端口”）。
Hyper-V 会为虚拟机网络动态保留一段 TCP 端口区间。故障发生时，Hyper-V 对端口 58526 的保留状态出现异常：该端口既没有被 WSA 正常监听，又被 Hyper-V 的端口保留机制“挂起”，结果就是所有指向127.0.0.1:58526的 TCP 连接被内核直接拒绝，表现即 10061。
重启之所以有效，是因为 Hyper-V 网络栈重新初始化后会释放这段异常保留；但若系统再次出现同类状态（尤其是 Hyper-V 已启用且频繁分配端口的机器上），错误会复现——这正是官方修复指南要求做端口永久保留的原因。

从仓库文档结构看，该修复文档被放在 MagiskOnWSA/DLL/docs/Fixes/ 目录（与安装类错误 0x80073C 系列修复、FixInternet.md、FixVirtError.md 等并列），并在 Documentation/Fix Guides/Post-Install Issues/TargetMachineActivelyRefusedConnection.md 中有同步维护的版本，说明 WSABuilds 将其视为 WSA 安装后（Post-Install）阶段的常规排障项，而非 Magisk 根权限特有问题。

三、完整修复流程（五步法）

官方修复指南给出的标准流程如下。除重启外，核心手段是先把 Hyper-V 从“现场”撤出（禁用 → 重启 → 用netsh把 58526 加入 TCP 排除端口区间），再把 Hyper-V 恢复原状，从而让 58526 脱离 Hyper-V 动态端口池的管辖范围，WSA 之后可以独占该端口。

权限提示：下文dism与netsh命令均需以管理员身份运行的 PowerShell / 命令提示符执行。

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

在开始任何端口操作之前，先确保 WSA 处于关闭状态，并防止它在后续重启中自动拉起：

完全关闭 WSA；
打开任务管理器 → 启动应用（Startup Apps），将 WSA 的自启动项禁用。

这一步保证重启后的端口保留操作在“干净”环境下生效，避免 WSA 与 Hyper-V 在启动竞争时再次争抢 58526。

第 2 步：禁用 Hyper-V（若当前已启用）

以管理员身份执行：

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

dism（部署映像服务和管理工具）在这里以/Online作用于当前系统映像，通过Microsoft-Hyper-V功能开关将整个 Hyper-V 平台临时禁用。该步骤的目的是让端口 58526 上的异常保留在“Hyper-V 完全不在场”的窗口期内被清除。

第 3 步：重启计算机

禁用功能必须重启后才生效。此时 WSA 端口上的异常保留会随 Hyper-V 网络栈的重建而释放。

第 4 步：将端口 58526 加入 TCP 排除区间（核心步骤）

重启后，以管理员身份执行：

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

参数逐项说明：

参数	取值	含义
`protocol`	`tcp`	针对 TCP 协议建立排除区间（ADB 走 TCP）
`startport`	`58526`	区间起始端口，即 WSA 开发者模式 ADB 端口
`numberofports`	`1`	区间长度仅 1 个端口，只锁定 58526 本身

netsh int ipv4 add excludedportrange会将指定端口段登记到 Windows 的**排除端口区间（excluded port range）**表中。一旦登记，Hyper-V 的动态端口分配机制不会再从该区间内保留端口，官方指南的表述正是：“Reserve port 58526 so Hyper-V doesn't reserve it back”（保留端口 58526，防止 Hyper-V 再次把它收进自己的动态保留池）。执行后可用如下命令确认区间已登记：

netsh int ipv4 show excludedportrange protocol=tcp

输出中应能看到以 58526 开头的 TCP 排除区间条目。

第 5 步：恢复 Hyper-V 并再次重启

如果你在第 2 步禁用了 Hyper-V（即它原本是启用的），现在用dism恢复它：

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

/All会连同依赖的 Windows 功能组件一并启用。随后再次重启。重启完成后，58526 仍处于排除区间内，但 Hyper-V 的端口分配逻辑已经知道“避开这一段”，因此它不会再抢占 58526。

如果第 2 步中 Hyper-V 本来就没启用（例如系统仅通过其他虚拟化机制运行 WSA），则跳过本步。

四、验证修复结果

完成上述流程后，按 ADB-Sideloading.md 的标准路径验证 ADB 通道是否恢复：

启动 WSA，在Settings → Developer中确认开发者模式已开启，并留意页面上显示的 IP 地址与端口；

在终端执行配对与连接：

adb pair 127.0.0.1:58526 adb connect 127.0.0.1:58526

用adb devices确认 WSA 已出现在设备列表中；
回到侧载工具（WSA-Sideloader / WSAPacman）重新安装 APK，确认不再弹出 “No connection could be made because the target machine actively refused it” 提示。

一个补充点：ADB 教程要求用户在开发者页面记录实际显示的 IP 与端口。本文所有命令围绕默认的 58526 展开（这也是修复文档与 FAQ 使用的端口）；如果你的开发者页面显示的是其他端口，请将netsh命令中的startport与adb pair/connect的地址相应替换为实际值，流程逻辑不变。

另外，若排除端口方案后问题依旧，可参考 FAQ（MagiskOnWSA/DLL/docs/README.md）中的备选思路：在开发者页面查看 WSA 实际的 IP 地址，改用adb connect <ip>:5555形式尝试，以区分“端口保留异常”与“监听端口与预期不一致”两类情况。

五、方案要点与适用前提

为什么“重启即可”不够？重启只清除当前的异常保留状态；netsh排除区间把 58526 从 Hyper-V 动态端口池中永久摘除，是针对复现的治本手段，两者配合使用才完整。
适用前提：Windows 10 / 11 上已安装 WSA（WSABuilds 构建或官方版本均适用，该问题与 Magisk/KernelSU 无关）；执行dism/netsh需要管理员权限；步骤 2、5 仅在 Hyper-V 当前已启用的前提下成对执行，避免把系统留在“Hyper-V 被禁用”的中间状态。
文档定位：本篇流程对应仓库 MagiskOnWSA/DLL/docs/Fixes/TargetMachineActivelyRefusedConnection.md（Documentation/Fix Guides/Post-Install Issues/TargetMachineActivelyRefusedConnection.md 为其在 WSABuilds 文档体系中的对应版本）；后续做 ADB 侧载时，可继续结合 ADB-Sideloading.md、WSA-Sideloader.md、WSAPacman.md 三份指南使用。

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