如何在 Next.js 中使用调试工具

本文档解释了如何使用 VS Code 调试器、Chrome 开发者工具或 Firefox 开发者工具调试您的 Next.js 前端和后端代码，并支持完整的源映射。

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

使用 VS Code 调试

在项目根目录下创建一个名为 .vscode/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://:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

注意：要在 VS Code 中使用 Firefox 调试，您需要安装 Firefox Debugger 扩展。

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

在“Next.js: debug full stack”配置中，serverReadyAction.action 指定了当服务器就绪时打开哪个浏览器。debugWithEdge 表示启动 Edge 浏览器。如果您使用的是 Chrome，请将此值更改为 debugWithChrome。

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

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

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

点击运行时配置的下拉菜单，然后点击 Edit Configurations...。创建一个 JavaScript Debug 调试配置，并将 https://:3000 作为 URL。根据您的喜好进行自定义（例如，用于调试的浏览器，保存为项目文件），然后点击 OK。运行此调试配置，所选浏览器应自动打开。此时，您应该有两个应用程序处于调试模式：NextJS node 应用程序和客户端/浏览器应用程序。

使用浏览器开发者工具调试

客户端代码

通过运行 next dev、npm run dev 或 yarn dev 启动您的开发服务器。服务器启动后，在您喜欢的浏览器中打开 https://:3000（或您的备用 URL）。

对于 Chrome

打开 Chrome 的开发者工具（Windows/Linux 上为 Ctrl+Shift+J，macOS 上为 ⌥+⌘+I）
转到Sources（源代码）选项卡

对于 Firefox

打开 Firefox 的开发者工具（Windows/Linux 上为 Ctrl+Shift+I，macOS 上为 ⌥+⌘+I）
转到Debugger（调试器）选项卡

在任何浏览器中，只要您的客户端代码到达 debugger 语句，代码执行将暂停，并且该文件将出现在调试区域。您还可以搜索文件以手动设置断点。

在 Chrome 中：Windows/Linux 上按 Ctrl+P，macOS 上按 ⌘+P
在 Firefox 中：Windows/Linux 上按 Ctrl+P，macOS 上按 ⌘+P，或使用左侧面板中的文件树

请注意，搜索时，您的源文件路径将以 webpack://_N_E/./ 开头。

React 开发者工具

对于 React 特定的调试，请安装 React 开发者工具浏览器扩展。这个基本工具可以帮助您：

检查 React 组件
编辑 props 和 state
识别性能问题

服务器端代码

要使用浏览器开发者工具调试服务器端 Next.js 代码，您需要向底层 Node.js 进程传递 --inspect 标志。

NODE_OPTIONS='--inspect' next dev

温馨提示：使用 NODE_OPTIONS='--inspect=0.0.0.0' 可以允许在 localhost 之外进行远程调试访问，例如在 Docker 容器中运行应用程序时。

如果您正在使用 npm run dev 或 yarn dev，那么您应该更新 package.json 中的 dev 脚本。

{
  "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://:3000

对于 Chrome

打开一个新标签页并访问 chrome://inspect
点击 Configure... 确保所有调试端口都已列出
如果尚未存在，请添加 localhost:9229 和 localhost:9230
在 Remote Target 部分查找您的 Next.js 应用程序
点击 inspect 打开一个独立的开发者工具窗口
转到Sources（源代码）选项卡

对于 Firefox

打开新标签页并访问 about:debugging
点击左侧边栏中的 This Firefox
在 Remote Targets 下，找到您的 Next.js 应用程序
点击 Inspect 打开调试器
转到Debugger（调试器）选项卡

服务器端代码的调试方式与客户端调试类似。搜索文件（Ctrl+P/⌘+P）时，您的源文件路径将以 webpack://{application-name}/./ 开头（其中 {application-name} 将根据您的 package.json 文件替换为您的应用程序名称）。

使用浏览器开发者工具检查服务器错误

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

Next.js 将在错误叠加层上的 Next.js 版本指示器下方显示一个 Node.js 图标。点击该图标，开发者工具 URL 将复制到剪贴板。您可以打开一个新浏览器标签页，使用该 URL 来检查 Next.js 服务器进程。

在 Windows 上调试

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

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

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

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