VSCode调试连接失败首要排查Windows防火墙入站规则，因其默认拦截调试端口（如2345、5678、9229），导致connection refused；需在“高级安全Windows Defender防火墙”中新建端口规则，明确放行对应TCP端口，并勾选域、专用、公用网络，且WSL2场景下该规则必不可少。
VSCode调试连接失败，先查Windows防火墙入站规则
绝大多数“connecting to port XXX”卡住或 connection refused 错误，根源不在 VSCode 或调试器本身，而在 Windows 防火墙默认拦截了入站调试端口。VSCode 启动调试时（比如 attach 到 gdbserver、debugpy 或 node --inspect），目标进程监听的端口（如 2345、5678、9229）必须被 Windows 防火墙明确放行——否则连接请求在系统层就被丢弃，VSCode 根本收不到响应。
验证方法：在 Windows 上打开「高级安全 Windows Defender 防火墙」→「入站规则」→ 右侧「新建规则」→ 选「端口」→ TCP → 特定本地端口（填你调试用的端口号，例如 2345）→「允许连接」→ 勾选「域」「专用」「公用」→ 命名（如 vscode-gdb-remote）→ 完成。
- 不要只依赖「程序」规则（如放行
Code.exe），它对调试端口无效；入站流量由监听端口的进程（如gdbserver或 Python 进程）触发，但 Windows 防火墙按端口而非发起者判断 - WSL2 场景下，该规则必须存在：WSL2 的虚拟网卡 IP 发起的连接，在 Windows 看来仍是外部入站请求
- 若使用非标准端口（如把
debugpy改到5679），需为新端口单独建规则，旧规则不自动生效
launch.json 中 address 写 localhost 还是 0.0.0.0？
取决于调试模式和网络拓扑。写错会导致 VSCode 尝试连错地址，或远程进程拒绝绑定。
常见组合：
- 本地调试（进程在 Windows 本机运行）：
"address": "localhost"—— 正确。此时gdbserver或debugpy绑定127.0.0.1:2345，VSCode 从同一台机器连过去 - WSL2 调试（进程在 WSL2 中运行，VSCode 在 Windows 中）：
"address": "localhost"—— 仍正确。WSL2 默认通过 localhost 映射端口，只要防火墙放行，Windows 能透传到 WSL2 的监听进程 - 真远程服务器（如树莓派、云主机）：
"address": "<target_ip>"</target_ip>（如"192.168.1.100"）—— 必须显式填 IP。写"localhost"会让 VSCode 去连自己本机，而不是目标机器 - 若远程进程绑定了
0.0.0.0（全网卡监听），VSCode 的address仍应填目标 IP，不是0.0.0.0
gdbserver 或 debugpy 启动后，端口是否真在监听？
VSCode 报 connection refused，常因目标端口根本没起来，或被其他进程占用了。不能只信 launch.json 配置，要实机验证。
在目标环境（WSL2、树莓派、Linux 服务器）执行：
- 查端口监听：
ss -tuln | grep :2345（或netstat -tuln | grep :5678）。有输出才说明进程已成功 bind 并 listen - 查谁占着端口：
lsof -i :2345（Linux/macOS）或netstat -ano | findstr :2345（Windows cmd）。若 PID 属于无关进程，需 kill 或换端口 - 手动启动测试：
gdbserver :2345 ./myapp，看是否立即打印Listening on port 2345；python -m debugpy --listen 5678 --wait-for-client myscript.py，看是否阻塞等待而非报错退出
注意：debugpy 若版本低于 1.6.0，--wait-for-client 参数不支持，会直接退出，导致端口不监听——务必用 python -m pip show debugpy 确认版本。
防火墙规则开了，还是连不上？检查 WSL2 的双重拦截点
WSL2 用户最容易漏掉的是：Windows 防火墙放行端口后，WSL2 自身的防火墙（如 ufw）可能还在拦。这是两层独立防护，缺一不可。
在 WSL2 终端中执行：
- 确认
ufw状态：sudo ufw status verbose。若显示Status: active，且没有对应端口（如2345）的 ALLOW 规则，则需添加：sudo ufw allow 2345 - 若用
firewalld（如 CentOS WSL）：sudo firewall-cmd --list-ports，再用sudo firewall-cmd --add-port=2345/tcp --permanent && sudo firewall-cmd --reload - SELinux 用户（较少见但存在）：
sudo setsebool -P gdb_exec_t on可能影响gdbserver权限，但更常见的是端口绑定失败，需查sudo ausearch -m avc -ts recent
真正棘手的情况是：Windows 防火墙开着，WSL2 的 ufw 也开着，但只开了其中一层——现象完全一样，排查必须分层验证，不能假设“开了一个就等于通了”。
