SpringBoot后端404错误：Nginx反向代理路径配置详解与解决方案

问题背景

在采用前后端分离架构的项目中，Nginx 常被用作反向代理服务器，将前端请求转发至后端 Spring Boot 服务。一个常见的部署问题是：前端页面可以正常访问，但发起的 API 请求却返回了 404 错误，这通常与反向代理的路径配置有关。

问题描述

项目部署完成后，分别启动了 Nginx 服务和 Spring Boot 后端应用。前端页面能够正常加载，但当页面发起 POST 等 API 请求时，这些请求未能被 Nginx 正确地转发到后端服务，导致客户端收到 404 状态码。

原因分析：端口与路径匹配

首先，需要排除一个基础配置错误：Nginx 监听端口与后端服务端口冲突。如果 Nginx 和后端 Spring Boot 应用都监听同一个端口（例如 8080），将导致端口占用冲突，服务无法正常启动。

根据配置确认，此问题已避免。如下图所示，Nginx 服务运行在 8081 端口，而 Spring Boot 应用运行在 8080 端口。

端口正确配置后，404 问题的核心便指向了 Nginx 的 location 路径匹配与转发规则。

解决方案：理解并配置反向代理路径

Nginx 的核心作用之一是作为反向代理。当浏览器访问 http://localhost:8081 时，Nginx 根据配置，将匹配特定路径规则的请求转发到指定的后端服务地址。

1. 明确后端 API 路径结构

要正确配置转发，首先必须明确后端服务的真实 API 路径。在本例的 Spring Boot 应用中，控制器通过 @RequestMapping 注解定义了请求根路径。

如图所示，控制器上注解为 @RequestMapping("/admin/employee")，这意味着访问该控制器中方法的完整路径前缀是 /admin/employee。

2. 理解 Nginx location 的匹配规则

Nginx 配置文件中的 location 指令用于匹配请求的 URI（路径）。location 后面的路径是一个“匹配模式”，它决定了哪些请求会由该 location 块内的配置（如 proxy_pass）处理。

关键的匹配规则如下：

• location /api/：匹配以 /api/ 开头的任何请求。
• location = /api/：只精确匹配 /api/ 这个路径。
• location ~ \.php$：使用正则表达式匹配以 .php 结尾的请求。

理解HTTP请求的路径处理流程是解决此类代理问题的关键。简单来说，你需要让 Nginx 截获前端请求的某部分路径，并将其“转换”为后端服务能识别的路径。

3. 配置正确的反向代理规则

结合以上分析，配置思路如下：

• 前端请求：假设前端统一以 /api 开头发起请求，例如 POST http://localhost:8081/api/employee/login。
• Nginx 匹配：使用 location /api/ 捕获所有以 /api/ 开头的请求。
• 路径重写与转发：通过 proxy_pass 将匹配到的请求转发给后端，并重写请求路径。将请求中的 /api 替换为后端需要的 /admin。

正确的 Nginx 配置示例如下：

# 反向代理,处理管理端发送的请求
location /api/ {
    proxy_pass http://localhost:8080/admin/;
}

在此配置中：

• 当请求 http://localhost:8081/api/employee/login 到达 Nginx。
• location /api/ 成功匹配该请求。
• proxy_pass 指令将请求转发至 http://localhost:8080/admin/，并将 location 匹配到的 /api/ 部分替换为 /admin/。
• 因此，最终到达 Spring Boot 后端应用的请求路径变为 http://localhost:8080/admin/employee/login，这正是后端控制器能够处理的路径，从而解决 404 错误。

<div align="center">


</div>

配置示例与验证

完整的相关配置参考如下：

1. Spring Boot application.yml (运行于8080端口):

   server:
     port: 8080

2. Nginx nginx.conf (运行于8081端口):

   server {
       listen       8081;
       server_name  localhost;
   
       location /api/ {
           # 关键配置：将 /api 前缀的请求转发至后端 /admin 路径
           proxy_pass http://localhost:8080/admin/;
       }
   
       # 其他配置，例如前端静态文件服务
       location / {
           root   /path/to/your/frontend/dist;
           index  index.html index.htm;
           try_files $uri $uri/ /index.html;
       }
   }

配置完成后，重启 Nginx 服务使配置生效。再次通过前端发起 API 请求，检查请求是否能够被正确转发并收到后端响应。掌握 Nginx 的路径匹配与转发逻辑，是解决前端代理 404 问题的核心。