Turbo Next.js在VS Code中服务端断点无法触发问题求助

1. 修正VS Code调试配置 #

Turbo会管控子进程，直接用官方默认的Next.js调试配置可能无法传递调试参数到服务端进程，需调整.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Turbo Next.js: Debug Server",
      "type": "node-terminal",
      "request": "launch",
      "command": "turbo dev",
      "env": {
        "NODE_OPTIONS": "--inspect"
      }
    }
  ]
}

• 核心是把NODE_OPTIONS="--inspect"直接注入到Turbo的启动环境中，确保子进程的Next.js服务能拿到调试参数。

2. 检查Turbo与Next.js的脚本配置 #

• 打开turbo.json，确认dev任务没有强制设置NODE_ENV=production，生产模式会压缩代码导致断点失效：

  "tasks": {
    "dev": {
      "cache": false,
      // 移除或注释掉这行："env": {"NODE_ENV": "production"}
    }
  }
  

• 如果是Monorepo结构，在你的Next.js应用目录（apps/[your-app]/package.json）的dev脚本中显式添加调试参数：

  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
  

3. 调试工具与环境适配 #

• Node.js版本：使用18.x及以上LTS版本，旧版Node对Turbo子进程的调试支持存在兼容性问题。
• 端口冲突处理：如果默认9229端口被占用，指定自定义端口：NODE_OPTIONS="--inspect=9230"，然后在VS Code调试配置或Chrome DevTools中对应修改端口。
• Chrome DevTools验证：打开chrome://inspect，点击「Configure」添加localhost:9229，启动调试后若能看到Next.js进程，说明调试连接正常。

4. 验证与排障步骤 #

1. 启动调试后，查看终端输出是否包含Debugger listening on ws://127.0.0.1:9229/[uuid]，这表明调试端口已正常监听。
2. 跳过Turbo直接运行NODE_OPTIONS="--inspect" next dev，如果断点能触发，说明问题出在Turbo的参数传递配置上，回到步骤1-2排查。
3. 确保服务端代码没有被Tree Shaking或压缩，检查.next目录下的服务端编译文件是否保留了源映射（source map）。

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