VSCode调试Next.js全栈必须拆分为服务端attach与客户端launch两个独立会话：服务端需--inspect=9229启动并配置"type":"node","request":"attach"，客户端需"type":"chrome"或"firefox"配合sourceMapPathOverrides映射webpack路径。
VSCode 调试 Next.js 全栈（服务端 + 客户端）必须拆成两个独立调试会话，不能靠单个配置“一键全链路”——因为服务端运行在 Node.js 进程，客户端运行在浏览器渲染引擎，二者调试协议、源码映射路径、启动时机完全不同。
为什么“Full Stack”配置常失败
常见错误现象：Breakpoint ignored because generated code not found（断点空心圆）、debugger语句不暂停、服务端逻辑（如 getServerSideProps 或 app/api/route.ts）完全不触发调试器。根本原因不是配置漏字段，而是试图用一个 launch.json 同时覆盖两类执行环境：
- 服务端代码由动态 fork 的 Node.js worker 进程执行，需
--inspect暴露端口 +attach模式连接 - 客户端代码经 Webpack/ESBuild 编译后注入浏览器，依赖
sourceMapPathOverrides映射到原始 TSX 文件 -
type: "node-terminal"或type: "pwa-node"无法同时满足两者，强行混用会导致其中一方断点失效
服务端调试：必须用 attach + --inspect
Next.js 13+（尤其 App Router）的 dev server 主进程只做调度，真正执行 getServerSideProps、API Routes、Server Actions 的是子进程。VSCode 默认 launch 模式连的是包装脚本，根本看不到业务代码上下文。
- 修改
package.json的dev脚本："dev": "next dev --inspect=9229"（端口可换，但要和后续配置对齐） - 确保
next.config.js启用 source map：experimental: { sourceMaps: true } -
.vscode/launch.json中添加独立的 attach 配置：{ "type": "node", "request": "attach", "name": "Attach to Next.js Server", "port": 9229, "restart": true, "skipFiles": ["<node_internals>/**"], "outFiles": ["${workspaceFolder}/.next/server/**/*.js"], "localRoot": "${workspaceFolder}", "remoteRoot": "${workspaceFolder}" } - 启动顺序严格：先终端运行
npm run dev，等日志出现ready - started server on http://localhost:3000后，再在 VSCode 里选该配置点击 ▶️ - 若用 pnpm，
node_modules/next/dist/bin/next路径需替换为 pnpm store 下的实际路径（如node_modules/.pnpm/next@*/node_modules/next/dist/bin/next）
客户端调试：Chrome/Firefox 启动 + 正确 sourceMap 映射
客户端断点（如 useEffect、事件处理器、"use client" 组件内逻辑）必须走浏览器调试通道，VSCode 只是前端调试器的 UI 前端。
- 配置 Chrome 启动项：
{ "type": "chrome", "request": "launch", "name": "Launch Chrome for Next.js", "url": "http://localhost:3000", "webRoot": "${workspaceFolder}", "sourceMaps": true, "sourceMapPathOverrides": { "webpack://_N_E/*": "${webRoot}/*", "webpack:///./~/*": "${webRoot}/node_modules/*", "webpack:///./src/*": "${webRoot}/src/*" } } - 关键不是
webRoot，而是sourceMapPathOverrides—— Next.js 默认生成的 sourcemap URL 是webpack://_N_E/开头，不配这个，VSCode 找不到原始文件 - 避免在服务端组件（如
page.tsx顶层）写debugger：它会在 Node.js 进程里执行，但你没 attach 到那个进程，也不会停；应移入"use client"组件或useEffect内 - 如果用 Firefox，
type: "firefox"配置中必须加"pathMappings"："pathMappings": [{ "url": "webpack://_N_E", "path": "${workspaceFolder}" }]
全栈协同调试的关键细节
所谓“全栈”，是指两个调试会话能同时运行、互不干扰，而非共享一个断点。最容易被忽略的三个点：
-
restart: true必须出现在服务端 attach 配置里：Next.js 热重载会 kill 旧子进程并拉起新进程，没这个字段，保存一次文件就断连 - 服务端和客户端调试不能共用同一个端口：Chrome 默认占
9222，Node.js attach 用9229是安全选择；若冲突，改--inspect=0.0.0.0:9230并同步更新launch.json的port - API Route 调试必须发真实请求：用
curl http://localhost:3000/api/hello测试最可靠，浏览器地址栏直接访问可能被缓存或跨域拦截，导致断点不触发
