调试
本文档介绍了如何使用 VS Code 调试器、Chrome DevTools 或 Firefox DevTools,通过完整的源地图支持来调试你的 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"
},
{
"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 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 或从命令面板中选择 “调试:开始调试” 以启动你的调试会话。
在 Jetbrains WebStorm 中使用调试器
点击列出运行时配置的下拉菜单,然后点击 “编辑配置...” 。创建一个 JavaScript Debug
调试配置,并将 http://localhost:3000
作为 URL。根据你的喜好进行自定义(例如,用于调试的浏览器,存储为项目文件),然后点击 “确定”。运行此调试配置,选定的浏览器应会自动打开。此时,你应该有两个处于调试模式的应用程序:NextJS 节点应用程序和客户端/浏览器应用程序。
使用浏览器开发者工具进行调试
客户端代码
像往常一样运行 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/./
开头。
服务端代码
要使用浏览器开发者工具调试服务端 Next.js 代码,你需要将 --inspect
标志传递给底层的 Node.js 进程。
NODE_OPTIONS='--inspect' next dev
须知:使用
NODE_OPTIONS='--inspect=0.0.0.0'
以允许在 localhost 之外进行远程调试访问,例如在 Docker 容器中运行应用程序时。
如果你正在使用 npm run dev
或 yarn dev
,那么你应该更新你的 package.json
中的 dev
脚本。
{
"scripts": {
"dev": "NODE_OPTIONS='--inspect' next dev"
}
}
使用 --inspect
标志启动 Next.js 开发服务器看起来会像这样
Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://node.org.cn/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
对于 Chrome
- 打开一个新标签页并访问
chrome://inspect
- 点击 Configure... 以确保列出了两个调试端口
- 如果
localhost:9229
和localhost:9230
尚未出现,请将它们都添加进去 - 在 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
文件)。
使用浏览器开发者工具检查服务器错误
当你遇到错误时,检查源代码可以帮助追踪错误的根本原因。
Next.js 将在错误覆盖层上的 Next.js 版本指示器下方显示一个 Node.js 图标。通过点击该图标,DevTools URL 将复制到你的剪贴板。你可以使用该 URL 打开一个新的浏览器标签页来检查 Next.js 服务器进程。
在 Windows 上调试
Windows 用户在使用 NODE_OPTIONS='--inspect'
时可能会遇到问题,因为 Windows 平台不支持该语法。为了解决这个问题,安装 cross-env
包作为开发依赖项(npm 和 yarn 使用 -D),并将 dev
脚本替换为以下内容。
{
"scripts": {
"dev": "cross-env NODE_OPTIONS='--inspect' next dev"
}
}
无论你使用哪个平台(包括 Mac、Linux 和 Windows),cross-env
都会设置 NODE_OPTIONS
环境变量,并允许你在设备和操作系统之间一致地进行调试。
须知:确保在你的机器上禁用 Windows Defender。此外部服务将检查*每个读取的文件*,据报告这会大大增加
next dev
的快速刷新时间。这是一个已知问题,与 Next.js 无关,但确实会影响 Next.js 开发。
更多信息
要了解有关如何使用 JavaScript 调试器的更多信息,请查看以下文档
这篇文章对您有帮助吗?