部署若依项目最让人上火的场景不是框架跑不起来而是你按教程一步步部署完浏览器一开页面一直转圈白屏、加载条卡死F12里全是pending请求。这种“页面无法展示”的情况在若依项目部署中极其常见而且往往有一个共同前提本地开发时一切正常换到服务器就翻车。我刚带项目的时候遇到这类问题也很头疼后来总结出一套分层排查法先分清楚是前端资源没出来还是后端接口没通再沿着“浏览器-代理-后端进程-数据库/缓存”这条链路一层层往下找。只要思路对了问题基本都能在十几分钟内定位。这篇文章就把这套方法完整分享出来附上几个经典案例和可以直接抄的配置希望能帮你少走点弯路。1. 先搞清楚“一直加载”到底是哪一层的问题1.1 一条经典故障链路画像若依前后端分离项目上线后实际请求链路是这样的浏览器访问 Nginx 或云服务器上的静态服务拿到 index.html 和打包后的 JS/CSS 文件然后前端代码发起 /prod-api 开头的请求由 Nginx 反向代理到后端 Java 服务后端再访问 MySQL、Redis 等中间件。整条链路上任何一个环节断了表现都是“页面加载不出来”。但注意不同环节断掉现象是有区别的。比如静态资源拿不到页面是白屏而且网络请求里 JS/CSS 直接报 404如果是接口转发不通页面能出框架但验证码、登录、数据列表会一直转圈如果是数据库或 Redis 连不上后端接口会快速返回 500前端表现是接口报错而不是一直 pending。1.2 用F12把问题“钉死”在某一层碰上页面一直加载我的习惯是先开浏览器开发者工具按一下 F12切到 Network 面板再刷新页面。看三样东西第一静态资源请求有没有失败比如 index.js、index.css 是否 404这决定前端部署是否正常第二接口请求是否发出比如 /captchaImage、/login、/getInfo 这些若依核心接口是否存在返回的状态码是什么第三最耗时的是哪个请求如果某个接口一直 pending问题基本就在转发到后端的路上。Console 面板也要看。控制台里出现Cannot read properties of undefined、Uncaught TypeError、Failed to resolve component之类的报错往往说明后端返回的路由数据有问题比如数据库菜单表里的 component 路径写错了导致前端动态加载组件失败。这一类问题只看 Network 看不出来但 Console 会明确指路。1.3 请求状态码的快速解读把接口返回的状态码搞明白排查效率能提升一大截。若依部署场景下常见状态码我总结成一张表状态码含义大概率原因200正常无需处理401未认证验证码/Token校验失败常见于Redis没配好或登录接口返回后前端没存到token404路径不存在前端请求的路径和后端Controller路径不一致或Nginx转发时prefix没处理对405方法不允许前端GET后端POST或不带body等多为代理配置将请求改写异常500服务端异常后端代码报错看日志即可大多和数据库、Redis连接有关502网关错误Nginx连不到后端端口后端没起或地址写错504网关超时后端进程假死、接口阻塞、远程数据库慢等看到 502 和 504 时优先去查 Java 进程是否活着、端口是否在监听看到 500先去翻后端日志看到 404先确认 Nginx location 和 proxy_pass 的路径拼接方式。状态码能直接告诉你在哪一层省掉一半排查时间。2. 后端服务没起来前端一定转圈——先排查Java进程这一侧2.1 数据库连不上的几种经典死法若依后端启动时必连 MySQL一旦数据库连不上Spring Boot 启动流程基本上会直接中断页面自然就无法正常访问。常见的死法有这么几种。第一种是密码错误或者数据库不存在。排查时先看日志Spring Boot 启动失败会打印类似Cannot create PoolableConnectionFactory或Unknown database的异常。对应的配置在若依项目ruoyi-admin/src/main/resources/application-druid.yml文件里重点检查 url、username、password 三个字段。第二种是 MySQL 8 和旧驱动的兼容问题。如果你数据库用的 8.x但项目里的 pom.xml 还引着 5.x 的 mysql-connector-java 版本启动时可能不报错但执行一些 SQL 时会异常。另外 MySQL 8 的驱动类名变成了com.mysql.cj.jdbc.Driverurl 里最好显式加上serverTimezoneAsia/Shanghai和useSSLfalse否则可能出现时区相关的报错影响验证码、登录等接口返回。第三种是数据库字符集问题。若依的 SQL 脚本里建表语句默认用 utf8mb4如果数据库和表的字符集不一致导入数据没问题但查询中文数据时偶尔会出现乱码或者接口报Incorrect string value。创建数据库时建议指定CREATE DATABASE IF NOT EXISTS ry-vue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;部署后如果怀疑数据库有问题最快的验证方式是用命令行直接连一下mysql -h 服务器IP -u 用户名 -p然后use 数据库名;能进去再查一下select count(*) from sys_user;。这一步过了数据库层面的问题基本排除。2.2 Redis没接好验证码和登录都会卡住若依的验证码和 Token 缓存都依赖 Redis这也是新手部署最容易踩的坑。很多人本地没装 Redis开发环境能跑是因为若依在某些配置下可能降级或者你根本还没走到验证码那一步但生产环境一旦 Redis 连不上登录页的验证码图片会一直不出来或者在加载转圈。排查时看后端日志如果出现Unable to connect to Redis、JedisConnectionException之类的字样基本就是 Redis 服务没启动、端口不对或者 Redis 设置了密码但 application.yml 里spring.redis.password没配。建议在后端启动前先确认redis-cli -h 127.0.0.1 -p 6379 ping如果返回 PONG说明 Redis 正常。注意若依默认 Redis 索引库是 0一般不让你改如果你在云服务器上部署还要确认 Redis 的protected-mode是否会影响连接虽然这些一般不影响本机连接但部署在 Docker 或跨主机时很容易翻车。2.3 端口、防火墙、安全组这三兄弟最容易误伤后端进程确实起来了日志也显示Started RuoYiApplication但页面还是加载不出来那就要看网络层了。先看端口是否在监听。若依前后端分离版默认后端端口是 8080如果改了要记得在 application.yml 里改server.port并且前端代理和目标地址保持一致。在服务器上执行netstat -tlnp | grep 8080能查到 java 进程监听 8080说明端口没问题。此时再在服务器本地试一下接口通不通curl http://127.0.0.1:8080/captchaImage如果能返回 JSON说明后端接口是好的问题多半出在外部访问链路也就是防火墙或云安全组。很多云服务器厂商默认不会放行所有端口。阿里云 ECS 需要在控制台的安全组里把 80、8080 等端口加入入方向规则同时服务器自身防火墙也要检查。CentOS 上典型的操作是# 查看防火墙状态 systemctl status firewalld # 放行端口 firewall-cmd --zonepublic --add-port80/tcp --permanent firewall-cmd --zonepublic --add-port8080/tcp --permanent firewall-cmd --reload我见过不少情况本地 curl 通浏览器访问不通最后查出来就是安全组没放行端口。这个问题和代码没关系但最能让人崩溃。2.4 后端进程“假死”JVM内存配置的教训还有一种隐蔽情况是后端进程没挂端口也监听但请求进去后卡住不动最终超时。页面表现就是接口一直 pending最后 504。这类问题很多和 JVM 内存配置有关。若依打包后是一个可执行 jar很多人在服务器上直接java -jar ruoyi-admin.jar启动默认堆内存是物理机的四分之一如果服务器本身只有 1G 或 2G 内存同时又跑了 MySQL、Redis、NginxJava 进程很容易被系统 OOM Killer 干掉或者频繁 Full GC 导致接口响应极慢。建议部署时显式指定内存参数比如 2G 内存的机器可以这样java -Xms512m -Xmx512m -jar ruoyi-admin.jar --spring.profiles.activeprod启动后用jstat -gcutil pid看一下 GC 情况如果 Old 区占用持续高位说明内存确实不够要么加内存要么降低堆配置。遇到进程直接被系统杀掉的情况可以用dmesg | tail -20查看经常能看到Out of memory: Kill process的记录。3. 前端构建与部署页面能不能出来全看这几处3.1 构建前先改 .env.production别用默认配置硬上前端打包是若依部署流程里很容易忽略一步。很多教程直接让你npm run build:prod但如果你没改环境变量打包出来的 API 地址可能还是开发环境的值。RuoYi-Vue 前端目录下有个.env.production文件内容大致是这样ENV production VUE_APP_BASE_API /prod-api这个VUE_APP_BASE_API决定了前端所有请求的前缀。生产环境下你希望浏览器请求/prod-api/login然后由 Nginx 把/prod-api转发到后端 8080。所以这个值要和 Nginx 的 location 前缀保持一致否则请求路径对不上页面一登录就开始转圈。RuoYi-Vue3 用的是 Vite对应的文件是.env.production里面的变量名是VITE_APP_BASE_API作用和上面一样。改完配置后重新打包再检查 dist 目录下的 JS 文件里是否出现了你期望的/prod-api字符串如果不是就是环境变量没生效看看是不是拼写错了变量名。3.2 dist目录别放错静态资源路径决定了白屏还是正常打包完成后前端产物在 dist 目录。不同类型的若依版本静态资源引用的路径不一样。如果你把 dist 放在 Nginx 的某个子目录比如/usr/share/nginx/html/dist而代码打包时资源路径是绝对路径/js/xxx.js那么浏览器访问/js/xxx.js时就会 404结果就是页面空白。Vue2 的若依publicPath 默认是/适合站点根路径部署如果一定要部署在子路径需要修改 vue.config.js 里的publicPath为相对路径或者子目录路径同时注意路由模式。Vue3 的若依在 vite.config.ts 里可以配置base部署到根路径就用/部署到子目录就改成对应路径。页面白屏时优先看 Network 里有没有 404 的静态资源。如果 index.html 能加载但 JS/CSS 404基本上就是路径问题。这时不用怀疑代码先调整打包路径再重新构建发布。3.3 history路由刷新404必须要有 try_files若依前端默认使用 Vue Router 的 history 模式这种模式下一个最大的坑就是你访问首页没问题但一旦你直接访问某个子路由比如/system/user或者刷新当前页面Nginx 找不到对应的物理文件直接返回 404。解决方法是服务器端把所有不存在的路径都重写到 index.html也就是 Nginx 的 try_files 指令location / { root /usr/share/nginx/html/dist; index index.html index.htm; try_files $uri $uri/ /index.html; }这一行是若依部署在 history 模式下的标配。少了它刷新页面会 404用户会觉得“页面突然打不开了”其实只是路由回退没有处理。如果你用 Docker 部署的 Nginx配置路径要对应容器内的路径别拿宿主机路径直接填。4. 连接前后的Nginx代理配置对了才叫“通了”4.1 一份能跑通的若依Nginx配置参考下面这份配置我用了很多次适配 RuoYi-Vue 前后端分离部署。前端放在/usr/share/nginx/html/dist后端跑在 8080 端口前端 API 前缀是/prod-apiserver { listen 80; server_name your.domain.com; # 前端静态资源 location / { root /usr/share/nginx/html/dist; index index.html index.htm; try_files $uri $uri/ /index.html; } # 后端接口反向代理 location /prod-api/ { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:8080/; } # 静态资源缓存策略可根据需要调整 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 7d; } }写完后执行nginx -t校验语法没问题再systemctl reload nginx。这里要特别留意proxy_pass后面的 URL 结尾是否带了斜杠两个写法效果完全不同。4.2 proxy_pass 结尾要不要加斜杠这是个送命题Nginx 的proxy_pass http://127.0.0.1:8080/;和proxy_pass http://127.0.0.1:8080;差一个斜杠转发结果天差地别。带斜杠的写法会把 location 匹配到的/prod-api前缀替换掉。比如前端请求/prod-api/login最终转发给后端的是/login。若依后端的 Controller 路径本来就是/login所以这个写法是正确的。如果不带斜杠比如写成proxy_pass http://127.0.0.1:8080;那么请求会被原样转发为/prod-api/login此时后端没有这个路径返回 404前端就一直加载不出来。那什么时候不用带斜杠如果你的后端本身就配置了 context-path比如server.servlet.context-path: /prod-api那就需要把/prod-api原样传给后端此时用不带斜杠的写法。所以部署前先看一下后端的 application.yml 里有没有配 context-path再决定 Nginx 怎么写。这是若依部署里最常见、也最容易被忽略的细节。4.3 三步确认代理是否真正生效改完 Nginx 配置别急着刷新浏览器先在服务器上做三层验证逻辑清晰问题也更好定位。第一步验证后端本身正常curl http://127.0.0.1:8080/captchaImage如果返回 JSON说明后端和 Redis 都正常。第二步验证 Nginx 转发正常curl http://127.0.0.1/prod-api/captchaImage如果返回和上一步一样的 JSON说明 Nginx 到后端的链路没问题。此时再在浏览器访问如果还是 pending就去查服务器防火墙和安全组了。第三步验证静态页面能出来curl http://127.0.0.1/ | head -n 20看到 HTML 内容说明前端部署没问题。这三步走完就能把问题压缩到网络或浏览器侧排查范围就非常小了。5. 真实案例复盘与问题速查表5.1 案例一验证码一直转圈是Redis在背锅一个朋友部署 RuoYi-Vue反馈说登录页验证码一直转圈后端日志看了一遍没发现明显报错接口返回 500。最后定位到 Redis。他那台云服务器上 Redis 确实装了但配置了密码若依的 application.yml 里没配导致认证失败验证码接口拿不到缓存服务。这个案例我印象很深因为日志里报错不是特别直观而验证码又是访问系统的第一道关卡。所以我把 Redis 检查放在后端排查的前三位。部署若依时无论开发还是生产先把 Redis 跑通再谈登录。5.2 案例二打包后页面白屏控制台提示chunk加载失败另一个案例是 Vue3 版本的若依打包部署后首页白屏Console 报Failed to fetch dynamically imported module或者Loading chunk failed。这种报错十有八九是路由懒加载的 chunk 文件路径不对。查下来发现是 vite 配置里的base没改。项目部署在服务器根目录但构建时 base 默认是/理论上没问题可当时他们把 dist 目录放在了 Nginx 的一个子路径下浏览器请求/admin/js/xxx.js实际文件在/dist/admin/js/xxx.js路径就错了。解决办法是把 base 改成相对路径./或者把 dist 下内容搬到站点根目录。这类问题 F12 里一眼就能看出来JS 请求 404路径对不上别傻乎乎去查后端。5.3 案例三登录成功但首页不停加载还有一类情况是登录能成功页面框架出来了但主区域一直转圈。这种情况多半出在动态路由上。若依的菜单权限是后端返回的前端通过/getRouters拿到路由数据再根据菜单表里的 component 字段动态加载页面组件。如果数据库菜单表的 component 写了不存在的路径比如/system/user/index但实际文件在views/system/user/index.vue之外前端匹配不到组件控制台会出现Failed to resolve component之类的报错对应页面就一直白屏转圈。排查方法很直接登录后看 Network 里/getRouters的响应再逐个核对菜单的 component 路径是否真实存在。这个和部署环境关系不大但经常在迁移数据库后冒出来因为换了 SQL 文件菜单数据可能不完整。5.4 问题速查表从现象到原因最后整理一张速查表覆盖若依部署后“页面无法展示”最常见的现象和解决方向现象可能原因优先排查点页面全白静态资源404前端部署路径错误、publicPath/base配置不对Network面板看JS/CSS请求路径登录页出不来验证码转圈后端没启动、Redis连不上、Nginx没转发后端日志、redis-cli ping登录后主区域一直转圈动态路由加载失败、菜单component路径错误/getRouters响应、Console报错接口502/504后端进程挂掉、端口不对、后端响应过慢netstat查端口、进程状态、JVM日志接口500数据库或Redis问题、代码异常后端日志、数据源配置刷新子路由404前端history路由未配try_filesNginx location配置本地正常服务器不行防火墙、安全组、环境变量差异服务器本地curl对比排查时记住一个原则从浏览器往服务器方向查先看请求能不能发出再看服务器内部服务通不通一层层缩小范围。大多数“页面一直加载”的问题最终都落在 Nginx 转发、Redis 连接或数据源配置这三块上。若依这套框架本身很成熟部署并不复杂出问题往往就是链路里的小细节没对上。个人体会是别一上来就怀疑代码或框架严格按照分层排查的思路走先看状态码再查日志再验证端口和中间件问题基本都能解决。如果你按照上面的方法还是找不到原因建议把后端日志完整拉出来、把 F12 的 Network 截图和 Console 报错贴出来很多时候答案就在那两处细节里。希望这篇内容能帮你顺利把若依项目跑起来。
