调试

本文档说明了如何使用 VS Code 调试器或 Chrome DevTools，并支持完整的源代码映射，来调试 Next.js 前端和后端代码。

任何可以附加到 Node.js 的调试器也可以用于调试 Next.js 应用程序。您可以在 Node.js 的调试指南中找到更多详细信息。

使用 VS Code 调试

在项目的根目录下创建一个名为 .vscode/launch.json 的文件，内容如下：

launch.json

{
  "version": "0.2.0",
  "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": "https://127.0.0.1:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

如果您使用的是 Yarn，则可以将 npm run dev 替换为 yarn dev，或者如果您使用的是 pnpm，则可以替换为 pnpm dev。

如果您正在更改应用程序启动的端口号，请将 https://127.0.0.1:3000 中的 3000 替换为您正在使用的端口。

如果您从根目录以外的目录运行 Next.js（例如，如果您使用的是 Turborepo），则需要将 cwd 添加到服务器端和完整堆栈调试任务中。例如，"cwd": "${workspaceFolder}/apps/web"。

现在转到调试面板（Windows/Linux 上为 Ctrl+Shift+D，macOS 上为 ⇧+⌘+D），选择一个启动配置，然后按 F5 或从命令面板中选择**调试：启动调试**以开始您的调试会话。

在 Jetbrains WebStorm 中使用调试器

单击列出运行时配置的下拉菜单，然后单击“编辑配置…”。创建一个 URL 为 https://127.0.0.1:3000 的“JavaScript 调试”调试配置。根据您的喜好进行自定义（例如，用于调试的浏览器，将其存储为项目文件），然后单击“确定”。运行此调试配置，选定的浏览器应自动打开。此时，您应该在调试模式下有两个应用程序：NextJS 节点应用程序和客户端/浏览器应用程序。

使用 Chrome DevTools 调试

客户端代码

像往常一样运行next dev、npm run dev或yarn dev启动开发服务器。服务器启动后，在 Chrome 中打开https://127.0.0.1:3000（或您的备用 URL）。接下来，打开 Chrome 的开发者工具（Windows/Linux 上按Ctrl+Shift+J，macOS 上按⌥+⌘+I），然后转到“**Sources**”选项卡。

现在，每当您的客户端代码到达debugger语句时，代码执行将暂停，该文件将出现在调试区域中。您也可以按 Windows/Linux 上的Ctrl+P或 macOS 上的⌘+P搜索文件并手动设置断点。请注意，在此处搜索时，您的源文件路径将以webpack://_N_E/./开头。

服务器端代码

要使用 Chrome DevTools 调试 Next.js 服务器端代码，您需要将--inspect标志传递给底层的 Node.js 进程。

终端

NODE_OPTIONS='--inspect' next dev

如果您使用的是npm run dev或yarn dev，则应更新package.json中的dev脚本。

package.json

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

使用--inspect标志启动 Next.js 开发服务器看起来像这样。

终端

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://node.org.cn/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://127.0.0.1:3000

服务器启动后，在 Chrome 中打开一个新标签页并访问chrome://inspect，您应该在“**Remote Target**”部分看到您的 Next.js 应用程序。单击应用程序下的“**inspect**”以打开一个单独的 DevTools 窗口，然后转到“**Sources**”选项卡。

在此处调试服务器端代码的工作方式与使用 Chrome DevTools 调试客户端代码非常相似，只是当您使用Ctrl+P或⌘+P搜索文件时，您的源文件路径将以webpack://{application-name}/./开头（其中{application-name}将替换为根据您的package.json文件确定的应用程序名称）。

使用 Chrome DevTools 检查服务器错误

遇到错误时，检查源代码可以帮助追踪错误的根本原因。

Next.js 将在开发覆盖层上显示一个类似绿色按钮的 Node.js 徽标。单击该按钮，Chrome DevTool URL 将复制到剪贴板，您可以使用该 URL 在新浏览器选项卡中打开并使用 Chrome DevTool 检查 Next.js 服务器进程。

在 Windows 上进行调试

Windows 用户在使用NODE_OPTIONS='--inspect'时可能会遇到问题，因为 Windows 平台不支持该语法。要解决此问题，请安装cross-env包作为开发依赖项（使用npm和yarn时使用-D），并使用以下内容替换dev脚本。

package.json

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

cross-env将设置NODE_OPTIONS环境变量，无论您使用的是哪个平台（包括 Mac、Linux 和 Windows），并允许您跨设备和操作系统一致地进行调试。

注意：确保在您的机器上禁用了 Windows Defender。此外部服务将检查每次文件读取，据报道这会大大增加使用next dev时的快速刷新时间。这是一个已知问题，与 Next.js 无关，但确实会影响 Next.js 开发。