NestJS监听模式调试端口释放过慢导致重启失败问题

环境 #

• MacOS
• WebStorm
• Docker
• Node 20.18.0
• Nest 11.0.5

问题现象 #

使用命令 nest start --debug 0.0.0.0:9229 --watch 运行NestJS应用时，修改文件后进程会重启，但旧调试实例未完全断开就启动新实例，导致奇数次修改时报错：

Starting inspector on 0.0.0.0:9229 failed: address already in use

而偶数次修改则能成功连接：

Debugger listening on ws://0.0.0.0:9229/125a0c3c-c6d2-4f1e-b5eb-fbe109676996

需要实现调试器在重启前正常断开，确保每次修改都能成功连接。

解决办法 #

1. 给旧进程留足退出延迟 #

修改启动命令，添加 --watch-delay 参数，指定文件变更后延迟重启的毫秒数，给旧进程释放端口的时间，比如设置2秒：

nest start --debug 0.0.0.0:9229 --watch --watch-delay 2000

2. 用随机端口+WebStorm自动连接 #

放弃固定调试端口，让Node自动分配可用端口，再配置WebStorm自动识别：

nest start --debug --watch

在WebStorm的「Attach to Node.js/Chrome」调试配置中，勾选「Auto detect port」，即可自动连接到重启后的新进程，彻底避免端口冲突。

3. 强制旧进程优雅退出 #

在应用主文件（通常是main.ts）中添加信号监听，确保旧进程收到重启信号时先关闭应用再退出：

process.on('SIGTERM', () => {
  app.close().then(() => {
    process.exit(0);
  });
});

process.on('SIGINT', () => {
  app.close().then(() => {
    process.exit(0);
  });
});

4. 开启WebStorm自动重连 #

在WebStorm的「Attach to Node.js/Chrome」调试配置中，找到「Connection」部分，勾选「Reconnect automatically」，即使出现端口冲突，WebStorm也会自动尝试重新连接新进程。

内容的提问来源于stack exchange，提问作者negl1gence