VSCode调试Next.js服务端代码需用node --inspect启动并Attach，因Next.js 13+主进程不执行业务逻辑，真实代码运行在子进程中，直接Attach主进程导致断点无法绑定。
VSCode 调试 Next.js 服务端代码（如 getServerSideProps、API Routes）不能靠默认 launch 配置，必须用 Node.js 的 --inspect 模式启动 dev server，并让 VSCode Attach 进去——否则断点永远不命中。
为什么默认 Attach 到 next dev 会失败
Next.js 13+（尤其是 App Router）启动时会 fork 多个子进程（如 Turbopack 监听、server actions handler、RSC server），next dev 主进程本身不执行页面逻辑，真正跑 getServerSideProps 或 API Route 的是内部的 Node.js worker 进程。直接 Attach 到主进程，VSCode 根本找不到那些函数的源码上下文。
- 现象：
getServerSideProps里打的断点显示为空心圆（unbound breakpoint），hover 提示 “Breakpoint ignored because generated code not found” - 根本原因：Vercel 的
nextCLI 启动的是一个包装器脚本，真实服务运行在动态 spawn 的子进程中，且 source map 路径映射不被默认launch.json识别 - 解决方案不是改
launch.json的program，而是改启动方式：让 Next.js 自己暴露 inspector 端口，再由 VSCode Attach
正确配置：用 node --inspect 启动 next dev
不修改任何 Next.js 代码，只调整启动命令和 VSCode 配置。关键在于让 Next.js 的 dev server 运行在可调试的 Node.js 实例中。
- 在项目根目录终端运行：
node --inspect-brk=9229 node_modules/next/dist/bin/next dev
（--inspect-brk会让进程在第一行暂停，确保 VSCode 连上后再继续） - VSCode 中创建
.vscode/launch.json，内容为：{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "attach", "name": "Attach to Next.js", "port": 9229, "address": "localhost", "localRoot": "${workspaceFolder}", "remoteRoot": "${workspaceFolder}", "sourceMaps": true, "skipFiles": ["<node_internals>/**"] } ] } - 注意
remoteRoot和localRoot必须一致，Next.js 的 sourcemap 是相对路径生成的，不配这个会导致断点映射失败 - 如果用 pnpm：把
node_modules/next/dist/bin/next换成node_modules/.pnpm/next@*/node_modules/next/dist/bin/next（用pnpm store path查路径，或直接npx next dev不推荐，因为 npx 启动的进程 inspector 不稳定）
调试 app/xxx/route.ts 和 getServerSideProps 的实操细节
这两类代码触发时机不同，但都依赖同一套 Attach 流程；区别在于断点位置和触发方式。
-
app/xxx/route.ts：在浏览器访问对应 URL 时才执行，断点打在POST/GEThandler 函数内即可，无需额外配置 -
getServerSideProps：必须用 Pages Router（pages/xxx.tsx），App Router 中没有该函数；断点打在函数体第一行，访问http://localhost:3000/xxx即触发 - 常见陷阱：
console.log输出可能出现在两个地方——VSCode Debug Console（来自 inspector）和 Terminal（来自 next CLI 包装器），只有前者能同步看到变量值和调用栈 - 性能影响：启用
--inspect后首次加载变慢（约 +800ms），但后续热更新不受影响；生产环境绝对不要加该参数
最易被忽略的一点：每次重启 next dev，都要先停掉旧的 Node.js 进程（Ctrl+C），再重新运行带 --inspect 的命令——VSCode Attach 不会自动重连，端口被占会导致连接拒绝。建议把启动命令写成 npm script："debug": "node --inspect-brk=9229 node_modules/next/dist/bin/next dev"，避免手敲出错。
