VSCode调试使用--network=host的Docker镜像失败问题求助

核心问题分析 #

你遇到的ECONNREFUSED错误，本质是VSCode无法和容器内的debugpy建立连接。虽然--network=host让容器共享宿主机网络，但不同系统下Docker的host网络实现逻辑有差异，加上端口监听、防火墙等因素，都会导致连接失败。

第一步：确认容器内debugpy的监听状态 #

先排查容器本身是否正常启动并监听端口：

1. 启动容器后，执行命令进入容器：

   docker exec -it <你的容器ID或名称> /bin/bash
   

2. 安装网络工具（如果没有的话）：

   # Debian/Ubuntu系
   apt update && apt install -y net-tools
   # Alpine系
   apk add net-tools
   

3. 查看端口监听情况：

   netstat -tulpn | grep 5678
   

   正常应该能看到debugpy进程监听0.0.0.0:5678。如果看不到，检查Dockerfile的CMD命令是否正确，比如small_app.py路径是否存在，debugpy是否安装成功。

分系统针对性解决 #

情况1：Linux系统（Docker直接运行在宿主机） #

Linux下--network=host是真·共享宿主机网络命名空间，问题通常出在端口占用或防火墙：

• 端口占用排查：在宿主机执行netstat -tulpn | grep 5678，如果有其他进程占用5678，杀掉该进程或换一个端口。
• 防火墙拦截排查：临时关闭防火墙测试：

  # Ubuntu/Debian
  sudo ufw disable
  # CentOS/RHEL
  sudo systemctl stop firewalld
  

  关闭后如果能连接，说明是防火墙拦截，添加永久规则开放5678端口：

  # Ubuntu/Debian
  sudo ufw allow 5678/tcp
  # CentOS/RHEL
  sudo firewall-cmd --add-port=5678/tcp --permanent
  sudo firewall-cmd --reload
  

• 确保监听地址正确：Dockerfile里的debugpy必须监听0.0.0.0:5678，不能是localhost或127.0.0.1——后者只会让容器内部访问，宿主机无法连接。

情况2：Windows/macOS系统（Docker Desktop基于虚拟机） #

Windows和macOS的Docker Desktop是跑在一个后台虚拟机里的，--network=host共享的是虚拟机的网络，不是你的物理主机网络。这是新手最容易踩的坑：

1. 获取Docker虚拟机IP：
   • Windows：打开Docker Desktop → 设置 → Resources → Network，查看Subnet对应的网关IP（比如192.168.65.2）；或者在PowerShell执行：

     docker run --rm alpine ip route | Select-String -Pattern 'default via' | ForEach-Object { $_.Line.Split(' ')[2] }
     

   • macOS：在终端执行：

     docker inspect bridge | grep -oP '"Gateway": "\K[^"]+'
     

2. 修改VSCode的launch.json配置：把connect.host从localhost换成刚才拿到的虚拟机IP，比如：

   {
       "name": "Python: Remote Attach",
       "type": "python",
       "request": "attach",
       "connect": {
           "host": "192.168.65.2", // 替换为你的Docker虚拟机IP
           "port": 5678
       },
       "pathMappings": [
           {
               "localRoot": "${workspaceFolder}",
               "remoteRoot": "/home"
           }
       ],
       "justMyCode": true
   }
   

3. 重新启动容器和VSCode调试，就能正常连接了。

额外验证点 #

• 查看容器日志：执行docker logs <容器ID>，确认是否有Waiting for client to connect...的输出，说明debugpy在正常等待连接。
• 直接用telnet测试连通性：在主机执行telnet <目标IP> 5678，如果能连通，说明网络没问题，问题出在VSCode配置；如果连不通，继续排查网络层面。

内容的提问来源于stack exchange，提问作者JohnJ