VSCode Ruby调试器127.0.0.1:1234端口占用故障求助

问题现象 #

• 调试控制台报错：ECONNREFUSED ::1:1234
• 重启VSCode、关机、重置网络均无法解决
• 启动VSCode后执行netstat -a，显示127.0.0.1:1234处于LISTENING状态；关闭VSCode后该状态仍存在，但netstat -b无进程关联信息
• 重装VSCode并仅启用Ruby、VSCode rdbg、VSCode ruby扩展后，报错变为：Fatal exception in DebugThread loop: Only one usage of each socket address (protocol/network address/port) is normally permitted. - bind(2) for "127.0.0.1" port 1234
• 非调试模式下Ruby程序可正常运行，仅调试功能异常
• 问题出现前仅执行过bundler install操作

排查与解决步骤 #

1. 修改调试端口，避开默认的1234 #

在.vscode/launch.json中添加port字段，指定一个未被占用的端口（例如1235）：

{
    "name": "MAIN",
    "type": "Ruby",
    "request": "launch",
    "cwd": "${workspaceRoot}",
    "program": "${workspaceRoot}/main.rb",
    "port": 1235
}

保存配置后重新启动调试，验证是否能正常连接。

2. 强制清理端口残留连接（Windows环境） #

1. 打开管理员命令提示符，执行以下命令查看端口是否被系统保留：

netsh int ipv4 show excludedportrange protocol=tcp

如果1234在保留范围内，重启WinNAT服务释放端口：

net stop winnat
net start winnat

2. 若端口未被系统保留，强制结束可能残留的关联进程：

taskkill /F /IM ruby.exe
taskkill /F /IM code.exe

完成后重新启动VSCode尝试调试。

3. 调整Ruby调试扩展设置 #

针对VSCode rdbg扩展，修改以下配置：

• 打开VSCode设置（快捷键Ctrl+,），搜索rdbg，将Debugger: Port设置为自定义端口，而非默认的1234
• 关闭Debugger: Auto Attach功能，避免自动关联进程导致端口占用冲突

4. 排查Bundler安装的Gem影响 #

尝试临时隔离bundle环境，验证是否为依赖包导致的问题：

1. 备份Gemfile.lock后删除该文件
2. 执行bundle install --clean重新安装依赖
3. 不通过bundle exec启动调试，直接使用VSCode默认的Ruby调试器运行程序

5. 重置Ruby调试器配置 #

删除VSCode的Ruby扩展缓存，重新安装扩展：

• 关闭VSCode
• 前往%USERPROFILE%\.vscode\extensions，删除所有Ruby相关的扩展文件夹（如rebornix.ruby-*、rubyide.ruby-debugger-*）
• 重新安装Ruby和rdbg扩展，重新生成launch.json配置

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