【Java】踩坑实录:Spring Boot + Nginx 本地部署404终极排查：从80端口被占用到配置生效全流程
前言
在搭建前后端分离项目本地部署环境时，遇到了经典的“Nginx代理访问404”问题：Spring Boot后端（8106端口）启动正常，Nginx看似启动成功，但访问localhost始终返回404，甚至出现bind() to 0.0.0.0:80 failed (10013)启动报错。
经过多轮排查，最终定位了端口占用、配置路径、进程重启三大核心坑点。本文将完整还原排查过程与解决方案，希望能帮到同样踩坑的小伙伴，少走弯路。
关键在于通过查看nginx-1.28.0\logs\error.log的日志，发现了是端口占用问题。
一、问题背景
项目环境
后端：Spring Boot 2.6.2，运行端口
8106，接口前缀/app/前端：静态资源打包后存放于
D:\reference-project\package\front\nginx-1.28.0\html\public代理：Nginx 1.28.0（Windows版），计划代理前端静态资源+后端接口
目标：访问
localhost打开前端页面，且前端能正常调用后端接口
异常现象
Spring Boot后端日志正常，访问
http://localhost:8106/app/xxx能正常返回接口数据；Nginx启动时提示
bind() to 0.0.0.0:80 failed (10013: An attempt was made to access a socket in a way forbidden by its access permissions)；强行启动Nginx后，访问
localhost返回HTTP Error 404. The requested resource is not found.；确认
public目录下存在index.html，排除静态资源缺失问题。
二、核心排查过程（按优先级排序）
步骤1：验证静态资源有效性（排除基础问题）
首先确认前端静态资源路径无误，打开文件资源管理器，核对路径D:\reference-project\package\front\nginx-1.28.0\html\public下存在index.html、static等核心文件，排除“文件缺失导致404”的基础问题。
步骤2：定位Nginx启动报错核心原因——80端口被系统占用
通过netstat -ano | findstr :80命令查看端口占用，发现[::]:80的监听进程PID为4，这是Windows的System系统进程。
关键知识点：PID 4 占用80端口的本质
PID 4对应的是Windows内核级的HTTP.sys驱动（Windows HTTP服务），该服务支撑IIS、网络打印机共享、WinRM远程管理等功能，会默认占用80端口。此时直接启动Nginx监听80端口，必然触发10013权限禁止错误。
步骤3：修改端口后仍404——排查配置与重启问题
将Nginx监听端口改为8080后，访问localhost:8080仍报404，核心原因有二：
配置未生效：仅修改端口，未使用绝对路径配置静态资源，且未彻底重启Nginx；
访问地址错误：改端口后未在浏览器中添加端口号，仍访问
localhost（默认80端口）。
三、终极解决方案（可直接复制落地）
结合本次问题，最终采用**“修改Nginx配置 + 彻底重启进程 + 验证端口访问”**的方案，兼顾开发便利性与系统服务安全性（不停止Windows HTTP服务）。
方案1：修改Nginx核心配置（nginx.conf）
打开nginx-1.28.0\conf\nginx.conf，替换server块配置，重点解决静态资源路径、端口冲突、SPA路由、接口代理四大问题：
# Nginx核心配置（适配Windows本地开发） worker_processes 1; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; # 核心服务配置 server { listen 8080; # 避开80端口冲突，改为8080 server_name localhost; charset utf-8; # 1. 前端静态资源代理（关键：可使用绝对路径 root D:/reference-project/package/front/nginx-1.28.0/） location / { root html/public; index index.html index.htm; try_files $uri $uri/ /index.html; # 支持SPA路由刷新，避免子路径404 } # 2. 后端接口代理（匹配前端请求前缀/app/） location /app/ { proxy_pass http://localhost:8106/app/; # 代理到Spring Boot后端 proxy_redirect off; # 传递请求头，解决后端获取客户端IP、Host异常问题 proxy_set_header Host $host; proxy_set_header X-real-ip $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 错误页面配置 error_page 500 502 503 504 /50x.html; location = /50x.html { root html; } } }方案2：管理员权限彻底重启Nginx（避免进程残留）
Windows下Nginx进程易残留，导致新配置无法生效，必须以管理员身份执行以下命令：
# 1. 进入Nginx安装目录cdD:\reference-project\package\hzb-front\nginx-1.28.0# 2. 强制杀死所有Nginx进程（核心：避免残留）taskkill /f /im nginx.exe# 3. 重新启动Nginxnginx方案3：验证部署结果
前端页面验证：浏览器访问
http://localhost:8080，成功加载前端页面；后端接口验证：前端调用接口（如
/app/user/info），能正常获取后端返回数据；日志验证：查看
nginx-1.28.0\logs\error.log，无任何报错信息，说明部署成功。
四、拓展补充：两种端口解决方案对比
| 解决方案 | 操作方式 | 适用场景 | 优缺点 |
|---|---|---|---|
| 改Nginx端口（本文方案） | 将监听端口改为8080/8090等 | 本地开发、无需使用80端口 | 优点：不影响系统服务；缺点：访问需加端口号 |
| 释放80端口 | 停止Windows HTTP服务（net stop http） | 生产部署、必须使用80端口 | 优点：可直接访问localhost；缺点：可能影响IIS、网络打印机等功能 |
提示：本地开发优先选择“改Nginx端口”，生产环境若需使用80端口，可先评估系统服务依赖，再执行
net stop http停止服务。
五、Windows下Nginx本地部署核心避坑点
路径坑：Windows下配置
root必须使用绝对路径（/或\\分隔），相对路径易因启动目录不同导致文件找不到；端口坑：1024以下端口（如80）需管理员权限，且易被系统服务占用，开发建议使用8080/8888等端口；
重启坑：修改配置后，必须先
taskkill强制杀死进程，再启动，仅用nginx -s reload可能因进程残留失效；SPA坑：前端为Vue/React等单页应用时，必须添加
try_files $uri $uri/ /index.html;，否则路由刷新会404。
六、总结
本次404问题的核心逻辑是：80端口被系统占用 → Nginx启动失败/配置未生效 → 静态资源无法被正确代理 → 访问报404。
（注：文档部分内容由 AI 生成）