next.js dev server断点失效的根本原因是未启用v8 inspector，需添加--inspect或--inspect-brk参数启动，并在webstorm中使用“attach to node.js/chrome”配置连接指定端口，而非新建node.js运行配置。

Next.js dev server 启动后 WebStorm 断点不生效

根本原因不是 WebStorm 配置错了，而是 Next.js 默认用 next start 或 next dev 启动时没开调试端口，V8 Inspector 没暴露出来，WebStorm 连不上。

• 必须显式加 --inspect 或 --inspect-brk 参数启动服务，例如：next dev --inspect=0.0.0.0:9229
• --inspect-brk 会让服务在第一行就暂停，适合调试 SSR 初始化逻辑；--inspect 则只监听，需手动触发断点
• 如果用 npm run dev，得改 package.json 里的脚本，不能只靠 WebStorm 的 Node.js 运行配置“自动注入”
• Mac / Linux 下注意端口是否被占用；Windows 上 0.0.0.0 有时会绑定失败，可试 127.0.0.1:9229

WebStorm 怎么连上 Next.js 的 Node.js 进程

不是新建“Node.js”运行配置，而是用“Attach to Node.js/Chrome”——因为 Next.js dev server 是独立进程，WebStorm 要作为 client 去 attach，不是 launch。

• 启动 Next.js 前，先在 WebStorm 里点 Run → Attach to Node.js/Chrome
• Host 填 localhost，Port 填你启动时指定的调试端口（如 9229）
• 确保 “Auto-reconnect” 打钩，否则服务重启后会断连（Next.js 热更新常触发重启）
• 如果提示 “Connection refused”，先 lsof -i :9229 或 netstat -ano | findstr :9229 看端口是否真在监听

SSR 页面里 getServerSideProps 断点进不去

常见错觉是“断点加了但没停”，其实是执行时机和文件路径没对上：Next.js 的 SSR 代码是在服务端 Node.js 进程里跑的，不是浏览器里，所以必须在服务端入口或数据获取函数内设断点，且文件得被 Node.js 实际加载。

• 断点只能打在 getServerSideProps 函数体内部、getStaticProps 或 app 目录下 layout.tsx/page.tsx 的服务端组件逻辑里
• 不能打在纯客户端组件（比如 "use client" 开头的文件）里——那些根本不会在 Node 进程执行
• 如果你用 App Router，fetch 默认是服务端执行，但加了 cache: 'no-store' 或 force-cache 不影响断点，只要它发生在 SSR 渲染周期中
• 检查 WebStorm 左下角是否显示 “Connected to V8” 和当前匹配的源码路径，如果显示 “No source maps” 或路径是 webpack:// 开头，说明 sourcemap 没正确生成或映射错位

为什么改了代码、服务重启了，断点还失效

Next.js 的 HMR（热模块替换）和 WebStorm 的调试会话不是完全同步的。进程重启后，旧的 V8 session 断开，但 WebStorm 不一定立刻重建连接，尤其在快速保存+自动重载场景下。

• 每次手动保存触发服务重启后，观察 WebStorm 底部状态栏：出现 “Disconnected” 就要等几秒，看到 “Connected” 才算恢复
• 避免在 node_modules/next/dist 里打断点——那些是编译后代码，没 sourcemap，断点会飘到奇怪位置
• 如果用了 Turbopack（next dev --turbopack），目前 WebStorm 官方不支持其调试协议，断点必然失效，必须切回默认的 Webpack 模式
• 临时解决办法：加个 debugger 语句，比依赖 UI 断点更可靠，尤其在 SSR 函数开头

最常被忽略的是：Next.js 的 app 目录下，page.tsx 文件默认走服务端渲染，但一旦里面用了 useEffect 或 useState，WebStorm 断点仍只对服务端部分有效；客户端逻辑得切到 Chrome DevTools 里调。两边环境隔离得很彻底，别指望一个调试器通吃。