VSCode如何配置Next.js的服务端渲染(SSR)断点调试

Next.js SSR断点不命中，主因是VSCode未连接到正确的子进程且source map未启用：需用--inspect启动并配置attach模式调试，同时在next.config.js中开启experimental.sourceMaps。

Next.js SSR断点不命中，基本就是没连对进程

很多开发者第一次在VSCode里调试Next.js的SSR逻辑时，都会遇到一个典型现象：断点变成了空心圆，鼠标悬停上去，提示“Breakpoint ignored because generated code not found”。这问题看似复杂，其实根源很直接——调试器压根没连到代码真正运行的地方。

怎么回事呢？当你用默认的launch模式去调试next dev时，VSCode会连接到Next.js的主包装进程。然而，像getServerSideProps、app/api/路由、Server Actions这些服务端渲染的核心逻辑，实际上是在Next.js动态fork出来的子进程里执行的。调试器连错了“房间”，自然就找不到你设下的断点了。

必须用 --inspect 启动 + attach 模式

解决思路很清晰：我们不能让VSCode“盲猜”进程，得让Next.js主动“举手”报告自己的位置，再由调试器去连接。关键在于两步走，缺一不可。

• 第一步，修改package.json中的dev脚本，加上--inspect=9229参数（端口号可以自定义，但后续配置必须同步）。
• 第二步，在.vscode/launch.json里配置一个attach类型的调试配置，端口号要对齐，并且type必须设为node（注意，不是pwa-node）。
• 启动顺序也有讲究：先运行npm run dev启动Next.js服务，然后在VSCode里选择刚才配置好的attach配置，点击运行。

下面是一个可以直接用的launch.json配置片段：

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Next.js SSR",
  "port": 9229,
  "address": "localhost",
  "skipFiles": ["/**"],
  "outFiles": ["${workspaceFolder}/.next/server/**/*.js"]
}

sourceMap 不开，断点永远找不到源码

即使调试器成功连上了正确的进程，还有一个“拦路虎”：source map。Next.js出于性能考虑，默认不会将source map写入磁盘，尤其是在App Router架构下，SWC编译器默认是禁用此功能的。没有source map，VSCode看到的就只是一堆编译后的、难以阅读的Ja vaScript代码，无法映射回你亲手编写的.ts或.tsx源文件，断点自然失效。

• 对于Next.js 13.4及以上版本，解决方案是在next.config.js文件中添加配置：experimental: { sourceMaps: true }。
• 如果是旧版本项目，或者使用了自定义Webpack配置，则需要手动设置devtool: 'source-map'。
• 配置完成后，可以到.next/server目录下检查，确认生成了对应的.map文件，例如.next/server/pages/xxx.js.map或.next/server/app/xxx/page.js.map。

常见失效场景和绕过验证法

配置都做了，断点还是灰色的？先别急着反复调整配置，用几个简单的方法快速验证一下，问题可能出在别处。

• 验证代码是否真的在服务端执行：在getServerSideProps或API路由文件里加一行console.log('pid:', process.pid)，刷新页面，观察终端是否有输出。如果没有输出，那说明请求根本没走SSR流程。
• 避免客户端导航：调试API路由时，直接在浏览器地址栏访问http://localhost:3000/api/hello，而不是通过点击前端按钮触发。前端路由跳转可能会绕过服务端渲染。
• 注意App Router的特性：像useServerSeoMeta或generateStaticParams这类函数，通常只在页面首次服务端渲染时触发，后续的客户端路由跳转不会重新执行。
• 环境隔离问题：如果开发环境在Docker或WSL中，那么launch.json里的address需要设置为"0.0.0.0"，并且启动命令也要相应改为next dev --inspect=0.0.0.0:9229。

还有一个极易被忽略的细节：Next.js开发服务器的热重载（Hot Reload）会导致进程PID发生变化。如果VSCode没有自动重连，断点就会失效。稳妥起见，建议在launch.json的配置里加上"restart": true选项，这样就能在代码修改后保持调试会话的活性，避免“改一行代码，断点全失效”的尴尬局面。