如何设置VSCode以构建Next.js开发环境？

本文共计882个文字，预计阅读时间需要4分钟。

VSCode 调试 Next.js 应用，无需图形界面，直接输出结果。

为什么直接 F5 启动 next dev 断点不命中

Next.js 的 next dev 是一个封装脚本，启动后会 fork 出多个 worker 进程（比如 RSC server、API handler、server actions runner），而 VSCode 默认的 launch 配置只能 attach 到主进程。主进程根本不执行你的业务函数，所以 getServerSideProps 里的断点 hover 显示 “Breakpoint ignored because generated code not found”。

• 现象：断点显示为空心圆，控制台无报错，但就是不暂停
• 本质：VSCode 找不到源码映射上下文，因为 source map 是子进程生成的，路径没对上
• 验证方法：终端运行 ps aux | grep next，能看到多个 Node 进程，PID 不同

必须用 node --inspect 启动 + attach 配置

不能靠 runtimeExecutable: "npm" 或 "next dev" 直接 launch，必须让 Next.js 自己暴露 inspector 端口，再由 VSCode 主动 attach。这是唯一稳定兼容 App Router 和 Pages Router 的方式。

• 改 package.json 的 dev 脚本为："dev": "next dev --inspect=9229"
• 如果用 pnpm，路径可能需调整：pnpm exec next dev --inspect=9229
• 确保 next.config.js 开启 source map：experimental: { sourceMaps: true }（Next.js 13.4+）
• 启动顺序：先终端运行 npm run dev，再在 VSCode 里选调试配置并启动

launch.json 的关键字段不能错

launch.json 里几个字段稍有偏差，断点就失效。尤其注意 localRoot 和 remoteRoot 必须一致，Next.js 的 source map 是相对路径生成的，不配这个，VSCode 根本找不到原始 TSX 文件。

• "type": "node"（不是 pwa-node，新版已弃用）
• "request": "attach"（不是 launch）
• "port": 9229（必须和 --inspect 参数值一致）
• "localRoot": "${workspaceFolder}" 和 "remoteRoot": "${workspaceFolder}" 严格相等
• "skipFiles": ["<node_internals>/**"]（避免断点卡进 Node 内部代码）

TSX 文件断点灰掉？检查 sourcemap 和文件后缀匹配

即使 attach 成功，.server.tsx 或 route.ts 里的断点仍可能灰掉，常见原因是 source map 没生成或文件没被 ESLint/TS 编译流程覆盖。

• 确认 .next/server/app/xxx/page.js 旁边有同名 .map 文件；没有就说明 sourceMaps: true 没生效
• TSX 文件要被识别，需在 eslint.config.js 的 files 里显式包含：["**/*.ts", "**/*.tsx", "**/*.server.tsx", "**/*.client.tsx"]
• 修改后删掉 .next 目录再重启 dev server，旧缓存会导致 sourcemap 错位
• 状态栏右下角看到 “ESLint” 字样，才说明当前文件被正确加载；没显示就是 files 不匹配

最易忽略的一点：热重载时进程会重启，但 VSCode 默认不会自动重连。务必在 launch.json 里加 "restart": true，否则改一行代码保存后，断点立刻失效。