Nginx部署若依项目：接口404与验证码不显示的解决方案

0 次阅读

若依（RuoYi）项目采用 Spring Boot + Vue 前后端分离架构后，通常会通过 Nginx 作为统一入口，实现前端静态资源代理、后端接口转发以及域名访问控制。但在实际部署过程中，经常会遇到两个典型问题：页面能够正常打开，但接口请求返回 404；登录页面可以加载，却无法显示验证码。

这类问题大多数并不是若依项目代码本身异常，而是 Nginx 代理配置、接口路径匹配、跨域处理或静态资源映射不正确导致。下面结合常见部署场景，对 Nginx 部署若依项目时接口 404 和验证码不显示问题进行系统分析。

一、若依项目部署架构分析

若依前后端分离版本通常包含两个部分：

  • Vue 前端项目：编译后生成 dist 目录，由 Nginx 提供静态访问。

  • Spring Boot 后端服务：运行在独立端口，例如 8080，通过接口提供数据服务。

典型访问流程如下：

用户浏览器
    |
    ↓
Nginx（80/443端口）
    |
    ├── /       → Vue静态页面
    |
    └── /prod-api/ → Spring Boot后端接口

若依默认情况下，前端请求接口通常类似：

/prod-api/login
/prod-api/captchaImage
/prod-api/getInfo

Nginx 需要将 /prod-api/ 开头的请求正确转发到后端服务。

如果代理规则缺失，请求会直接进入 Vue 路由处理，最终返回 404。

二、接口404问题常见原因

1. Nginx未配置接口代理

这是最常见的问题。

例如：

浏览器访问：

http://example.com/prod-api/login

如果 Nginx 没有代理配置，请求会寻找：

/usr/share/nginx/html/prod-api/login

而这个目录通常不存在，因此返回：

404 Not Found

解决方式是在 Nginx 配置文件中增加代理规则。

示例：

Nginx
server {
    listen 80;
    server_name example.com;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /prod-api/ {
        proxy_pass http://127.0.0.1:8080/;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

重点注意：

Nginx
location /prod-api/

必须与若依前端配置保持一致。

三、proxy_pass路径配置错误导致接口404

Nginx中的 proxy_pass 尾部斜杠非常关键。

例如：

错误配置

Nginx
location /prod-api/ {
    proxy_pass http://127.0.0.1:8080;
}

请求：

/prod-api/login

可能转发为：

http://127.0.0.1:8080/prod-api/login

如果后端接口实际地址：

http://127.0.0.1:8080/login

就会返回404。

正确方式：

Nginx
location /prod-api/ {
    proxy_pass http://127.0.0.1:8080/;
}

这样：

/prod-api/login

会转换为：

/login

符合若依后端接口路径。

四、检查若依前端接口前缀配置

如果 Nginx 使用：

/prod-api/

作为接口代理路径，需要确认 Vue 项目的环境配置。

打开：

.env.production

通常可以看到：

properties
VUE_APP_BASE_API = '/prod-api'

如果修改过，例如：

properties
VUE_APP_BASE_API = ''

那么前端请求会变成：

/login

而不是：

/prod-api/login

最终导致接口无法匹配。

修改后需要重新编译：

Bash
npm run build

然后重新替换 Nginx 部署目录中的 dist 文件。

五、验证码不显示的原因分析

若依登录验证码接口通常为：

GET /captchaImage

前端实际请求：

/prod-api/captchaImage

验证码无法显示，一般有以下几种情况。

六、验证码接口代理失败

打开浏览器开发者工具：

进入：

F12 → Network → captchaImage

查看请求状态。

如果显示：

404

说明 Nginx没有正确代理验证码接口。

解决方式：

确认存在：

Nginx
location /prod-api/ {
    proxy_pass http://127.0.0.1:8080/;
}

然后重新加载：

Bash
nginx -s reload

七、验证码跨域问题

如果前端和后端不是同一个域名，例如：

前端：

https://www.demo.com

后端：

http://127.0.0.1:8080

浏览器会受到跨域限制。

推荐通过 Nginx 统一代理：

https://www.demo.com
        |
        |
        ↓
Nginx
        |
        ↓
Spring Boot

不要让浏览器直接访问后端地址。

八、验证码缓存导致显示异常

若依验证码接口返回的是图片数据或 Base64 数据。

部分浏览器或代理服务器可能缓存验证码请求。

可以增加缓存控制：

Nginx
location /prod-api/ {
    proxy_pass http://127.0.0.1:8080/;

    add_header Cache-Control no-cache;
    add_header Pragma no-cache;
}

同时检查浏览器是否存在旧缓存。

可以尝试：

  • Ctrl + F5 强制刷新

  • 清理浏览器缓存

  • 使用无痕窗口测试

九、HTTPS部署时验证码异常

很多生产环境会使用 HTTPS。

如果：

https://example.com

访问前端，

但验证码接口请求：

http://example.com/prod-api/captchaImage

浏览器会阻止混合内容请求。

表现为：

  • 登录页面正常

  • 验证码区域空白

  • 控制台提示 Mixed Content

解决方式：

统一使用 HTTPS。

Nginx配置：

Nginx
location /prod-api/ {

    proxy_pass http://127.0.0.1:8080/;

    proxy_set_header X-Forwarded-Proto https;
}

同时后端开启代理支持。

Spring Boot配置：

YAML
server:
  forward-headers-strategy: framework

十、检查后端服务是否正常运行

Nginx配置正确，也需要确认 Spring Boot 服务状态。

查看端口：

Bash
netstat -tunlp | grep 8080

测试接口：

Bash
curl http://127.0.0.1:8080/captchaImage

如果返回正常数据：

说明后端没有问题。

如果失败：

检查：

  • 若依服务是否启动

  • 数据库连接是否正常

  • Redis是否运行

  • 验证码相关配置是否异常

十一、Nginx完整部署示例

生产环境常用配置：

Nginx
server {

    listen 80;
    server_name example.com;


    location / {

        root /opt/ruoyi/dist;

        index index.html;

        try_files $uri $uri/ /index.html;

    }


    location /prod-api/ {

        proxy_pass http://127.0.0.1:8080/;

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


        proxy_connect_timeout 60;

        proxy_read_timeout 60;

    }

}

该配置实现：

  • Vue页面访问

  • Vue Router刷新支持

  • 后端接口代理

  • 验证码访问

  • 用户登录认证

十二、快速排查流程

遇到若依接口404或验证码不显示，可以按照以下顺序检查：

第一步：检查前端请求地址

浏览器打开：

F12 → Network

确认接口是否：

/prod-api/xxx

第二步：检查Nginx代理

执行：

Bash
nginx -t

确认配置无错误。

然后：

Bash
nginx -s reload

第三步：测试后端接口

服务器执行：

Bash
curl http://127.0.0.1:8080/captchaImage

确认后端可访问。

第四步：检查proxy_pass斜杠

重点确认：

正确：

Nginx
proxy_pass http://127.0.0.1:8080/;

错误：

Nginx
proxy_pass http://127.0.0.1:8080;

第五步：检查HTTPS和跨域

如果生产环境使用域名和SSL：

  • 前后端协议保持一致

  • 不要暴露后端端口

  • 使用Nginx统一代理

十三、总结

Nginx部署若依项目后出现接口404和验证码不显示，核心原因通常集中在三个方面：

  1. Nginx没有正确代理 /prod-api/ 请求；

  2. proxy_pass路径处理错误导致接口地址变化；

  3. 前端接口前缀、HTTPS、跨域配置不一致。

正确部署时，应保证：

  • Vue静态资源由Nginx托管；

  • 后端接口通过Nginx反向代理；

  • /prod-api/路径保持统一；

  • 验证码接口能够正常转发；

  • HTTPS环境避免混合内容。

按照请求路径、Nginx代理、后端服务三个层面逐步排查，基本可以快速解决若依项目上线后的接口异常问题。

文章标签
若依项目 Nginx配置 接口404 验证码不显示 Spring Boot部署