Skip to main content

调试

本文档解释了如何使用 VS Code 调试器、Chrome 开发工具 或 Firefox DevTools 调试具有完整源映射支持的 Next.js 前端和后端代码。

¥This documentation explains how you can debug your Next.js frontend and backend code with full source maps support using the VS Code debugger, Chrome DevTools, or Firefox DevTools.

任何可以附加到 Node.js 的调试器也可以用于调试 Next.js 应用。你可以在 Node.js 调试指南 中找到更多详细信息。

¥Any debugger that can attach to Node.js can also be used to debug a Next.js application. You can find more details in the Node.js Debugging Guide.

使用 VS Code 进行调试​

¥Debugging with VS Code

在项目的根目录下创建一个名为 .vscode/launch.json 的文件，其中包含以下内容：

¥Create a file named .vscode/launch.json at the root of your project with the following content:

{
  "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 client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost: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 调试器扩展。

¥Note: To use Firefox debugging in VS Code, you'll need to install the Firefox Debugger extension.

如果你使用的是 Yarn，则 npm run dev 可以替换为 yarn dev；如果你使用的是 pnpm，则可以替换为 pnpm dev。

¥npm run dev can be replaced with yarn dev if you're using Yarn or pnpm dev if you're using pnpm.

如果你的应用启动于 更改端口号，请将 http://localhost:3000 中的 3000 替换为你正在使用的端口。

¥If you're changing the port number your application starts on, replace the 3000 in http://localhost:3000 with the port you're using instead.

如果你从根目录以外的目录运行 Next.js（例如，如果你使用 Turborepo），则需要将 cwd 添加到服务器端和全堆栈调试任务。例如，"cwd": "${workspaceFolder}/apps/web"。

¥If you're running Next.js from a directory other than root (for example, if you're using Turborepo) then you need to add cwd to the server-side and full stack debugging tasks. For example, "cwd": "${workspaceFolder}/apps/web".

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

¥Now go to the Debug panel (Ctrl+Shift+D on Windows/Linux, ⇧+⌘+D on macOS), select a launch configuration, then press F5 or select Debug: Start Debugging from the Command Palette to start your debugging session.

使用 Jetbrains WebStorm 中的调试器​

¥Using the Debugger in Jetbrains WebStorm

单击列出运行时配置的下拉菜单，然后单击 Edit Configurations...。使用 http://localhost:3000 作为 URL 创建 JavaScript Debug 调试配置。根据你的喜好进行自定义（例如用于调试的浏览器、存储为项目文件），然后单击 OK。运行此调试配置，所选浏览器应自动打开。此时，你应该有 2 个应用处于调试模式：NextJS 节点应用和客户端/浏览器应用，remark 和 rehype 插件暂时无法与 一起使用。

¥Click the drop down menu listing the runtime configuration, and click Edit Configurations.... Create a JavaScript Debug debug configuration with http://localhost:3000 as the URL. Customize to your liking (e.g. Browser for debugging, store as project file), and click OK. Run this debug configuration, and the selected browser should automatically open. At this point, you should have 2 applications in debug mode: the NextJS node application, and the client/browser application.

使用浏览器 DevTools 进行调试​

¥Debugging with Browser DevTools

客户端代码​

¥Client-side code

通过运行 next dev、npm run dev 或 yarn dev 像平常一样启动开发服务器。服务器启动后，在你首选的浏览器中打开 http://localhost:3000（或你的备用 URL）。

¥Start your development server as usual by running next dev, npm run dev, or yarn dev. Once the server starts, open http://localhost:3000 (or your alternate URL) in your preferred browser.

对于 Chrome：

¥For Chrome:

  • 打开 Chrome 的开发者工具（Windows/Linux 上为 Ctrl+Shift+J，macOS 上为 ⌥+⌘+I）

    ¥Open Chrome's Developer Tools (Ctrl+Shift+J on Windows/Linux, ⌥+⌘+I on macOS)

  • 转到“源”选项卡

    ¥Go to the Sources tab

对于 Firefox：

¥For Firefox:

  • 打开 Firefox 的开发者工具（Windows/Linux 上为 Ctrl+Shift+I，macOS 上为 ⌥+⌘+I）

    ¥Open Firefox's Developer Tools (Ctrl+Shift+I on Windows/Linux, ⌥+⌘+I on macOS)

  • 转到“调试器”选项卡

    ¥Go to the Debugger tab

在任一浏览器中，只要你的客户端代码到达 debugger 语句，代码执行就会暂停，并且该文件将出现在调试区域中。你也可以搜索文件来手动设置断点：

¥In either browser, any time your client-side code reaches a debugger statement, code execution will pause and that file will appear in the debug area. You can also search for files to set breakpoints manually:

  • 在 Chrome 中：在 Windows/Linux 上按 Ctrl+P 或在 macOS 上按 ⌘+P

    ¥In Chrome: Press Ctrl+P on Windows/Linux or ⌘+P on macOS

  • 在 Firefox 中：在 Windows/Linux 上按 Ctrl+P 或在 macOS 上按 ⌘+P，或使用左侧面板中的文件树

    ¥In Firefox: Press Ctrl+P on Windows/Linux or ⌘+P on macOS, or use the file tree in the left panel

请注意，在搜索时，你的源文件的路径将以 webpack://_N_E/./ 开头。

¥Note that when searching, your source files will have paths starting with webpack://_N_E/./.

服务器端代码​

¥Server-side code

要使用浏览器 DevTools 调试服务器端 Next.js 代码，你需要将 --inspect 标志传递给底层 Node.js 进程：

¥To debug server-side Next.js code with browser DevTools, you need to pass the --inspect flag to the underlying Node.js process:

NODE_OPTIONS='--inspect' next dev

很高兴知道：使用 NODE_OPTIONS='--inspect=0.0.0.0' 允许在本地主机之外进行远程调试访问，例如在 Docker 容器中运行应用时。

¥Good to know: Use NODE_OPTIONS='--inspect=0.0.0.0' to allow remote debugging access outside localhost, such as when running the app in a Docker container.

如果你使用的是 npm run dev 或 yarn dev，那么你应该更新 package.json 上的 dev 脚本：

¥If you're using npm run dev or yarn dev then you should update the dev script on your package.json:

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

使用 --inspect 标志启动 Next.js 开发服务器将如下所示：

¥Launching the Next.js dev server with the --inspect flag will look something like this:

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

对于 Chrome：

¥For Chrome:

  1. 打开新标签页并访问 chrome://inspect

    ¥Open a new tab and visit chrome://inspect

  2. 在远程目标部分中查找你的 Next.js 应用

    ¥Look for your Next.js application in the Remote Target section

  3. 单击“检查”以打开单独的 DevTools 窗口

    ¥Click inspect to open a separate DevTools window

  4. 转到“源”选项卡

    ¥Go to the Sources tab

对于 Firefox：

¥For Firefox:

  1. 打开新标签页并访问 about:debugging

    ¥Open a new tab and visit about:debugging

  2. 单击左侧边栏中的“此 Firefox”

    ¥Click This Firefox in the left sidebar

  3. 在远程目标下，找到你的 Next.js 应用

    ¥Under Remote Targets, find your Next.js application

  4. 单击“检查”以打开调试器

    ¥Click Inspect to open the debugger

  5. 转到“调试器”选项卡

    ¥Go to the Debugger tab

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

¥Debugging server-side code works similarly to client-side debugging. When searching for files (Ctrl+P/⌘+P), your source files will have paths starting with webpack://{application-name}/./ (where {application-name} will be replaced with the name of your application according to your package.json file).

使用浏览器 DevTools 检查服务器错误​

¥Inspect Server Errors with Browser DevTools

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

¥When you encounter an error, inspecting the source code can help trace the root cause of errors.

Next.js 将在开发覆盖层上显示一个 Node.js 徽标，就像一个绿色按钮。单击该按钮后，DevTools URL 将被复制到剪贴板。你可以使用该 URL 打开新的浏览器选项卡来检查 Next.js 服务器进程。

¥Next.js will display a Node.js logo like a green button on the dev overlay. By clicking that button, the DevTools URL is copied to your clipboard. You can open a new browser tab with that URL to inspect the Next.js server process.

在 Windows 上调试​

¥Debugging on Windows

Windows 用户在使用 NODE_OPTIONS='--inspect' 时可能会遇到问题，因为 Windows 平台不支持该语法。要解决此问题，请安装 cross-env 包作为开发依赖（-D 与 npm 和 yarn），并将 dev 脚本替换为以下内容。

¥Windows users may run into an issue when using NODE_OPTIONS='--inspect' as that syntax is not supported on Windows platforms. To get around this, install the cross-env package as a development dependency (-D with npm and yarn) and replace the dev script with the following.

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

无论你使用哪个平台（包括 Mac、Linux 和 Windows），cross-env 都会设置 NODE_OPTIONS 环境变量，并允许你跨设备和操作系统进行一致的调试。

¥cross-env will set the NODE_OPTIONS environment variable regardless of which platform you are on (including Mac, Linux, and Windows) and allow you to debug consistently across devices and operating systems.

很高兴知道：确保你的计算机上禁用了 Windows Defender。该外部服务将检查读取的每个文件，据报告这会大大增加 next dev 的快速刷新时间。这是一个已知问题，与 Next.js 无关，但它确实影响 Next.js 开发。

¥Good to know: Ensure Windows Defender is disabled on your machine. This external service will check every file read, which has been reported to greatly increase Fast Refresh time with next dev. This is a known issue, not related to Next.js, but it does affect Next.js development.

更多信息​

¥More information

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

¥To learn more about how to use a JavaScript debugger, take a look at the following documentation: