简介围绕若依前后端分离项目的部署实践这份文档面向已具备 Java、Vue 与 Linux 基础的开发者系统梳理从环境准备到上线排错的完整路径。内容按 LinuxNginx 部署、WindowsTomcat 无 Nginx 部署、第三方 API 跨域处理三部分展开涉及前后端打包、Redis 缓存、反向代理、路由回退与登录后空白等关键节点并给出部署后刷新 404 等常见问题的排查思路。资源包共 1 个 docx 文件约 223KB篇幅精炼便于按章节对照操作也可作为团队内部部署手册的参考底稿。目前已有 7766 人学习适合需要快速跑通若依项目、理解前后端分离部署细节与跨域排错方法的中初级开发者查阅。1. 部署后白屏、404、菜单打不开若依前后端分离最容易翻车的三个瞬间打包上传、nohup起 jar、nginx -s reload浏览器一开——白屏。再刷新404。换个账号登录菜单点不动。这三连击几乎是每个第一次部署若依前后端分离项目的人都要交的学费我在不同机器上重装过好几遍坑一个没落下。问题在于它不像单体的 Spring Boot 那样“起了就是起了”。前端 Vue 打出来的dist是静态资源后端 Spring Boot 是接口服务中间还夹着 Nginx 反向代理和 Redis 缓存链路一长任何一环配置错位都表现为“页面打不开”报错信息还都藏在浏览器控制台或者msg.log里不看日志根本猜不到。这篇就按 LinuxNginx 和 WindowsTomcat 两条部署路径把白屏、404、菜单加载失败、第三方 API 跨域这几类高频故障逐个拆开说清触发条件、根因以及能直接抄的命令和配置。2. 白屏与接口 404Nginx 代理和打包配置错在哪部署完第一眼看到白屏很多人第一反应是前端打包坏了回头重跑npm run build:prod --report白跑几遍还是白。实际上白屏只是“HTML 加载成功了但 JS/CSS 资源 404 或者接口全挂”的外在表现根因基本锁定在两个地方Nginx 的root/location指向不对或者前端vue.config.js里的publicPath跟实际访问路径不匹配。2.1 先分清是静态资源 404 还是接口 404打开浏览器开发者工具切到 Network 面板刷新页面看红色请求的路径长什么样。如果是/static/js/xxx.js、/static/css/xxx.css这类静态资源 404问题在前端打包路径或者 Nginx 的静态目录配置如果是/prod-api/getInfo、/prod-api/login这类接口 404问题在 Nginx 的proxy_pass或后端服务没起来。这一步分流决定了后面查哪个配置文件别一上来就改代码。另一种情况更隐蔽请求返回 200但响应体是一段 HTML。这说明 Nginx 把接口请求也当成静态资源去try_files了最后 fallback 到index.html前端拿到一坨 HTML 当 JSON 解析自然报错。判断方法是看 Response 的 Content-Type是text/html就实锤了。2.2 Nginx 配置root、location、proxy_pass 三段必须对齐若依官方文档给的 Nginx 配置骨架大概是这样我按实际排错时最常改的三个点加了注释server { listen 80; server_name localhost; location / { root /home/ruoyi/dist; # 必须指到 dist 目录本身不是它的父目录 try_files $uri $uri/ /index.html; # history 路由必须回退到 index.html index index.html index.htm; } 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_pass http://127.0.0.1:8080/; # 结尾的斜杠决定路径是否被截断 } }root是最容易写错的一项。有人写成/home/ruoyi结果访问/时 Nginx 去找/home/ruoyi/index.html而文件其实在/home/ruoyi/dist/index.html里直接 404 白屏。try_files那行是给 Vue 的 history 模式兜底的缺了它用户刷新非根路径比如/system/user就会 404因为服务器上根本没有这个物理文件。proxy_pass结尾的斜杠是个经典陷阱。写http://127.0.0.1:8080/时/prod-api/login会被替换成/login转发给后端如果漏掉斜杠写成http://127.0.0.1:8080转发过去的路径是/prod-api/login后端没有这个映射直接 404。后端 Spring Boot 的 context-path 如果配了/prod-api那反过来就不能带斜杠否则变成/prod-api/prod-api/login。这两个配置是一对改一个必须检查另一个。改完配置不要急着重载先nginx -t验证语法通过再nginx -s reload。语法错的时候 reload 会失败但旧进程还在跑页面表现跟没改一样很容易误判成“改了没用”。2.3 前端 publicPath那个被很多人忽略的点原文档里提到“后期修改了文件或菜单再部署上去菜单打不开去掉vue.config.js里/之前的.即可”。这个.指的是publicPath: ./这种相对路径写法。相对路径在本地npm run dev时没问题但部署到 Nginx 后如果访问路径带层级相对路径解析会错位静态资源全 404页面白屏。// vue.config.js module.exports { publicPath: process.env.NODE_ENV production ? / : /, // 部署在根路径用 /如果部署在子路径 /ruoyi/ 下才改成 /ruoyi/ outputDir: dist, assetsDir: static }publicPath设成/表示资源从域名根开始找这是部署在独立域名或独立端口下最稳的写法。只有当项目挂在http://ip/ruoyi/这种子路径下时才需要改成/ruoyi/并且 Nginx 的root和location也要同步加前缀。改完必须重新npm run build:prod只改配置不重新打包是无效的——dist 里的index.html引用路径是打包时写死的。打包时加--report会额外生成一个体积分析页面部署时它只是个静态文件不影响运行但如果发现 dist 特别大、上传慢可以先看这个报告砍掉没用的依赖再传能省不少等待时间。3. 菜单打不开与登录后空白路由、Redis 和 Tomcat 的连环坑比白屏更让人抓狂的是“能登录但登录完一片空白”或者“菜单树加载不出来点哪个都没反应”。这类问题往往不是前端坏了而是后端返回的数据不对或者路由回退没配好。WindowsTomcat 部署路径下这个坑尤其密集因为少了 Nginx 那层兜底全靠 Tomcat 自己处理。3.1 登录成功但空白页Tomcat 缺少 Context 配置原文档里写得很直白war 包丢进webapps、改名为prod-api、dist 丢进去然后必须改conf/server.xml在 Host 节点下加 ContextHost namelocalhost appBasewebapps unpackWARstrue autoDeploytrue Context path/ docBasedist的绝对路径或相对webapps的路径 reloadabletrue crossContexttrue/Context /Host不加这段登录接口能通因为/prod-api是独立 war 应用Tomcat 能自动映射但前端页面路由一跳转就空白。原因在于 Vue 的 history 模式路由/system/user这类地址Tomcat 找不到对应的物理目录又没有回退规则直接给个空响应。Context 把根路径指向 dist 目录配合后面的web.xml做 404 回退才形成完整闭环。docBase写相对路径时是相对于webapps目录的比如 dist 放在webapps/dist这里就写dist写绝对路径则要写全D:\tomcat\webapps\dist这种反斜杠注意转义习惯。reloadabletrue用于开发期改文件自动重载生产环境建议关掉每次都重载会拖慢响应。3.2 刷新页面 404WEB-INF/web.xml 的 404 回退原文档给出的关键一步在 dist 目录下建WEB-INF文件夹里面放web.xml?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd version3.1 metadata-completetrue display-nameRouter for Tomcat/display-name error-page error-code404/error-code location/index.html/location /error-page /web-app这段配置的作用是Tomcat 遇到 404 时把请求转发到/index.html前端路由接管后再按 URL 渲染对应组件。功能上等价于 Nginx 的try_files $uri $uri/ /index.html。没有它用户只要在任意非根页面按 F5就是一个 Tomcat 的 404 页看起来像服务挂了。metadata-completetrue表示不扫描注解加快启动version3.1要和 Tomcat 版本匹配Tomcat 8 用 3.1、Tomcat 9 用 4.0 都行版本写错会导致 web.xml 解析失败症状是配置“完全没生效”。放好文件后必须重启 Tomcat热部署不一定能识别新增的 WEB-INF。3.3 菜单加载不出来先看 Redis再看动态路由若依的菜单是动态权限菜单登录后前端调/getRouters拿菜单树。这个接口挂了或者返回空数组左侧菜单就是空白。排查顺序我一般是先redis-cli ping确认 Redis 活着再tail -f msg.log看有没有连接异常最后看接口返回。Redis 没起的时候登录可能还能成功JWT 校验不完全依赖它但 token 缓存、验证码、字典数据全挂菜单接口很容易超时或返回空。启动命令就是redis-server确认redis.conf里bind和protected-mode没把本地连接挡掉。jar 包启动时如果 Redis 连不上日志里会有Unable to connect to Redis明确的报错别去前端找原因。启动 jar 本身也有讲究原文档用的是nohup java -jar ruoyi-admin.jar msg.log 21 nohup让进程脱离终端 msg.log 21把标准输出和错误都重定向到日志放后台。少了21错误日志不会进文件出问题只能看到标准输出排查时等于蒙眼。msg.log生成在当前执行命令的目录下换目录启动就找不到日志了这是新手常问“日志在哪”的原因。4. 跨域报错与部署避坑清单CORS、代理和那些反复踩的点控制台一行红字has been blocked by CORS policy前面所有部署工作看起来都白干了。跨域在若依项目里分两种前后端之间的跨域部署正确时不该出现和调用第三方 API比如地图服务的跨域必然出现必须处理。混在一起查会浪费大量时间。4.1 前后端跨域先确认代理是否真的生效标准部署下前端和后端同域名同端口请求走/prod-api被 Nginx 转发浏览器看来是同源不会有跨域。如果部署后还是报跨域说明请求根本没走代理——大概率是前端baseURL配错了直接请求了http://ip:8080。检查.env.production里的VUE_APP_BASE_API应该是/prod-api这种相对路径不是完整域名。# .env.production VUE_APP_BASE_API /prod-api改成完整地址后浏览器就认为跨域了Nginx 代理形同虚设。这个文件改完同样要重新打包。本地开发时vue.config.js里配devServer.proxy也是同理只对npm run dev生效生产环境靠 Nginx两边别搞混。4.2 第三方 API 跨域三种处理方式怎么选调用地图类第三方 API 时跨域无法避免因为请求目标是别人的域名。常见做法有三种后端加 CORS 配置让浏览器放行。Spring Boot 里可以全局配Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) // 生产环境换成具体域名 .allowedMethods(GET, POST, PUT, DELETE) .allowCredentials(true) .maxAge(3600); } }allowedOriginPatterns而不是allowedOrigins(*)是因为开启allowCredentials(true)后通配符*会被拒绝用 Pattern 版本才能兼容。这只解决自家后端接口的跨域第三方 API 的响应头不归你管。要绕开第三方 API 的跨域就得让请求从服务器发出。Nginx 加一段反代location /third-api/ { proxy_pass https://第三方接口域名/; proxy_set_header Host 第三方接口域名; }前端请求改成/third-api/xxx浏览器同源Nginx 服务器之间没有跨域限制。缺点是要为每个第三方域名加一段且对方如果校验 Referer 或签名可能还是过不去。第三种是前端代理只在开发期有效生产环境不适用。三种方式里需要长期稳定调用的走 Nginx 反代临时调试用后端 CORS别在vue.config.js的 proxy 上纠结生产问题。4.3 部署避坑清单五条血泪记录现象改了配置重启后毫无变化。原因Nginx 没 reload 或 reload 失败但没看输出Tomcat 进程没真正重启。解决nginx -t nginx -s reload一步步来Tomcat 用shutdown.sh后确认进程消失再startup.sh。现象部署到子路径后所有资源 404。原因publicPath还是/Nginx 的location也没加前缀。解决两处同步改成子路径重新打包。现象jar 起来几秒就退出。原因端口被占或 Redis 连不上异常打到msg.log里了。解决tail -f msg.log看首个异常堆栈netstat -tlnp | grep 8080查端口。现象Windows 下 dist 里加了WEB-INF但刷新还是 404。原因web.xml版本与 Tomcat 不匹配或文件放错层级应在 dist/WEB-INF/web.xml。解决核对版本号重启 Tomcat。现象菜单能显示但点进去接口 401。原因token 没带上或 Redis 里 token 已过期。解决看请求头有没有Authorization清缓存重新登录检查 Redis 服务时间与服务器是否一致。5. 快速定位部署故障我的分层排查顺序折腾多了以后我形成了一个固定的排查顺序从外到内一层层剥基本十分钟内能定位到是哪一层的问题。第一步永远是看浏览器 Network 面板把所有红色请求按类型分类静态资源、接口、第三方。静态资源 404 查publicPath和 Nginxroot接口 404 查proxy_pass斜杠和 context-path接口 500 直接跳去看msg.log第三方报 CORS 走第 4 章的处理。这一步能砍掉八成“感觉哪里都坏了”的假象。第二步看后端日志的首个异常。tail -n 200 msg.log足够异常堆栈的第一行和 caused by 那几行才是根因后面的都是连锁反应。Redis 连不上、端口占用、数据库连不上、配置文件没加载日志里都有明确关键字比在前端猜快得多。第三步做连通性验证绕过前端直接打接口curl -i http://127.0.0.1:8080/getInfo curl -i http://127.0.0.1/prod-api/getInfo第一条通第二条不通问题在 Nginx 转发两条都不通后端没起来或者路径不对。这样能立刻把 Nginx 和后端两个嫌疑分开。现象优先检查常见根因整页白屏Network 静态资源publicPath、Nginx root接口 404proxy_pass 结尾斜杠路径被截断或多一层前缀登录后空白server.xml Context缺少根路径映射刷新 404try_files / web.xmlhistory 路由无回退菜单空Redis /getRouters缓存服务未启动跨域红字VUE_APP_BASE_API请求绕过代理直连后端还有一个笨但有效的习惯每次改完配置先nginx -t、再 reload、再刷新三步都确认了才继续下一步绝不一次性改三处再一起重启。早期我图省事一次改 Nginx 配置、vue.config.js和server.xml结果页面好了但不知道是哪一项起的作用下次换个环境又从头踩一遍。后来强制自己一次只动一个变量改完记录一句“改了 X现象从 A 变成 B”排错速度反而快了很多。这套部署文档里 LinuxNginx、WindowsTomcat、跨域处理三部分的内容配合上面这个顺序用基本能覆盖绝大多数部署期的疑难杂症。希望帮到你。本文还有配套的精品资源点击获取
