WSL2 Ubuntu中Spring Boot API无法通过Postman访问localhost:8080

核心原因 #

WSL2采用独立虚拟网卡，Windows主机的localhost与WSL2内部的localhost并非同一地址；同时Spring Boot默认仅绑定本地回环地址，导致外部（Windows主机）无法访问服务。

分步解决方案 #

1. 修改Spring Boot服务绑定地址 #

让服务监听所有网卡请求，而非仅WSL2内部回环地址：

• 临时启动方案：启动时添加参数

  java -jar your-application.jar --server.address=0.0.0.0
  

• 永久配置方案：在项目application.properties中添加

  server.address=0.0.0.0
  

  或application.yml中配置

  server:
    address: 0.0.0.0
  

2. 验证WSL2内部服务可用性 #

先确认服务本身无问题，避免接口逻辑错误：
在WSL2终端执行测试命令：

curl -X POST http://localhost:8080/api/v1/model -H "Content-Type: application/json" -d '{}'

若返回预期响应，说明服务正常，问题出在网络映射；若报错，检查接口路径拼写、是否添加@RestController和@PostMapping("/api/v1/model")注解。

3. 使用WSL2的IP地址访问 #

在WSL2终端获取自身IP：

hostname -I

得到类似172.23.128.1的地址后，在Windows的Postman中替换localhost：

POST http://172.23.128.1:8080/api/v1/model

4. 配置端口转发（可选，固定用localhost访问） #

若希望一直用localhost:8080访问，通过Windows端口转发实现：

1. 以管理员身份打开PowerShell；
2. 执行命令自动配置转发：

   $wslIp = wsl hostname -I | awk '{print $1}'
   netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=$wslIp
   

3. 允许Windows防火墙入站请求：
   • 打开「Windows Defender防火墙」→「高级设置」→「入站规则」；
   • 新建规则，允许TCP 8080端口的连接。

5. 排查其他潜在问题 #

• 检查WSL2防火墙是否拦截端口：执行sudo ufw allow 8080临时开放测试；
• 确认端口未被占用：执行lsof -i :8080查看进程，如有占用可杀掉对应进程。

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