调试 | 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: 调试服务端",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: 调试客户端",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: 全栈调试",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

若使用 Yarn，可将 npm run dev 替换为 yarn dev。如果修改了应用的启动端口号，请将 http://localhost:3000 中的 3000 替换为您使用的端口。

现在转到调试面板（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 标签页。

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

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 开发体验。

调试