Next.js 13+服务端断点失效的根本原因是主进程不执行业务逻辑，必须通过--inspect启动并配置VSCode attach模式，同时启用experimental.sourceMaps: true且localRoot与remoteRoot严格一致。
next dev 默认不暴露调试端口，VSCode 直接 F5 启动或 Attach 主进程必然失败——断点显示为空心圆、hover 提示 Breakpoint ignored because generated code not found，这不是插件问题，而是 Next.js 13+ 的进程模型决定的。
为什么 next dev 断点不生效
Next.js 13+（尤其 App Router）启动后，主进程只做调度，真实业务逻辑（如 getServerSideProps、app/api/xxx/route.ts、Server Components）运行在动态 fork 出的子进程中。VSCode 默认 attach 到主进程，根本找不到源码上下文。
典型现象：
- 断点为空心圆，控制台无报错但不暂停
-
ps aux | grep next显示多个 Node 进程，PID 不同 - 修改代码热重载后，断点自动失效（旧进程被 kill，新进程没连上）
必须改 package.json 的 dev 脚本加 --inspect
不能依赖 VSCode 自动注入调试参数，next dev 是封装脚本，不传 --inspect 就不会开启 V8 Inspector。
实操步骤：
- 打开
package.json，修改"dev"字段："dev": "next dev --inspect=9229" - 若端口 9229 被占用，可换为
--inspect=0.0.0.0:9230，后续launch.json的port必须同步改 - 用 pnpm？写成
"dev": "pnpm exec next dev --inspect=9229"，否则pnpm不会正确解析next二进制路径 - 别用
--inspect-brk做日常调试——它卡死在第一行，每次保存都要手动 resume，严重拖慢开发节奏
launch.json 必须用 attach 模式且配对 localRoot/remoteRoot
"type": "node" + "request": "attach" 是唯一稳定方式；"request": "launch" 或 pwa-node 在 Next.js 13+ 下基本失效。
关键字段一个都不能错：
-
"port": 9229（必须和--inspect参数值一致） -
"localRoot": "${workspaceFolder}"和"remoteRoot": "${workspaceFolder}"必须严格相等——Next.js 的 source map 是相对路径生成的，不配这个，VSCode 找不到原始.tsx文件 -
"restart": true—— 热重载时自动重连新 fork 出的子进程 -
"skipFiles": ["<node_internals>/**"]</node_internals>—— 避免断点意外卡进 Node 内部代码
示例最小可用配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: attach",
"type": "node",
"request": "attach",
"port": 9229,
"restart": true,
"skipFiles": ["<node_internals>/**"],
"localRoot": "${workspaceFolder}",
"remoteRoot": "${workspaceFolder}"
}
]
}
next.config.js 必须启用 experimental.sourceMaps
没 source map，VSCode 就无法把编译后的 JS 映射回原始 TSX，断点自然无效。Next.js 13.4+ 默认不生成完整 sourcemap。
操作很简单：
- 在
next.config.js中加入：experimental: { sourceMaps: true } - 纯 JS 项目也要加，不只是 TypeScript 项目
- 改完需重启
npm run dev，否则.next/目录下不生成sourcemap文件 - TSX 文件断点灰掉？先确认
tsconfig.json里"sourceMap": true已开启，再检查next.config.js是否生效
真正容易被忽略的是：所有环节必须同时满足——--inspect 启动、attach 配置、sourceMaps: true、localRoot/remoteRoot 一致。漏掉任意一环，断点就只是个装饰。
