Debugging

本文档说明了如何使用 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": "http://localhost: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。

如果你更改了应用程序启动的端口号，需要将 http://localhost:3000 中的 3000 替换为你使用的端口。

如果你不是在根目录运行 Next.js (比如你在使用 Turborepo)，那么你需要在服务端和全栈调试任务中添加 cwd。例如，"cwd": "${workspaceFolder}/apps/web"。

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

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

使用 Chrome DevTools 调试

客户端代码

像往常一样通过运行 next dev、npm run dev 或 yarn dev 启动开发服务器。服务器启动后，在 Chrome 中打开 http://localhost: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 代码，你需要给底层的 Node.js 进程传递 --inspect 标志：

Terminal

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 开发服务器时，会看到类似这样的输出：

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，你应该能在 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 开发。