{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
本文档解释了如何使用完整的源映射支持，通过 [VS Code 调试器](https://code.visualstudio.com/docs/editor/debugging)、[Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools) 或 [Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/) 来调试您的 Next.js 前端和后端代码。
任何可以附加到 Node.js 的调试器也可用于调试 Next.js 应用程序。您可以在 Node.js [调试指南](https://nodejs.org/en/docs/guides/debugging-getting-started/) 中找到更多详细信息。
## 使用 VS Code 调试
在项目根目录下创建一个名为 `.vscode/launch.json` 的文件，内容如下：
```json filename="launch.json"
{
"version": "0.2.0",
"configurations": [
{
"name": "Next.js: debug server-side",
"type": "node-terminal",
"request": "launch",
"command": "npm run dev -- --inspect"
},
{
"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/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 Debugger 扩展。
如果您使用 Yarn，npm run dev 可以替换为 yarn dev；如果您使用 pnpm，则替换为 pnpm dev。
在“Next.js: debug full stack”配置中，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 或从命令面板中选择 Debug: Start Debugging 来启动调试会话。
单击列出运行时配置的下拉菜单，然后单击 Edit Configurations...。创建一个 URL 为 http://localhost:3000 的 JavaScript Debug 调试配置。根据您的喜好进行自定义（例如，用于调试的浏览器，存储为项目文件），然后单击 OK。运行此调试配置，所选浏览器应自动打开。此时，您应该有两个处于调试模式的应用程序：Next.js Node 应用程序和客户端/浏览器应用程序。
像往常一样，通过运行 next dev、npm run dev 或 yarn dev 来启动您的开发服务器。服务器启动后，在您偏好的浏览器中打开 http://localhost:3000（或您的备用 URL）。
对于 Chrome：
Ctrl+Shift+J，macOS 上为 ⌥+⌘+I）对于 Firefox：
Ctrl+Shift+I，macOS 上为 ⌥+⌘+I）在任一浏览器中，每当您的客户端代码到达 debugger 语句时，代码执行将暂停，并且该文件将出现在调试区域。您还可以搜索文件来手动设置断点：
Ctrl+P，在 macOS 上按 ⌘+PCtrl+P，在 macOS 上按 ⌘+P，或使用左侧面板中的文件树请注意，在搜索时，您的源文件路径将以 webpack://_N_E/./ 开头。
对于 React 特定的调试，请安装 React 开发者工具 浏览器扩展。这个重要的工具可以帮助您：
要使用浏览器 DevTools 调试 Next.js 服务器端代码，您需要传递 --inspect 标志：
next dev --inspect--inspect 的值会传递给底层的 Node.js 进程。查看 --inspect 文档了解高级用例。
须知：使用
--inspect=0.0.0.0允许在 localhost 之外进行远程调试访问，例如在 Docker 容器中运行应用程序时。
使用 --inspect 标志启动 Next.js 开发服务器将显示如下内容：
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对于 Firefox：
about:debugging服务器端代码的调试方式与客户端调试类似。在搜索文件（Ctrl+P/⌘+P）时，您的源文件路径将以 webpack://{application-name}/./ 开头（其中 {application-name} 将根据您的 package.json 文件中的应用程序名称进行替换）。
要使用 --inspect-brk 或 --inspect-wait，您必须改为指定 NODE_OPTIONS。例如 NODE_OPTIONS=--inspect-brk next dev。
当您遇到错误时，检查源代码有助于追溯错误的根本原因。
Next.js 会在错误覆盖层上，Next.js 版本指示器下方显示一个 Node.js 图标。单击该图标，DevTools URL 将被复制到剪贴板。您可以使用该 URL 打开新的浏览器标签页来检查 Next.js 服务器进程。
确保您的机器上已禁用 Windows Defender。据报告，此外部服务会检查 每次文件读取，这会大大增加使用 next dev 时的快速刷新时间。这是一个已知问题，与 Next.js 无关，但确实会影响 Next.js 的开发。
要了解有关如何使用 JavaScript 调试器的更多信息，请查阅以下文档：