spark-web应用8080端口随机启动报错换端口即正常的排查方案

问题根本成因 #

• Spark Web框架的内置启动校验逻辑中，只要port()方法指定的端口无法完成TCP绑定，就会直接终止进程并返回退出码100，该异常和业务代码、路由配置没有任何关联。
• 反复出现的无规律异常、换3000端口即可正常启动的表现，本质是8080端口存在绑定阻碍，常见触发场景分为三类：
  • 上一次运行的Spark应用没有被完全终止，残留的后台Java进程持续占用8080端口
  • 上一次应用异常退出后，操作系统还处于TCP连接回收周期，8080端口短时间处于TIME_WAIT状态，不允许新进程绑定
  • 本地第三方服务（本地Tomcat、数据库可视化工具、视频客户端，或是Windows系统下Hyper-V/WSL2动态分配的端口保留范围）将8080划入不可绑定区间——没有普通用户进程占用端口，但操作系统层面禁止普通应用绑定

排查与永久解决步骤 #

• 启动前先定位8080端口的实际占用状态
  • Windows系统：命令行执行netstat -ano | findstr :8080，提取占用端口的进程PID；再执行tasklist | findstr 对应PID确认具体进程名称
  • Linux/macOS系统：终端执行lsof -i :8080，可直接查看占用端口的进程ID与进程名
• 针对定位到的问题源头做对应处理
  • 如果是残留的自身开发的Java进程：直接强制终止对应PID即可。Windows下执行taskkill /PID 进程ID /F，Linux/macOS下执行kill -9 进程ID，终止后即可正常用8080端口启动应用，不需要调整端口配置
  • 如果是第三方软件占用8080端口：直接调整该第三方软件的监听端口避开8080，不要反过来修改自身应用的端口适配无关服务
  • 如果未查询到任何进程占用端口，但绑定仍然失败：检查系统层面的端口保留范围。Windows下以管理员权限执行netsh int ipv4 show excludedportrange protocol=tcp，如果看到8080落在动态保留的端口区间内，调整Hyper-V的动态端口起始范围，将8080移出保留区间即可解决
• 从IDE配置层面减少残留进程的发生概率
  修改IntelliJ IDEA的运行配置，将默认的停止策略从“发送优雅退出信号”调整为“强制终止整个进程树”，后续点击停止按钮时会直接清理所有关联的后台Java进程，从根源上避免残留进程占端口的问题。

实用提示：Postman中维护的API配置只需要设置一个全局端口变量，一次调整即可同步所有接口的请求地址，维护成本远低于每次启动临时更换端口的操作。

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