Next.js服务端代码调试故障：断点未绑定、无源码，如何解决？

一、VS Code「Next.js: debug server-side」断点不触发（灰色未绑定） #

这个问题大概率是服务端source map未启用，或者调试配置和Next.js 15版本不兼容，按以下步骤修复：

• 编辑next.config.js，强制开启服务端source map：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    serverSourceMaps: true, // 关键配置：启用服务端源码映射
    productionBrowserSourceMaps: true,
  };
  
  module.exports = nextConfig;
  

• 更新VS Code的.vscode/launch.json配置，适配Next.js 15：

  {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Next.js: Debug Server-Side",
        "type": "node",
        "request": "launch",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run", "dev"],
        "env": {
          "NODE_OPTIONS": "--inspect=0.0.0.0:9229",
          "NEXT_DEBUG_SERVER_SIDE": "true"
        },
        "port": 9229,
        "skipFiles": ["<node_internals>/**"]
      }
    ]
  }
  

• 重启VS Code和开发服务，注意断点要设置在服务端执行的代码块里：比如App Router的async function Page()（默认是服务端组件），或者getServerSideProps这类服务端专属逻辑中，不要加'use client'指令，否则代码会跑到客户端执行。

二、「Next.js: debug full stack」启动报错 #

默认的全栈调试配置和Node v23/Next.js 15的新版本存在兼容性问题，直接改用拆分的端调试方案：

• 删除默认的full stack配置，在launch.json中保留服务端调试配置，再添加客户端调试配置：

  {
    "name": "Next.js: Debug Client-Side",
    "type": "chrome",
    "request": "launch",
    "url": "http://localhost:3000",
    "webRoot": "${workspaceFolder}"
  }
  

• 调试时先启动服务端调试，再启动客户端调试，即可实现全栈断点调试。

三、Chrome DevTools找不到webpack://源码 #

Next.js 15默认用Turbopack打包，或者source map路径映射逻辑变化，导致webpack://目录消失，按以下处理：

• 临时禁用Turbopack，修改package.json的dev脚本：

  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev --no-turbopack"
  }
  

• 确保next.config.js已开启serverSourceMaps，重启服务后，在Chrome DevTools的Sources面板，直接展开file://下的项目根目录查找源码，而不是找webpack://。
• 如果还是找不到，按Ctrl+P（Windows）/Cmd+P（Mac）直接输入文件名（比如page.tsx），快速定位源码。

额外注意事项 #

• Node v23是开发预览版，存在未知兼容性风险，建议降级到LTS版本（如v20.x），这是Next.js官方推荐的Node版本。
• 运行npm install重新安装依赖，确保Next.js 15和React 19的依赖版本完全匹配，避免潜在冲突。

内容的提问来源于stack exchange，提问作者user3057544