如何配合 Next.js 使用调试工具
了解如何使用 VS Code、Chrome DevTools 或 Firefox DevTools 调试 Next.js 应用程序。
本文档说明如何使用 VS Code 调试器、Chrome DevTools 或 Firefox DevTools 在完整的 source maps 支持下调试 Next.js 前端和后端代码。
任何能够附加到 Node.js 的调试器也可用于调试 Next.js 应用程序。你可以在 Node.js 调试指南中找到更多细节。
使用 VS Code 调试#
在项目根目录创建一个名为 .vscode/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 调试器扩展。
如果你使用 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 来启动调试会话。
在 JetBrains WebStorm 中使用调试器#
点击列出运行时配置的下拉菜单,然后点击 Edit Configurations...。创建一个 JavaScript Debug 调试配置,将 http://localhost:3000 作为 URL。根据喜好进行自定义(例如用于调试的浏览器、存储为项目文件),然后点击 OK。运行此调试配置,所选浏览器应会自动打开。此时,你应该有 2 个处于调试模式的应用程序:Next.js node 应用程序和客户端/浏览器应用程序。
使用浏览器 DevTools 调试#
客户端代码#
像往常一样运行 next dev、npm run dev 或 yarn dev 启动开发服务器。服务器启动后,在你喜欢的浏览器中打开 http://localhost:3000(或你的备用 URL)。
对于 Chrome:
- 打开 Chrome 的开发者工具(Windows/Linux 上为
Ctrl+Shift+J,macOS 上为⌥+⌘+I) - 转到 Sources 标签页
对于 Firefox:
- 打开 Firefox 的开发者工具(Windows/Linux 上为
Ctrl+Shift+I,macOS 上为⌥+⌘+I) - 转到 Debugger 标签页
在任一浏览器中,只要你的客户端代码执行到 debugger 语句,代码执行就会暂停,该文件会显示在调试区域。你还可以搜索文件以手动设置断点:
- 在 Chrome 中:在 Windows/Linux 上按
Ctrl+P,在 macOS 上按⌘+P - 在 Firefox 中:在 Windows/Linux 上按
Ctrl+P,在 macOS 上按⌘+P,或使用左侧面板中的文件树
请注意,搜索时,你的源文件路径将以 webpack://_N_E/./ 开头。
React 开发者工具#
对于特定于 React 的调试,请安装 React 开发者工具浏览器扩展。这个必备工具可帮助你:
- 检查 React 组件
- 编辑 props 和 state
- 发现性能问题
服务端代码#
要使用浏览器 DevTools 调试服务端 Next.js 代码,你需要传入 --inspect 标志:
pnpm dev --inspectnpm run dev -- --inspectyarn dev --inspectbun run 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/learn/getting-started/debugging
ready - started server on 0.0.0.0:3000, url: http://localhost:3000对于 Chrome:
- 打开一个新标签页并访问
chrome://inspect - 在 Remote Target 部分查找你的 Next.js 应用程序
- 点击 inspect 打开一个单独的 DevTools 窗口
- 转到 Sources 标签页
对于 Firefox:
- 打开一个新标签页并访问
about:debugging - 点击左侧边栏中的 This Firefox
- 在 Remote Targets 下找到你的 Next.js 应用程序
- 点击 Inspect 打开调试器
- 转到 Debugger 标签页
调试服务端代码的方式与客户端调试类似。搜索文件(Ctrl+P/⌘+P)时,你的源文件路径将以 webpack://{application-name}/./ 开头(其中 {application-name} 将根据 package.json 文件替换为你的应用程序名称)。
要使用 --inspect-brk 或 --inspect-wait,你必须改为指定 NODE_OPTIONS。例如 NODE_OPTIONS=--inspect-brk next dev。
使用浏览器 DevTools 检查服务端错误#
遇到错误时,检查源代码有助于追踪错误的根本原因。
Next.js 会在错误覆盖层上的 Next.js 版本指示器下方显示一个 Node.js 图标。点击该图标,DevTools 的 URL 会被复制到你的剪贴板。你可以用该 URL 打开一个新的浏览器标签页来检查 Next.js 服务器进程。
在 Windows 上调试#
确保你的机器上禁用了 Windows Defender。这项外部服务会检查每一次文件读取,据报道这会大幅增加 next dev 的 Fast Refresh 时间。这是一个已知问题,与 Next.js 无关,但确实会影响 Next.js 开发。
更多信息#
要了解有关如何使用 JavaScript 调试器的更多信息,请查看以下文档: