Debian中Node.js的调试技巧有哪些

Debian 下 Node.js 调试技巧

一 核心方法与快速上手

调试这事儿，最直接的方式，就是用 --inspect 或 --inspect-brk 这两个参数启动调试服务器。默认监听 9229 端口。两者的区别在于：前者启动后，程序会直接运行，等待调试器连接；后者则会在第一行代码处暂停，方便你从入口点开始断点调试。举个实际例子：node --inspect app.js 或 node --inspect-brk app.js。启动之后，你就可以在 Chrome DevTools 的 chrome://inspect 页面找到并连接它，或者在 VS Code 里通过“运行与调试”面板附加到这个端口。当然，如果喜欢更纯粹的命令行操作，直接用 node inspect app.js 也可以进行步进和断点控制。为了以后调试更顺手，建议把这些启动命令直接写到 package.json 的 scripts 里，比如 "debug": "node --inspect-brk app.js"，一劳永逸。

二 开发期高效工作流

在 VS Code 里，最核心的是配置好 .vscode/launch.json。这里有几种常用的配置：直接启动项目，用 { "type": "node", "request": "launch", "name": "Launch Program", "program": "${workspaceFolder}/app.js" }；如果项目已经在后台运行了，可以用 attach 模式连接它：{ "type": "node", "request": "attach", "name": "Attach", "port": 9229 }；另外还有一种比较高级的用法，调试那些通过 npm 脚本启动的项目，比如 Next.js：{ "type": "node", "request": "launch", "name": "Debug Next.js", "skipFiles": ["/**"], "command": "npm run dev" }。

对于需要频繁改代码的场景，配合 nodemon 做热重载调试是个好主意。在 nodemon.json 里配置 "exec": "node --inspect-brk src/your-script.js"，这样每次保存文件，程序就会自动重启并自动进入调试状态。另外，利用 debug 模块来输出命名空间日志也很有用。通过环境变量可以按需控制输出，比如 DEBUG=myapp:* node app.js 只打印 myapp 命名空间的日志，或者更精细地用 DEBUG=myapp:server,myapp:db node app.js 来只看某几个子模块的日志，避免在生产环境被海量日志刷屏。

三 远程与容器场景

远程调试其实思路和本地差不多。在目标 Debian 主机上，用 node --inspect-brk app.js 启动项目，确保调试端口（默认 9229）能从本地机器访问到，比如放行防火墙或安全组。然后在本地的 VS Code 里，使用 attach 配置，把 address 字段填上远程服务器的 IP，比如 "address": "192.0.2.10"。当然，Chrome DevTools 也能干这事儿，在 Connection 页面手动添加远程地址就行。如果代码跑在容器里，需要把容器的 9229 端口映射到宿主机，然后再用宿主机的地址去连接，效果一样。

四 生产问题定位与事后分析

线上出了问题，别指望靠几个 console.log 来排查。标准做法是用结构化日志库，比如 Pino 或 Winston，它们能控制不同环境下的输出级别，方便集中采集。对于偶发的崩溃问题，可以启用核心转储（core dump），然后用 llnode 这类工具在事后进行深入分析，能清晰地看到 Ja vaScript 堆栈和原生层对象的映射关系。当然，这个功能只在必要时才开启，避免过多的性能和磁盘压力。

五 常见问题与排查清单

平时调试时，总会遇到一些常见问题，这里整理了一份排查清单，对症下药：

• chrome://inspect 页面看不到目标进程 确认进程确实是以 --inspect 或 --inspect-brk 启动的，监听的是 9229 端口。本机和远程的话，要检查网络是否可达。如果还是找不到，可以直接在 DevTools 的 Connection 页面手动添加地址。
• 端口被占用 用 lsof -iTCP:9229 -sTCP:LISTEN 看看是不是已经有别的 Node 调试进程占用了 9229。如果冲突了，杀掉旧进程，或者换个端口启动，比如 --inspect=9230。
• 断点不生效 检查 VS Code 的运行配置和文件路径是否匹配，确认没有通过 skipFiles 之类的设置误伤了自己想调试的源码。有时候，直接用 attach 模式连接正在运行的进程反而更靠谱。
• 远程 / 容器连不上 核对 IP 和端口映射，检查防火墙和安全组策略。核心原则就是：调试客户端必须能直连到调试端口，中间不能有拦截。