最后更新：2026-07-31
适用场景：Spring Boot 启动失败、8080 端口被占用、Port 8080 was already in use、Web server failed to start、Windows / Linux / macOS 查看端口占用、修改 server.port

Spring Boot 项目启动时，如果控制台出现下面这种报错：

Web server failed to start. Port 8080 was already in use.

或者：

Port 8080 was already in use.

基本可以确定：当前项目想使用 8080 端口，但这个端口已经被别的进程占用了。

这个问题很常见，尤其是本地开发时：

上一个 Spring Boot 项目没关
IDEA 里重复启动了两次
另一个服务也用了 8080
Docker 容器占用了端口
本机装了 Tomcat / Nginx / 其他 Java 服务

这个报错本身不复杂，处理思路也很简单：

要么关掉占用端口的进程；
要么让当前 Spring Boot 项目换一个端口。

---

一、先看报错长什么样

常见完整报错类似这样：

***************************
APPLICATION FAILED TO START
***************************

Description:

Web server failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.

这段提示已经把解决方向说得很清楚：

1. 找到占用 8080 端口的进程，并停止它
2. 或者把当前应用改成其他端口

本地开发时，不要一看到这个报错就去改代码。先判断一下：

这个 8080 端口到底是谁占用了？

---

二、最快解决办法

如果你只是想让项目先跑起来，最快的办法是改端口。

在 application.yml 里加：

server:
  port: 8081

或者在 application.properties 里加：

server.port=8081

然后重新启动项目。

如果 8081 也被占用，可以换成：

8082
8090
9000
10000

开发环境下，端口号不是固定不能改的。只要你前端、接口文档、回调地址同步调整即可。

---

三、什么时候该杀进程，什么时候该换端口

不要所有情况都直接杀进程。

我一般这样判断：

情况	建议处理
之前启动的同一个项目没关	杀掉旧进程
IDEA 里重复启动了同一个服务	停掉多余运行实例
另一个项目正常使用 8080	当前项目换端口
Docker 容器占用 8080	停容器或改映射端口
本机 Tomcat 占用 8080	停 Tomcat 或换 Spring Boot 端口
公司项目约定必须用 8080	找出占用进程并关闭
本地多个服务同时开发	每个服务分配固定端口

一句话：

端口被自己遗留进程占了，就关掉它；
端口被正常服务占了，就换当前项目端口。

---

四、Windows 查看 8080 端口占用

Windows 上可以用 netstat 查。

打开 CMD 或 PowerShell，执行：

netstat -ano | findstr :8080

如果端口被占用，可能会看到：

TCP    0.0.0.0:8080     0.0.0.0:0     LISTENING     12345

最后一列：

12345

就是进程 PID。

然后查看这个 PID 是什么程序：

tasklist | findstr 12345

可能输出：

java.exe                    12345 Console

说明是某个 Java 进程占用了 8080。

---

五、Windows 结束占用端口的进程

如果确认这个进程可以关闭，可以执行：

taskkill /PID 12345 /F

其中：

12345 替换成你查到的 PID

例如：

taskkill /PID 12345 /F

执行后再启动 Spring Boot 项目。

注意：不要看到 java.exe 就无脑杀。你的电脑上可能有多个 Java 程序正在运行。最好先确认是不是你刚才启动过的旧项目。

---

六、Windows 图形界面查进程

如果不习惯命令行，也可以这样：

Ctrl + Shift + Esc 打开任务管理器
切换到“详细信息”
找到对应 PID
确认进程名称
右键结束任务

如果任务管理器没显示 PID，可以在“详细信息”页右键表头，勾选：

PID

本地开发时，最常见的情况就是 IDEA 里项目没停干净，后台还留着一个 java.exe。

---

七、Linux 查看端口占用

Linux 上常用：

lsof -i :8080

输出类似：

COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
java    12345 root   88u  IPv6  12345      0t0  TCP *:8080 (LISTEN)

这里的 PID 是：

12345

也可以用：

netstat -tunlp | grep 8080

如果系统没有 netstat，可以用：

ss -tunlp | grep 8080

---

八、Linux 结束进程

确认可以结束后：

kill 12345

如果普通 kill 不生效，再用：

kill -9 12345

不建议一上来就 kill -9。
kill -9 是强制结束，服务没有机会优雅释放资源。

更稳一点：

kill 12345
sleep 2
lsof -i :8080

如果还在，再考虑：

kill -9 12345

---

九、macOS 查看端口占用

macOS 和 Linux 类似。

查看 8080：

lsof -i :8080

只看监听状态：

lsof -nP -iTCP:8080 | grep LISTEN

结束进程：

kill 12345

强制结束：

kill -9 12345

---

十、IDEA 里重复启动导致端口占用

这是最常见的本地开发场景。

你点了一次运行按钮，项目已经启动。
后来又点了一次运行，新的进程也想用 8080，于是报错。

处理方式：

1. 看 IDEA 底部 Run 窗口
2. 停掉旧的运行实例
3. 再重新启动

如果你开了多个 Run 标签，注意每个标签都可能是一个正在运行的服务。

也可以在 IDEA 右上角的运行配置旁边点停止按钮。

如果 IDEA 里看不到，但端口还被占用，就用命令查 PID。

---

十一、Spring Boot 改端口

application.yml

server:
  port: 8081

application.properties

server.port=8081

这就是最常见的改端口方式。

如果项目里有多个环境配置，比如：

application.yml
application-dev.yml
application-test.yml
application-prod.yml

要注意端口可能写在不同文件里。

例如：

# application-dev.yml
server:
  port: 8081

如果你改了 application-dev.yml，但实际启动时没有激活 dev 环境，那么端口配置不会生效。

---

十二、通过启动参数改端口

不想改配置文件，也可以启动时临时指定：

java -jar demo.jar --server.port=8081

IDEA 里也可以在 Program arguments 中加：

--server.port=8081

这样只对本次启动生效。

适合临时测试：

同一个项目启动多个实例
本地同时跑多个服务
不想改配置文件

---

十三、通过环境变量改端口

有些部署环境会用环境变量。

Linux / macOS：

export SERVER_PORT=8081
java -jar demo.jar

Docker：

docker run -e SERVER_PORT=8081 demo-app

Spring Boot 可以把环境变量映射到配置属性。
SERVER_PORT 对应：

server.port

这种方式适合容器部署或云平台部署。

---

十四、随机端口怎么写

如果只是测试，不关心具体端口，可以写：

server:
  port: 0

这样 Spring Boot 会随机分配一个可用端口。

启动日志里会看到实际端口，例如：

Tomcat started on port 53421

这种方式适合：

测试环境
集成测试
本地临时启动多个实例

不适合正式接口服务，因为前端或调用方不知道你实际端口是多少。

---

十五、端口配置没生效怎么办

如果你已经写了：

server:
  port: 8081

但启动还是占用 8080，先查这几个地方：

1. 配置文件是不是 application.yml / application.properties
2. yml 缩进是否正确
3. 是否改错了环境文件
4. spring.profiles.active 是否激活了对应环境
5. 启动参数里是否又指定了 --server.port=8080
6. 环境变量里是否有 SERVER_PORT=8080
7. IDEA 运行配置里是否写了旧端口

配置优先级不同，后面的启动参数、环境变量可能会覆盖配置文件。

例如你配置文件写：

server:
  port: 8081

但启动命令是：

java -jar demo.jar --server.port=8080

那最终仍然会用 8080。

---

十六、Docker 里的端口占用

Docker 场景有两层端口：

容器内端口
宿主机端口

例如：

docker run -p 8080:8080 demo-app

意思是：

宿主机 8080 -> 容器 8080

如果宿主机 8080 已经被占用，这个命令会失败。

可以改成：

docker run -p 8081:8080 demo-app

意思是：

宿主机访问 8081
转发到容器里的 8080

这时 Spring Boot 容器内部仍然可以用 8080，但外部通过 8081 访问。

如果想改 Spring Boot 自身端口，可以：

docker run -e SERVER_PORT=8081 -p 8081:8081 demo-app

---

十七、Docker Compose 端口写法

docker-compose.yml 示例：

services:
  demo-app:
    image: demo-app:latest
    ports:
      - "8081:8080"

这里表示：

宿主机 8081 -> 容器 8080

如果写成：

ports:
  - "8080:8080"

而宿主机 8080 已经被占用，就会启动失败。

本地开发多个 Spring Boot 容器时，建议这样分配：

services:
  user-service:
    ports:
      - "8081:8080"

  order-service:
    ports:
      - "8082:8080"

  product-service:
    ports:
      - "8083:8080"

这样容器内部都可以使用 8080，宿主机端口不同。

---

十八、Nginx 或 Tomcat 占用了 8080

本机如果安装过 Tomcat，默认也可能用 8080。

检查方式仍然是：

netstat -ano | findstr :8080

或者 Linux/macOS：

lsof -i :8080

如果确认是 Tomcat：

Windows：停止 Tomcat 服务
Linux：停止对应 Tomcat 进程

如果 8080 是 Nginx、网关或其他服务正常使用的端口，那就不要关它，直接让 Spring Boot 换端口。

---

十九、多个 Spring Boot 服务怎么分配端口

本地做微服务或多模块项目时，不要都用 8080。

可以约定：

网关服务：8080
用户服务：8081
订单服务：8082
商品服务：8083
后台服务：8088
管理端接口：8090

配置示例：

server:
  port: 8082

最好在 README 里写清楚：

user-service: 8081
order-service: 8082
product-service: 8083

否则团队协作时很容易冲突。

---

二十、端口被占用和 Spring Boot 版本有关吗

大多数情况下没关系。

无论是 Spring Boot 2、Spring Boot 3 还是 Spring Boot 4，只要内嵌 Web 容器启动时端口被占用，就会报类似错误。

但如果你升级了 Spring Boot 版本后突然出现端口问题，可能是因为：

配置文件没生效
profile 改了
server.port 被覆盖
启动脚本变了
Docker 映射变了
IDEA 运行配置变了

如果是 Spring Boot 2 升级 3，可以顺便检查：

Spring Boot 2 升级 3 指南

---

二十一、端口被占用和 JDK 有关系吗

一般也没关系。

不过如果你启动了多个不同 JDK 的 Java 进程，比如：

一个 JDK8 项目占用 8080
一个 JDK17 项目也想用 8080

那么后启动的项目还是会失败。

这时查端口时看到的可能都是：

java.exe

所以要根据 PID 判断具体是哪一个 Java 进程。

如果你有 JDK 版本混乱问题，可以看：

Java major version 对照表

---

二十二、常见错误处理方式

1. 直接改端口

server:
  port: 8081

适合：

只是本地端口冲突
另一个服务需要继续运行
想快速启动当前项目

---

2. 关闭旧进程

Windows：

netstat -ano | findstr :8080
taskkill /PID 12345 /F

Linux/macOS：

lsof -i :8080
kill 12345

适合：

旧项目没关
重复启动
确认进程可以关闭

---

3. 检查配置是否被覆盖

重点检查：

application.yml
application-dev.yml
启动参数
环境变量
IDEA Program arguments
Docker 环境变量
Docker 端口映射

适合：

明明改了 server.port，但启动还是 8080

---

二十三、完整排查清单

遇到端口被占用，按下面顺序查：

1. 看报错里写的是哪个端口
2. 判断是本地运行还是 Docker 部署
3. Windows 用 netstat -ano 查 PID
4. Linux/macOS 用 lsof 或 ss 查进程
5. 确认占用进程能不能关闭
6. 如果能关，就结束进程
7. 如果不能关，就修改 server.port
8. 检查 application.yml 缩进
9. 检查 profile 是否激活
10. 检查启动参数是否覆盖端口
11. 检查环境变量 SERVER_PORT
12. 检查 IDEA 运行配置
13. 检查 Docker 端口映射
14. 重新启动项目

---

二十四、常见问题 FAQ

1. Port 8080 was already in use 是什么意思？

意思是 8080 端口已经被其他进程占用了，当前 Spring Boot 项目不能再绑定这个端口。

---

2. 怎么查看 8080 被谁占用？

Windows：

netstat -ano | findstr :8080

Linux/macOS：

lsof -i :8080

---

3. 怎么关闭占用 8080 的进程？

Windows：

taskkill /PID 进程ID /F

Linux/macOS：

kill 进程ID

如果普通 kill 不生效，再考虑：

kill -9 进程ID

---

4. 怎么修改 Spring Boot 端口？

application.yml：

server:
  port: 8081

application.properties：

server.port=8081

---

5. 为什么我改了 server.port 还是 8080？

常见原因：

改错配置文件
profile 没激活
启动参数覆盖了配置
环境变量覆盖了配置
IDEA 运行配置里写了旧端口
Docker 映射端口没改

---

6. 8080 被占用一定要杀进程吗？

不一定。

如果占用 8080 的服务本来就需要运行，那就不要杀它，改当前项目端口更合适。

---

7. Docker 里 8080 被占用怎么办？

如果宿主机 8080 被占用，可以改映射：

docker run -p 8081:8080 demo-app

表示访问宿主机 8081，转发到容器 8080。

---

8. 多个 Spring Boot 项目可以都用 8080 吗？

不能在同一台机器上同时监听同一个端口。

可以分配：

8081
8082
8083
8088
8090

---

二十五、最后总结

Spring Boot 端口被占用，不是代码逻辑问题，基本就是端口冲突。

处理方式只有两个：

关闭占用端口的进程
或者修改当前项目端口

本地开发时，我更建议先查：

netstat -ano | findstr :8080

或者：

lsof -i :8080

确认到底是谁占用了端口。

如果只是旧项目没关，杀掉进程即可。
如果是另一个正常服务在用 8080，那就把当前项目改成：

server:
  port: 8081

不要为了启动一个项目，随手关掉不该关的服务。

---

二十六、相关文章

Spring Boot DataSource 报错：

Spring Boot DataSource 报错怎么处理

Spring Boot 接收 JSON 参数：

Spring Boot 接收 JSON 参数

Spring Boot 与 JDK 兼容：

Spring Boot JDK 兼容表

Spring Boot 2 升级 3：

Spring Boot 2 升级 3 指南

Java 开发环境配置：

Java开发环境配置专题

---

更新记录

2026-07-31：
- 创建 Spring Boot 端口被占用处理文章
- 增加 Windows / Linux / macOS 查看端口占用方法
- 增加修改 server.port、启动参数、环境变量方式
- 增加 Docker / Docker Compose 端口映射说明
- 增加 IDEA 重复启动、profile 配置不生效等常见场景