如何通过VSCode调试Ruby 2.4.10的旧Rack/Cuba项目

前置环境准备 #

• 先在项目根目录终端执行rbenv local 2.4.10，执行ruby -v确认输出为2.4.10版本，避免多版本Ruby串环境
• 安装适配Ruby 2.4的调试依赖，不要装最新版gem，会有兼容问题：
  • 执行gem install ruby-debug-ide -v 0.7.3，这是最后一个支持Ruby 2.4的调试IDE适配层版本
  • 执行gem install debase -v 0.2.5.beta2，这是适配Ruby 2.4的调试核心库，0.3及以上版本会出现C扩展编译失败的问题
  • 把上述两个gem添加到dep的依赖清单里，避免后续换环境丢失依赖
• 在VSCode插件商店搜索官方发布的Ruby扩展并安装，不要装第三方杂项Ruby调试插件，容易有端口冲突
• 如果之前装Ruby 2.4的时候没指定openssl版本，先执行brew install openssl@1.1，再重新执行RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)" rbenv install 2.4.10重装对应版本，Ruby 2.4不支持高版本openssl3，会导致后续各类gem编译、网络请求报错；如果编译C扩展时报错，先执行xcode-select --install装好Mac命令行开发工具。

launch.json 可用配置 #

在项目根目录新建.vscode/launch.json文件，粘贴以下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Cuba/Rack API",
      "type": "Ruby",
      "request": "launch",
      "program": "${workspaceRoot}/config.ru",
      "cwd": "${workspaceRoot}",
      "runtimeExecutable": "~/.rbenv/shims/ruby",
      "runtimeArgs": [
        "-S",
        "rackup",
        "-p",
        "9292",
        "-o",
        "0.0.0.0"
      ],
      "port": "1234",
      "debuggerPort": "1235",
      "showDebuggerOutput": true,
      "stopOnEntry": false
    }
  ]
}

配置注意点 #

• runtimeExecutable必须指向rbenv的shim路径，Mac上VSCode作为GUI应用默认拿不到终端里配置的rbenv PATH变量，直接写ruby会调用系统自带的高版本Ruby，触发语法兼容报错
• 不要在runtimeArgs里加dep exec或者bundle exec包裹rackup命令，dep本身是轻量依赖管理，rbenv shim下的rackup会自动加载项目依赖，额外加进程嵌套会导致调试端口无法连通
• 如果你的服务启动入口不是默认的config.ru，把program字段改成你实际的rack启动文件路径即可

调试验证步骤 #

• 在Cuba路由的业务逻辑行号左侧点击，打红色断点标记
• 切到VSCode调试面板，选中Debug Cuba/Rack API配置，点击启动按钮
• 等调试控制台输出服务启动成功、调试器已连接的日志后，调用对应接口，就会自动命中断点，支持单步执行、变量查看、调用栈追踪等常规调试操作

给Ruby初学者的补充参考 #

• 老版本Ruby最容易踩的坑就是gem版本不兼容，所有带C扩展的gem（调试工具、数据库驱动、网络库等），安装前先确认最后一个适配当前Ruby版本的发布号，不要直接装最新版
• 搞懂rbenv的shim机制能解决90%的多版本环境问题：你在终端执行的ruby、gem、rackup等命令本质都是shim转发脚本，会自动读取当前目录的.ruby-version文件切到对应Ruby版本，GUI应用因为不加载终端shell配置，经常拿不到这个路径，手动指定执行路径是最稳妥的方案
• Cuba+Rack的栈非常薄，没有多余的魔法封装，调试的时候顺着Rack的call方法往下走，很快就能搞懂Ruby Web服务的请求处理全流程，比厚重的全栈框架更适合入门理解底层逻辑
• dep作为小众依赖管理工具，核心逻辑就是手动把gem的lib目录加到加载路径，没有复杂的版本隔离逻辑，如果遇到找不到gem的报错，直接检查dep生成的路径配置文件有没有把对应gem目录加进去即可，不用绕复杂的排查流程

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