【踩坑实录】若依Vue宝塔部署：验证码空白、反复提示登录状态已过期｜完整排错

文章标签：若依 RuoYi‑Vue 宝塔 Nginx 登录状态已过期 prod‑api

阅读时长：8分钟

适用：宝塔 + SpringBoot Jar + 前后端分离若依项目

前言

最近部署若依‑Vue前后端分离版本，踩了一套连环大坑，网上大部分教程照搬过来直接翻车。

现象：

• 不配置伪静态：页面刷新404、接口报400；
• 复制网上通用Vue History伪静态之后：前端页面可以打开；
• 验证码图片一片空白，看不到验证码；
• 账号密码登录成功，立马弹出：登录状态已过期，您可以继续留在该页面，或者重新登录；
• 反复登录无限循环，token明明拿到手，一调用接口就401。

网上90%教程默认后端 context‑path: /api，但是很多同学改成 context‑path: /，直接复制配置直接崩。

一开始以为是Redis、token过期问题，排查半天，最后发现全部是Nginx代理斜杠、路径匹配、cookie路径的坑。

环境信息

• 前端：RuoYi‑Vue3/Vue2，生产环境 VITE_APP_BASE_API = '/prod-api'
• 后端：SpringBoot Jar包，server.servlet.context-path: /（后端接口无/api前缀）
• 部署方式：宝塔Nginx部署前端dist，Nginx反向代理本地jar，jar端口8080
• 依赖：Redis存储token、验证码

问题根因

1. 普通Vue History伪静态 try_files $uri $uri/ /index.html; 会把 /captchaImage、/prod‑api/* 全部当成前端路由，返回index.html，接口拿到的是HTML源码，不是后端数据；
2. proxy_pass 末尾斜杠，多一个少一个，路径映射错乱，接口404/401；
3. Nginx代理路径发生变化，Cookie路径不匹配，浏览器丢弃会话Cookie，token会话丢失，疯狂提示登录过期；
4. /captchaImage 是独立接口，不带任何api前缀，需要单独代理，很多教程漏掉这一块。

重点提醒：出现登录状态已过期，不一定是Redis和token的问题，Nginx配置错误一样疯狂返回401。

一、宝塔伪静态最终可用配置

操作路径：宝塔面板 → 网站 → 设置 → 伪静态，清空原有全部内容，复制下面配置。

⚠️全部符号务必英文，不要复制网页带来的中文长横杠，Nginx会直接配置失效。

# Vue history模式，前端静态页面路由
location / {
    try_files $uri $uri/ /index.html;
}

# 处理前端 /prod‑api 请求，剥离/prod‑api前缀转发后端根路径
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 60s;
    # 解决代理路径变更，cookie路径不匹配导致会话丢失、登录频繁过期
    proxy_cookie_path / /prod-api;
}

# 验证码独立接口，无/api、无/prod‑api前缀，必须单独代理
location /captchaImage {
    proxy_pass http://127.0.0.1:8080/captchaImage;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

修改注意：把8080替换为你jar实际运行端口。保存后重载Nginx，确认无配置报错。

逻辑说明

浏览器请求：https://xxx.yxqz.top/prod-api/login

Nginx剥离/prod-api/前缀，转发到后端：http://127.0.0.1:8080/login

proxy_pass http://127.0.0.1:8080/; 末尾斜杠不能丢，丢了不会剥离前缀，接口直接404。

二、后端 application.yml 关键配置

server:
  port: 8080
  address: 0.0.0.0
  servlet:
    context-path: / # 后端根路径，不要改成/api

address: 0.0.0.0，不能只写127.0.0.1，否则外部访问受限。

三、前端 .env.production 配置

# 页面标题
VITE_APP_TITLE = 青春步道后台管理系统
# 生产环境标识
VITE_APP_ENV = 'production'
# 生产接口请求前缀
VITE_APP_BASE_API = '/prod-api'
# 开启gzip打包压缩
VITE_BUILD_COMPRESS = gzip

✅重要：修改完环境变量，必须执行 npm run build 重新打包，上传全新dist到网站根目录。

只改配置不重新打包，浏览器依旧读取旧的dist文件，所有修改全部无效。dist不要嵌套子文件夹，网站根目录直接放index.html。

四、排错调试流程（二分法快速定位问题）

核心思路：先绕开Nginx，直接测试后端jar，判断问题属于后端还是Nginx代理。

1、服务器终端测试后端验证码接口

curl http://127.0.0.1:8080/captchaImage

• 返回二进制乱码流：jar、Redis运行正常；
• 连接拒绝：jar未启动、端口错误、监听地址不对；
• 报错：检查Redis是否启动，核对Redis密码、database配置。

2、测试鉴权接口，判断token是否有效

登录页面拿到token，复制token值，服务器终端执行：

curl -H "Authorization: Bearer 你的token" http://127.0.0.1:8080/getInfo

1. ✅正常返回用户信息json：后端Jar、Redis完全没问题，问题100%出在Nginx代理配置；
2. ❌返回401：Redis未启动/密码错误/库号不对，查看后端日志排查。

3、浏览器端验证

1. 清除浏览器localStorage旧token；
2. Ctrl + F5强制刷新页面；
3. 浏览器直接访问 域名/captchaImage，正常直接展示验证码图片；
4. F12打开网络面板，观察请求地址：
   • 登录接口：POST /prod-api/login
   • 获取用户信息：GET /prod-api/getInfo

现象	问题定位
访问/captchaImage返回HTML源码	伪静态未生效，接口被history路由劫持
接口返回502 Bad Gateway	Nginx无法连接后端jar，检查jar启动状态、端口
本机curl后端正常，浏览器访问域名返回401	Nginx斜杠、proxy_cookie_path配置错误
本机curl直接返回401	Redis异常，token无法读写，查看后端日志

五、高频踩坑总结

1. 复制配置带入中文符号：网页复制出来长破折号，Nginx校验失败，伪静态完全失效；
2. proxy_pass末尾斜杠：斜杠控制是否剥离location匹配前缀，少斜杠路径错乱，接口404/401；
3. 忘记重新build打包dist，旧dist缓存坑无数人；
4. Redis未启动、密码错误，登录成功token存不进去，调用接口直接401；
5. dist文件夹嵌套，网站根目录不是index.html；
6. Nginx代理模式，安全组不需要放行8080端口，仅本地127.0.0.1访问jar，只开放80/443端口。

补充：如果你的后端 context‑path: /api

很多默认模板后端上下文是/api，伪静态/prod‑api块改成下面：

location /prod-api/ {
    proxy_pass http://127.0.0.1:8080/api/;
    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 60s;
    proxy_cookie_path /api /prod-api;
}

写在最后

若依宝塔部署出现验证码空白、反复登录过期，大部分不是业务代码bug，都是Nginx反向代理路径理解不到位。

记住三个关键点：

1. proxy_pass末尾斜杠控制路径剥离；
2. /captchaImage独立接口，不走api前缀，必须单独代理；
3. proxy_cookie_path处理代理路径变化，解决会话丢失，避免疯狂弹窗登录过期。

---