如何使用Puma Dev与VSCode调试Rails应用及配置远程调试

嘿，我来一步步帮你搞定用Puma Dev配合VSCode调试Rails应用的事儿，包括远程调试的配置——这都是我实际踩过坑后总结的有效方法，放心用！

一、前期准备 #

首先得确保咱们的基础环境没问题：

• 已经安装好Puma Dev，并且能正常关联你的Rails项目（比如用puma-dev link命令把项目绑定到.dev域名）
• VSCode里装好了Ruby调试插件，比如Ruby Debugger或者官方的Ruby LSP（后者更推荐，功能更全）
• 你的Rails项目依赖已经通过bundle install装全了，且能正常启动

二、让Puma Dev开启调试模式 #

Puma Dev默认不会启用调试端口，所以得先让它进入调试模式，有两种方式：

临时启动（单次生效） #

在终端里用环境变量启动Puma Dev：

PUMA_DEV_DEBUG=1 puma-dev

启动后看日志，会看到类似Debugger enabled on 0.0.0.0:9293的提示——这说明调试端口9293已经打开了（Puma默认调试端口是9292，Puma Dev会用9293避免冲突）

永久配置（每次启动自动生效） #

如果不想每次都输环境变量，可以创建Puma Dev的配置文件：

1. 在家目录下创建.puma-dev文件夹（如果还没有的话）
2. 在里面新建config文件，写入：

debug: true

之后每次启动Puma Dev都会自动开启调试模式，省心很多！

三、配置VSCode的调试器 #

接下来要让VSCode能连接到Puma Dev的调试端口：

1. 打开你的Rails项目，点击VSCode左侧的「运行和调试」图标（Ctrl+Shift+D）
2. 点击「创建launch.json文件」，选择「Ruby」环境（如果没看到这个选项，检查插件是否安装正确）
3. 把默认的配置替换成下面的内容：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Puma Dev",
      "type": "ruby",
      "request": "attach",
      "remoteHost": "127.0.0.1",
      "remotePort": "9293",
      "remoteWorkspaceRoot": "${workspaceFolder}",
      "cwd": "${workspaceFolder}",
      "showDebuggerOutput": true
    }
  ]
}

简单解释下关键参数：

• remotePort: 对应Puma Dev的调试端口，默认是9293，如果你改了配置里的端口，这里也要同步改
• remoteWorkspaceRoot和cwd: 都指向你的项目根目录，确保调试器能找到正确的代码文件
• showDebuggerOutput: 开启后能在调试控制台看到更多日志，方便排查问题

四、开始调试！ #

一切配置好后，按这个流程来：

1. 启动Puma Dev（不管是临时还是永久配置的调试模式）
2. 在VSCode里找到你想调试的代码行，点击行号左侧加个红点（断点），比如控制器的某个action里
3. 点击调试面板的绿色三角按钮，选择「Attach to Puma Dev」配置
4. 访问你的Rails应用的对应路由（比如http://yourapp.dev/posts），触发断点
5. 这时候VSCode就会自动暂停在断点处，你可以查看变量、单步执行、调用栈等，和本地调试完全一样！

五、常见问题排查 #

• 连接不上调试器？ 先看Puma Dev的启动日志，有没有Debugger enabled的提示；再检查VSCode的launch.json里的端口是否和Puma Dev的一致
• 端口冲突？ 可以修改Puma Dev的调试端口：在~/.puma-dev/config里加一行debug-port: 9294，然后把launch.json里的remotePort改成9294即可
• 断点不生效？ 确保你设置断点的文件是当前Puma Dev正在运行的代码文件，有没有可能代码被缓存了？可以重启Puma Dev试试

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