Node.js的调试功能基于V8引擎的调试协议实现，默认情况下调试端口为9229，开发者可以根据实际需求自定义调试端口，适配不同的开发和部署场景。
一、通过命令行参数设置调试端口
这是最常用的调试端口设置方式，启动Node.js服务时通过--inspect或--inspect-brk参数指定端口即可。--inspect-brk会在代码第一行暂停，方便开发者从头开始调试。
1. 指定固定调试端口
使用--inspect=端口号的格式即可绑定指定端口，示例如下：
# 设置调试端口为9230，启动app.js node --inspect=9230 app.js # 设置调试端口为9231，且启动时在第一行暂停 node --inspect-brk=9231 app.js
2. 使用随机调试端口
如果不指定具体端口，仅使用--inspect参数，Node.js会自动分配9229及之后的可用端口，示例如下：
# 使用默认随机端口启动调试 node --inspect app.js
二、通过环境变量设置调试端口
除了命令行参数，还可以通过NODE_OPTIONS环境变量统一配置Node.js的启动参数，适合需要在多个服务中统一调试配置的场景。
1. Linux/macOS系统配置
在终端中执行如下命令设置环境变量后启动服务：
# 设置调试端口为9232 export NODE_OPTIONS="--inspect=9232" # 启动服务 node app.js
2. Windows系统配置
在命令提示符中执行如下命令：
# 设置调试端口为9232 set NODE_OPTIONS=--inspect=9232 # 启动服务 node app.js
也可以通过NODE_DEBUG_PORT环境变量单独设置调试端口，示例如下：
# Linux/macOS设置 export NODE_DEBUG_PORT=9233 node --inspect app.js # Windows设置 set NODE_DEBUG_PORT=9233 node --inspect app.js
三、在代码中动态设置调试端口
如果需要在应用运行时动态控制调试端口，可以通过inspector模块实现，适合需要按需开启调试的场景。
const inspector = require('inspector');
const fs = require('fs');
// 自定义调试端口
const debugPort = 9234;
// 开启调试，绑定指定端口
inspector.open(debugPort, undefined, true);
console.log(`调试端口已开启，端口号为：${debugPort}`);
// 可以按需关闭调试
// inspector.close();
四、调试端口冲突的解决方案
当指定的调试端口被其他进程占用时，会出现端口冲突错误，此时可以通过以下方式解决：
- 更换未被占用的端口，重新启动服务
- 查看占用端口的进程并关闭对应进程，Linux/macOS使用
lsof -i:端口号命令，Windows使用netstat -ano|findstr 端口号命令 - 不指定固定端口，使用随机端口分配的方式启动调试
五、调试工具连接自定义端口
设置好调试端口后，常见的调试工具可以按照如下方式连接：
| 调试工具 | 连接方式 |
|---|---|
| Chrome DevTools | 在Chrome地址栏输入chrome://inspect，在Discover network targets中添加localhost:自定义端口号，即可看到对应服务 |
| VS Code | 在launch.json配置中添加"port": 自定义端口号字段，即可连接到对应调试端口 |
| WebStorm | 在调试配置中选择Attach to Node.js/Chrome，填写自定义端口号即可连接 |
注意：调试端口默认仅监听127.0.0.1地址，如果需要远程调试，可以使用--inspect=0.0.0.0:端口号的格式绑定所有网络接口，但生产环境不建议开启远程调试，避免安全风险。六、常见注意事项
- 不要将调试端口暴露到公网环境，避免未授权访问导致代码泄露或服务器被攻击
- 生产环境默认不要开启调试模式，仅在需要排查问题时临时开启
- 如果使用Docker部署Node.js服务，需要将调试端口映射到宿主机，才能通过宿主机连接调试
Docker部署时设置调试端口的示例：
# 映射宿主机的9235端口到容器的9235调试端口 docker run -p 9235:9235 -p 3000:3000 my-node-app node --inspect=0.0.0.0:9235 app.js
Node.js调试端口inspectnode_debug_port调试配置修改时间：2026-06-20 21:45:19