跳到内容

调试

本文档解释了如何使用 VS Code 调试器Chrome DevToolsFirefox 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 client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://127.0.0.1:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "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}"
      }
    }
  ]
}

注意:要在 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://127.0.0.1:3000 中的 3000 替换为你正在使用的端口。

如果你的 Next.js 是从根目录以外的目录运行的(例如,如果你正在使用 Turborepo),那么你需要将 cwd 添加到服务器端和全栈调试任务中。例如,"cwd": "${workspaceFolder}/apps/web"

现在转到调试面板(Windows/Linux 上为 Ctrl+Shift+D,macOS 上为 ⇧+⌘+D),选择一个启动配置,然后按 F5 或从命令面板中选择 调试:开始调试 以启动调试会话。

在 Jetbrains WebStorm 中使用调试器

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

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

客户端代码

像往常一样运行 next devnpm run devyarn dev 来启动你的开发服务器。服务器启动后,在首选浏览器中打开 https://127.0.0.1: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/./ 开头。

服务器端代码

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

终端
NODE_OPTIONS='--inspect' next dev

须知:使用 NODE_OPTIONS='--inspect=0.0.0.0' 以允许从 localhost 外部进行远程调试访问,例如在 Docker 容器中运行应用程序时。

如果你正在使用 npm run devyarn 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

  1. 打开一个新标签页并访问 chrome://inspect
  2. 点击 Configure... 以确保列出了两个调试端口
  3. 添加 localhost:9229localhost:9230,如果它们尚未存在
  4. Remote Target 部分查找你的 Next.js 应用程序
  5. 点击 inspect 以打开一个单独的 DevTools 窗口
  6. 转到 Sources 选项卡

对于 Firefox

  1. 打开一个新标签页并访问 about:debugging
  2. 点击左侧边栏中的 This Firefox
  3. Remote Targets 下,找到你的 Next.js 应用程序
  4. 点击 Inspect 以打开调试器
  5. 转到 Debugger 选项卡

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

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

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

Next.js 将在错误叠加层上的 Next.js 版本指示器下方显示一个 Node.js 图标。通过单击该图标,DevTools URL 将复制到你的剪贴板。你可以使用该 URL 打开一个新的浏览器标签页,以检查 Next.js 服务器进程。

在 Windows 上调试

Windows 用户在使用 NODE_OPTIONS='--inspect' 时可能会遇到问题,因为 Windows 平台不支持该语法。为了解决这个问题,请安装 cross-env 包作为开发依赖项(npmyarn 使用 -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 开发。

更多信息

要了解有关如何使用 JavaScript 调试器的更多信息,请查看以下文档