Next.js 13+ App Router 下 debugger 不生效，主因是服务端组件（SSR）与客户端执行环境混淆：debugger 在服务端代码中需用 VSCode Node.js Attach 模式（端口9229）调试，客户端逻辑须置于"use client"组件内；需确认 sourcemap、清缓存、区分 Chrome DevTools 与 VSCode 调试职责。
Next.js 13+ App Router 下 debugger 不生效？检查运行模式
在 VSCode 里调试 Next.js 应用，十有八九会卡在第一步：断点压根儿没触发。问题出在哪？大概率是搞错了代码的执行环境。App Router 默认启用了服务端组件（SSR），这意味着你写在 page.tsx 或 layout.tsx 里的 debugger 语句，其实是在 Node.js 服务端运行的。而你，很可能正眼巴巴地盯着浏览器的开发者工具，等着它停下来——这当然行不通。
几个实操建议，帮你快速定位：
- 确认当前页面是否触发 SSR：访问
https://localhost:3000后，别急着关终端。观察 Next.js 的启动日志，如果出现了wait - compiling /...和event - compiled client and server successfully这样的信息，并且带有 “server” 字样，那就说明服务端代码已经加载并执行了。 - 服务端断点必须通过 VSCode 的 Node.js 调试器附加，浏览器 F12 对此无能为力。
- 如果只想调试客户端逻辑（比如
useEffect、事件处理函数），那就得把debugger语句移到明确标记了"use client"的组件内部，并且确保这个组件没有被服务端组件直接调用。 - 还有个临时验证的法子：在
next.config.js里加上experimental: { serverComponentsExternalPackages: [] }来临时禁用 SSR。当然，这仅限于调试期，不推荐长期开启。
launch.json 配置 next dev 时为什么连不上？端口与自动重启是关键
直接用 VSCode 默认的 Node.js: Launch Program 模板去调试 Next.js？大概率会失败。原因在于，next dev 不是一个运行完就结束的脚本，而是一个长期驻留的开发服务器，并且它具备热重载（自动重启）的能力——这会导致调试器进程很容易“失联”。
怎么解决？关键在于正确的连接方式：
- 改用“附加”模式，而非“启动”模式：先手动在终端运行
npm run dev（或next dev）启动开发服务器。然后，在 VSCode 中按Ctrl+Shift+P，输入并选择Debug: Attach to Node Process，再从进程列表里选中next dev对应的 PID。 - 更稳定、可重复的方式，是直接配置
launch.json。使用attach配置，并显式指定端口：{ "type": "node", "request": "attach", "name": "Attach to Next.js", "port": 9229, "restart": true, "protocol": "inspector", "console": "integratedTerminal" } - 启动 Next.js 时，必须带上
--inspect标志：命令是next dev --inspect=9229（Next.js 13.2+ 支持；旧版本需要使用NODE_OPTIONS='--inspect' next dev）。 - 配置里的
restart: true至关重要。因为 Next.js 的热重载会终止旧进程、启动新进程，没有这个选项，断点在重载后就会失效。
调试 Server Actions 或 API Route 时断点跳过？确认执行环境与 sourcemap
Server Actions 和 app/api/xxx/route.ts 这类 API 路由，是纯粹的服务端逻辑。但有时候，VSCode 可能会因为 sourcemap 映射错误，或者构建缓存的问题，导致断点显示为灰色的“未绑定”状态，怎么都触发不了。
遇到这种情况，可以按以下步骤排查：
- 首先，确保在调试期间，
next.config.js中的output: 'standalone'选项是关闭的。如果开启，可能会跳过开发服务器的 sourcemap 生成。 - 强制清除构建缓存：运行
rm -rf .next && next dev --inspect=9229。尤其是在修改过tsconfig.json或next.config.js之后，这一步非常必要。 - 对于 Server Action，需要明确：它必须在客户端组件中触发（例如在
form action={...}里），断点要打在服务端的函数体内才有效。如果你直接把debugger放在useActionState的回调函数里，那是无效的。 - 调试 API Route 时，断点只在对应的 HTTP 请求发出后才会触发。别光刷新页面，试试用
curl https://localhost:3000/api/hello这样的命令来发起请求。 - 最后，检查一下 VSCode 的
Debug Console，看看有没有Could not read source map这类错误。如果有，通常意味着.next/server/app/...目录下的编译后 JS 文件，没能正确映射到你的 TSX 源码。这时，需要确认tsconfig.json中compilerOptions.sourceMap选项设置为true。
Chrome DevTools 和 VSCode 双调试冲突？优先级与入口点要分清
同时打开 Chrome 开发者工具（F12）和 VSCode 调试器，听起来很强大，但很容易引发“断点抢夺战”，导致单步调试时跳转错乱。这种情况在混合调试客户端钩子和服务端数据获取逻辑时尤为常见。
要避免冲突，关键在于明确分工：
- 给两个工具划清职责：让 VSCode 专心负责服务端逻辑（比如
generateStaticParams、服务端组件渲染、API 路由），而 Chrome DevTools 则专注于客户端交互（比如useState状态变化、fetch响应处理、DOM 操作）。 - 在专注于 VSCode 调试时，可以暂时禁用 Chrome 的 JS 断点干扰：打开 DevTools → Settings → Preferences → Debugger，勾选
Disable Ja vaScript debugging选项。 - 在 VSCode 中，不要启用
Smart Step Into功能（默认关闭即可）。Next.js 的打包层（比如edge-runtime、webpack的包裹代码）可能会让这个功能误入歧途，跳进无关的内部代码。 - 如果你发现断点总是停在
webpack/bootstrap或next/dist/...这类内部文件里，那基本可以断定是 sourcemap 没有对齐。解决办法？回到上一节，执行清除缓存和验证配置的步骤。
说到底，Next.js 调试中最棘手的，往往不是配置文件的几个参数，而是服务端组件与客户端组件边界模糊所带来的执行环境误判。经验表明，当你对一段代码的执行位置产生哪怕一丝怀疑时，最直接有效的办法就是先打上一行日志：console.log('env:', typeof window === 'undefined' ? 'server' : 'client')。确认了环境，很多问题就迎刃而解了。
