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

本文档介绍如何通过支持完整源码映射的 VS Code 调试器、Chrome DevTools 或 Firefox DevTools 调试 Next.js 的前后端代码。

任何能附加到 Node.js 的调试器也可用于调试 Next.js 应用。更多细节请参阅 Node.js 调试指南。

使用 VS Code 调试

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

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: 调试服务端",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: 调试客户端",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: 调试客户端 (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: 全栈调试",
      "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 调试器扩展。

如果使用 Yarn 可将 npm run dev 替换为 yarn dev，使用 pnpm 则替换为 pnpm dev。

在 "Next.js: 全栈调试" 配置中，serverReadyAction.action 指定服务器就绪时打开的浏览器。debugWithEdge 表示启动 Edge 浏览器。若使用 Chrome，请将此值改为 debugWithChrome。

如果更改了应用启动端口，请将 http://localhost:3000 中的 3000 替换为您使用的端口。

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

现在转到调试面板（Windows/Linux 按 Ctrl+Shift+D，macOS 按 ⇧+⌘+D），选择启动配置后按 F5 或从命令面板选择 调试: 启动调试 开始调试会话。

在 Jetbrains WebStorm 中使用调试器

点击运行时配置下拉菜单，选择 编辑配置...。创建 JavaScript 调试 配置，URL 设为 http://localhost:3000。按需自定义（如调试用浏览器、存储为项目文件等），点击 确定。运行此调试配置，所选浏览器将自动打开。此时应有两个应用处于调试模式：NextJS 节点应用和客户端/浏览器应用。

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

客户端代码

通过运行 next dev、npm run dev 或 yarn dev 启动开发服务器。服务器启动后，在首选浏览器中打开 http://localhost:3000（或您的替代 URL）。

Chrome 操作：

打开开发者工具（Windows/Linux 按 Ctrl+Shift+J，macOS 按 ⌥+⌘+I）
切换到 Sources 标签页

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/./ 开头。

服务端代码

要通过浏览器开发者工具调试服务端代码，需向 Node.js 进程传递 --inspect 标志：

Terminal

NODE_OPTIONS='--inspect' next dev

须知：使用 NODE_OPTIONS='--inspect=0.0.0.0' 可允许远程调试访问（如 Docker 容器中运行应用时）。

如果使用 npm run dev 或 yarn dev，需更新 package.json 中的 dev 脚本：

package.json

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

带 --inspect 标志启动 Next.js 开发服务器时输出示例：

Terminal

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

Chrome 操作：

新建标签页访问 chrome://inspect
点击 配置... 确保列出两个调试端口
添加 localhost:9229 和 localhost:9230（如未存在）
在 远程目标 部分找到 Next.js 应用
点击 inspect 打开独立开发者工具窗口
切换到 Sources 标签页

Firefox 操作：

新建标签页访问 about:debugging
左侧边栏点击 此 Firefox
远程目标 下找到 Next.js 应用
点击检查打开调试器
切换到 Debugger 标签页

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

通过浏览器开发者工具检查服务端错误

遇到错误时，检查源代码有助于追踪根本原因。

Next.js 会在错误覆盖层上 Next.js 版本指示器下方显示 Node.js 图标。点击该图标会将开发者工具 URL 复制到剪贴板。您可在新浏览器标签页中打开该 URL 检查 Next.js 服务进程。

Windows 调试

Windows 用户使用 NODE_OPTIONS='--inspect' 时可能遇到语法不支持问题。解决方案是安装 cross-env 作为开发依赖（npm 和 yarn 使用 -D），并替换 dev 脚本如下：

package.json

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

cross-env 会跨平台（包括 Mac、Linux 和 Windows）设置 NODE_OPTIONS 环境变量，确保在不同设备和操作系统上调试一致。

须知：请确保关闭 Windows Defender。该外部服务会检查每个读取的文件，已知会显著增加 next dev 的快速刷新时间。此问题与 Next.js 无关，但会影响 Next.js 开发体验。