VSCode无法调试Next.js服务端代码（遵循官方指南）

问题概述 #

使用VSCode调试Next.js应用服务端代码时，无法绑定任何断点，但通过Chrome开发者工具（chrome://inspect）附加调试可正常工作。

复现步骤 #

• 使用命令 npx create-next-app@latest nextjs-blog --use-npm --example "https://github.com/vercel/next-learn/tree/master/basics/learn-starter" 生成Next.js应用
• 按照官方文档创建launch.json配置文件
• 在VSCode中运行Next.js: debug server-side调试任务
• 在pages/index.js的Home组件return语句处设置断点
• 访问应用首页

预期行为 #

• VSCode中断点显示为红色实心圆点（绑定成功）
• 加载首页时触发断点

实际行为 #

• VSCode提示无法绑定断点
• 加载首页时断点未触发

补充信息 #

尝试在launch.json中添加以下attach配置项，手动运行npm run dev后启动该配置，VSCode给出更多提示：

{
  "name": "Attach",
  "port": 9229,
  "request": "attach",
  "skipFiles": ["<node_internals>/**"],
  "type": "node"
}

怀疑是sourcemap工作异常导致的问题。

系统信息 #

• Next.js版本：13.1.6
• VSCode版本：1.75.0
• Node版本：18.7.0
• 操作系统：Linux

排查与解决方案 #

1. 检查launch.json配置
   确保使用官方推荐的调试配置，尤其是node-terminal类型的配置（而非旧版的node类型），完整配置如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    }
  ]
}

node-terminal类型会自动处理Node的调试端口和sourcemap关联，避免手动配置的遗漏。

2. 强制开启sourcemap
   在项目根目录的next.config.js中添加sourcemap相关配置，确保服务端代码的sourcemap生成：

module.exports = {
  // 确保服务端sourcemap生成
  serverRuntimeConfig: {
    sourcemap: true,
  },
  // 可选：如果需要客户端sourcemap也开启
  productionBrowserSourceMaps: true,
}

3. Attach模式的正确启动方式
   如果使用attach模式，需要先启动带调试参数的开发服务：

npm run dev -- --inspect

确保Node进程开启了调试端口（默认9229），再启动VSCode的attach配置。

4. 更新相关组件

• 将VSCode的JavaScript Debugger插件更新到最新版本
• 考虑升级Node.js到18.x系列的稳定版，避免旧版本的调试兼容性问题

5. 确认断点位置
   确保断点设置在服务端实际执行的代码中：比如getServerSideProps函数内，或者服务端渲染的组件逻辑中。如果是仅客户端执行的代码，需要切换到客户端调试配置。

内容的提问来源于stack exchange，提问作者Tom Jardine-McNamara