调试 | Next.js - 简体中文

本文档介绍如何通过 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-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

如果使用 Yarn 或 pnpm，可将 npm run dev 替换为 yarn dev 或 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 开始调试会话。

在 Jetbrains WebStorm 中使用调试器

点击运行时配置的下拉菜单，选择 Edit Configurations...。创建一个 Javascript Debug 调试配置，URL 设置为 http://localhost:3000。根据需要自定义（例如选择调试浏览器、存储为项目文件等），然后点击 OK。运行此调试配置，所选浏览器将自动打开。此时您应该有两个处于调试模式的应用：NextJS 节点应用和客户端/浏览器应用。

使用 Chrome DevTools 调试

客户端代码

像往常一样通过运行 next dev、npm run dev 或 yarn dev 启动开发服务器。服务器启动后，在 Chrome 中打开 http://localhost:3000（或您的替代 URL）。接着打开 Chrome 开发者工具（Windows/Linux 按 Ctrl+Shift+J，macOS 按 ⌥+⌘+I），然后转到 Sources 标签页。

当客户端代码执行到 debugger 语句时，代码执行将暂停，该文件会出现在调试区域。您也可以按 Ctrl+P（Windows/Linux）或 ⌘+P（macOS）搜索文件并手动设置断点。注意搜索时，源文件路径将以 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

注意：运行 NODE_OPTIONS='--inspect' npm run dev 或 NODE_OPTIONS='--inspect' yarn dev 无效。这会尝试在同一端口启动多个调试器：一个用于 npm/yarn 进程，一个用于 Next.js。控制台将显示类似 Starting inspector on 127.0.0.1:9229 failed: address already in use 的错误。

服务器启动后，在 Chrome 中打开新标签页并访问 chrome://inspect，您应该在 Remote Target 部分看到 Next.js 应用。点击应用下方的 inspect 打开单独的 DevTools 窗口，然后转到 Sources 标签页。

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

在 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 开发。

调试