基于VSCode的Node进程守护工具（PM2）本地群集调试方案-VSCode-PHP中文网

pm2 + vscode 本地集群调试可行，但必须显式启用调试端口并为每个实例分配唯一端口，否则vscode无法attach到多个进程；因默认cluster模式下所有worker共享同一inspect端口会冲突，且vscode attach调试器只能连接单个目标进程。

基于vscode的node进程守护工具（pm2）本地群集调试方案

直接说结论：PM2 + VSCode 本地群集调试可行，但不能靠 pm2 start 默认模式硬上，必须显式启用调试端口并为每个实例分配唯一端口，否则 VSCode 无法 attach 到多个进程。

为什么 `pm2 start --watch` 无法直接调试群集模式

群集（cluster）模式下，PM2 默认 fork 多个子进程共享同一监听端口（如 3000），但所有子进程共用一个 --inspect 端口会冲突。VSCode 的 attach 调试器只能连接一个目标进程，且无法自动发现集群中哪个 worker 实际在处理请求。

常见错误现象：Connection refused 或调试器连上后断点不命中、日志无输出、CPU 占用显示为 0。

PM2 cluster 模式默认不开启 inspector，需手动为每个 worker 注入 --inspect
--watch 会触发全量重启，导致正在调试的 worker 进程被杀，VSCode 连接中断
未指定 exec_mode: 'cluster' 时，pm2 start 默认走 fork 模式，看似“多进程”实为单实例，达不到群集调试目的

`pm2 start` 启动带独立调试端口的 cluster 实例

关键点是让每个 worker 绑定不同 inspect 端口，且避免热重载干扰调试会话。推荐使用配置文件方式启动：

创建 ecosystem.config.js：

Rydberg Agent Node

使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r

下载

{
  apps: [{
    name: 'api-cluster',
    script: './server.js',
    exec_mode: 'cluster',
    instances: 4,
    node_args: '--inspect=9230',
    // 注意：此处 node_args 会被每个 worker 继承，但端口会自动递增（9230, 9231, 9232, 9233）
    watch: false, // 关闭 watch，防止调试中被意外重启
    env: {
      NODE_ENV: 'development'
    }
  }]
}

然后执行：pm2 start ecosystem.config.js

PM2 会自动为每个 worker 分配递增的 inspect 端口（从 9230 开始）
必须关闭 watch，否则文件变更会 kill 所有 worker，断开所有调试连接
若用命令行启动，需写成 pm2 start server.js -i 4 --node-args="--inspect=9230"，效果相同

VSCode 中配置多个 `attach` 调试配置

一个 launch 配置只能 attach 一个进程，群集调试需要为每个 worker 显式定义独立配置：

在 .vscode/launch.json 中添加：

[
  {
    "name": "Attach to Worker 0",
    "type": "pwa-node",
    "request": "attach",
    "address": "127.0.0.1",
    "port": 9230,
    "localRoot": "${workspaceFolder}",
    "remoteRoot": "${workspaceFolder}",
    "skipFiles": ["<node_internals>/**"]
  },
  {
    "name": "Attach to Worker 1",
    "type": "pwa-node",
    "request": "attach",
    "address": "127.0.0.1",
    "port": 9231,
    "localRoot": "${workspaceFolder}",
    "remoteRoot": "${workspaceFolder}",
    "skipFiles": ["<node_internals>/**"]
  }
]</node_internals></node_internals>

每个配置对应一个固定端口，不可复用；端口数必须 ≤ instances 数
remoteRoot 必须与实际运行路径一致，尤其在 Docker 或远程部署时容易填错
VSCode 不支持“自动 attach 到所有匹配端口”，必须手动逐个启动调试会话

调试时的实际操作与易忽略细节

群集调试不是“启动就完事”，关键在于如何验证和切换上下文：

先运行 pm2 show api-cluster，确认每个 worker 的 PID 和实际绑定的 inspect 端口（PM2 日志里会打印 Debugger listening on ws://127.0.0.1:923X/...）
VSCode 调试面板中，每次只能 active 一个调试会话；不同 worker 的断点互不影响，但日志输出混在一起，需靠 process.pid 或 cluster.worker.id 区分
若修改代码，必须手动 pm2 reload api-cluster（非 restart），才能触发 worker 优雅重启并保留调试连接
不要在调试中使用 pm2 restart —— 它会彻底 kill 所有 worker，VSCode 会报 Target not connected