VS Code调试Next.js遇未绑定断点：源映射路径错误

问题说明 #

Windows系统下使用WSL和Chrome，在VS Code中配置Next.js调试器时，断点始终处于未绑定状态。浏览器调试控制台出现以下源映射读取错误：

Could not read source map for file:///C:/shared/node_modules/next/dist/compiled/%40next/react-refresh-utils/dist/runtime.js {...}'
Could not read source map for file:///C:/shared/node_modules/next/dist/compiled/%40next/react-refresh-utils/dist/internal/helpers.js {...}'

调试工具错误将file:///C:/shared识别为项目根目录，实际项目根目录为file:///C:/shared/work/workbench。

项目结构：

C:
  /shared/work/workbench
    /.vscode
      launch.json
      workbench.code-workspace
    {...rest}

现有配置 #

launch.json 内容 #

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)" ,
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

工作区文件内容 #

{
  "folders": [
    {
      "path": ".."
    }
  ]
}

解决步骤 #

1. 修正工作区路径配置 #

修改workbench.code-workspace中的路径，让VS Code正确识别项目根目录：

{
  "folders": [
    {
      "path": "."
    }
  ]
}

也可以直接使用绝对路径：

{
  "folders": [
    {
      "path": "C:/shared/work/workbench"
    }
  ]
}

2. 为Chrome调试添加源映射路径映射 #

在launch.json的客户端调试配置中，添加sourceMapPathOverrides，将错误路径映射到正确位置：

{
  "name": "Next.js: debug client-side",
  "type": "chrome",
  "request": "launch",
  "url": "http://localhost:3000",
  "sourceMapPathOverrides": {
    "file:///C:/shared/*": "file:///C:/shared/work/workbench/*"
  }
}

3. 指定服务端调试的工作目录 #

确保npm run dev在正确的项目根目录执行，修改服务端调试配置：

{
  "name": "Next.js: debug server-side",
  "type": "node-terminal",
  "request": "launch",
  "command": "npm run dev",
  "cwd": "${workspaceFolder}"
}

4. 清除缓存并重启 #

• 删除项目根目录下的.next文件夹
• 重启VS Code和Chrome
• 重新启动调试会话

验证 #

启动调试后，检查浏览器控制台是否消除源映射错误，同时测试断点是否能正常绑定并触发。

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