vscode 默认无法调试 next.js 服务端逻辑，因 dev server 主进程仅为调度器，真实代码运行在未启用 inspector 的子进程中且 source map 路径映射失败；需在 package.json 中添加 --inspect=9229 参数，并配置 launch.json 使用 attach 模式、匹配 localroot/remoteroot、启用 sourcemaps 和 restart，同时在 next.config.js 中开启 experimental.sourcemaps。
VSCode 默认不支持直接调试 Next.js 服务端逻辑（比如 getServerSideProps、API Routes 或 Server Actions），因为 Next.js 13+ 的 dev server 启动的是一个包装进程，真实业务代码运行在动态 fork 的子进程中——你 attach 到主进程，断点自然不生效。
为什么 next dev 启动后断点不命中
常见现象是断点显示为空心圆，hover 提示 “Breakpoint ignored because generated code not found”。根本原因有三个：
- Next.js 主进程只是调度器，
getServerSideProps和 API Route 实际跑在内部 worker 进程里 - 默认没开启 inspector，VSCode 没端口可连
- source map 路径映射失败，调试器找不到原始 TS/JS 文件位置
必须改 package.json 的 dev 脚本加 --inspect
不能只靠 launch.json 配置，得让 Next.js 自己暴露调试端口。编辑 package.json：
"scripts": {
"dev": "next dev --inspect=9229"
}
说明：
-
--inspect=9229是最简方式，比--inspect-brk更适合日常迭代（后者会卡在第一行） - 如果 9229 被占用，换成
--inspect=0.0.0.0:9230，同时同步改launch.json的port - pnpm 用户注意：
pnpm run dev也能识别该参数，无需手动拼路径
launch.json 必须用 attach 模式且配对 localRoot/remoteRoot
新建 .vscode/launch.json，内容如下：
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "Attach to Next.js",
"port": 9229,
"address": "localhost",
"localRoot": "${workspaceFolder}",
"remoteRoot": "${workspaceFolder}",
"sourceMaps": true,
"skipFiles": ["<node_internals>/**"],
"restart": true
}
]
}</node_internals>
关键点：
-
request必须是attach，不是launch——next dev是长期进程，不是单次脚本 -
localRoot和remoteRoot必须一致，否则 source map 映射失败（Next.js 生成的 sourcemap 是相对路径） -
restart: true不可省：热重载会重启 worker 进程，没它断点就失效
别漏掉 next.config.js 的 sourceMaps 开关
Next.js 13.4+ 需显式启用 source map 支持，否则即使连上了也找不到源码上下文。在 next.config.js 中加：
module.exports = {
experimental: {
sourceMaps: true
}
}
注意：
- 这个配置只影响
.next/目录下生成的 source map 文件，不改变运行时行为 - 旧版 Next.js（devtool: 'source-map'，但已不推荐
- 改完要重启
npm run dev，否则缓存的.next/里没新 map
真正容易被忽略的是：启动顺序和进程归属。必须先执行 npm run dev，等终端出现 event - compiled client and server successfully 再点 VSCode 的 ▶️ 启动调试；断点只能打在服务端文件里（如 pages/api/hello.ts 或 app/page.tsx 中的 export async function generateStaticParams()），打在纯客户端组件里不会触发 Node.js 调试器。
