如何让Next.js调试更高效精准？

我从Next.js VSCode调试页面获取了如下launch.json配置：

{
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

运行全栈调试选项后，Next.js启动方式与普通npm run dev一致，但调试效果不佳。我已在调试终端开启捕获异常断点，在Python项目中VSCode会精准停在异常发生的代码行并给出清晰错误，但Next.js的断点会指向Next.js源码中复杂的通用错误，比如某次Axios请求的Promise拒绝错误，断点指向了\node_modules\next\dist\server\dev\on-demand-entry-handler.js的202行，这对我毫无帮助。如何优化Next.js调试，使其能定位到我编写的代码并给出清晰易懂的错误？

1. 调整launch.json配置，跳过外部代码 #

修改全栈调试配置，加入skipFiles字段，直接跳过node_modules和Node.js内部代码，只聚焦业务代码：

{
  "configurations": [
    // 保留原有其他配置
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      },
      "skipFiles": [
        "<node_internals>/**",
        "${workspaceFolder}/node_modules/**/*"
      ]
    }
  ]
}

2. 启用"仅我的代码"模式 #

在VSCode调试面板的控制栏中，勾选**仅我的代码（Just My Code）**选项。该模式会自动过滤第三方库和框架的代码，让断点直接停在你编写的业务代码异常位置。

3. 手动捕获异步异常并明确抛出 #

对于Axios这类异步请求，不要让Promise拒绝被Next.js内部机制拦截，在业务代码中手动处理异常并抛出明确信息：

// 示例API请求代码
async function fetchData() {
  try {
    const response = await axios.get('/api/data');
    return response.data;
  } catch (error) {
    // 自定义错误信息，或直接抛出原始错误的关键内容
    throw new Error(`数据请求失败: ${error.response?.data?.message || error.message}`);
  }
}

这样调试时，断点会直接停在你抛出错误的代码行，而非Next.js内部处理逻辑。

4. 确保源码映射配置正确 #

在next.config.js中显式启用完整源码映射，保证调试时能准确映射到原始业务代码：

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  devtool: 'source-map' // 强制使用source-map，提升源码映射精度
};

module.exports = nextConfig;

5. 拆分客户端与服务端调试 #

如果异常明确发生在客户端，单独使用"Next.js: debug client-side"配置调试；若为服务端异常，使用"Next.js: debug server-side"配置。分开调试可减少干扰，精准定位问题。

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