简介：若依前后端分离项目是目前广泛使用的开源快速开发平台，前端采用 Vue 与 Element UI，后端基于 Spring Boot、Spring Security、Redis 和 Jwt，并支持代码生成器一键生成前后端代码。部署文档面向后台开发、实施运维以及需要自行搭建若依环境的开发者，覆盖 Linux+Nginx 与 Windows+Tomcat 两种典型环境的完整部署流程，并针对跨域调用第三方 API、部署后菜单打不开和刷新页面出现 404 等常见问题给出具体解决方案。文档以 docx 格式提供，压缩包共 1 个文件，大小仅 223KB，内容精炼且步骤明确，包含 jar 包打包、前端 dist 构建、Redis 与 Nginx 代理配置、Tomcat 部署及 web.xml 路由修复等关键操作，同时梳理了后端 CORS、前端 proxy 与 Nginx 转发三种跨域处理思路。已有 7761 人学习，说明其具有较强的实用性与参考价值，能够帮助开发者系统掌握若依前后端分离项目的部署、排错与环境适配方法，显著降低上线试错成本。
1. 若依前后端分离项目到底在部署什么：一张链路图拆清角色
刚接触若依这套著名免费框架的人，最容易把“部署”想成“把代码跑起来”。前后端分离项目的部署，其实是在部署四个独立角色：后端服务、前端静态站点、MySQL数据库、Redis缓存。很多人翻车，不是代码有问题，而是没搞清这四个角色彼此的通信关系就急着启动，结果前端打不开、后端连不上库、验证码不显示，每一处都在报错，但又不知道先查哪个。
若依前后端分离版的价值在于：它把权限、菜单、用户、字典、日志这些后台管理系统的通用能力做成了开箱即用的底座，你要做的只是把它部署起来，再往里面填业务代码。适合谁？适合需要快速搭起一套管理后台的中小团队，也适合刚入门想看清“一个真实企业级项目长什么样”的开发者。本文从环境准备到前后端启动再到踩坑排查，按一线实际操作顺序写，每一步都给命令和参数说明，照着做能少走很多弯路。
2. 部署前的准备：版本组合、JDK与Node、中间件规划
2.1 版本组合与运行环境选型
部署若依前后端分离版，第一步不是敲命令，而是确认本机环境。这里有一个核心认知：后端用的是Spring Boot框架，前端用的是Vue技术栈，两者对运行环境的要求完全不同，你至少要装齐 JDK、Maven、Node.js、MySQL、Redis 这五样，缺一个都会在中途卡住。
我一般会先检查 JDK 版本，因为后端代码编译和运行都依赖它。若依要求 JDK 1.8 及以上，考虑到新机器上可能存在多个 JDK 版本，建议在命令行里显式确认当前生效的版本。
java -version echo $JAVA_HOME逻辑说明：第一条命令打印当前用的 JDK 版本，第二条打印环境变量指向的 JDK 安装路径。若依的项目脚本里会用到 JAVA_HOME 来定位 java 可执行文件，这个变量没配好，后面启动后端一定会报“找不到主类”或者“无法加载 main 类”的错误。参数说明：如果你本机装了 1.8 和 11 两个版本，务必让 JAVA_HOME 指向 1.8，有些较新版本的部署文档会要求更高版本，但以当前主流的若依分支为准，JDK 1.8 是最稳妥的。
前端方面，若依前端基于 Vue CLI 构建，Node.js 版本不要追求最新，14 到 16 之间的 LTS 版本足够稳定。版本太新可能导致 node-sass 这类依赖编译失败，版本太旧又跑不动 CLI 工具。检验前端环境用下面命令：
node -v npm -v逻辑说明：确认 Node 与 npm 都可用。后续前端依赖安装和生产构建全部依赖这两个命令，如果 npm 版本过旧，安装依赖时会有大量警告。我用 16 以上的 LTS 版本，配合 npm 镜像源，整个安装过程基本不需要额外折腾。
2.2 MySQL与Redis的规划与参数
两个中间件中，MySQL 承担业务数据存储，Redis 承担验证码、会话和缓存数据。很多新手只装 MySQL 而忘记 Redis，或者 Redis 没设密码，部署完登录页验证码一直转圈。先规划好再动手能避免这些问题。
MySQL 方面建议单独建一个库，字符集用 utf8mb4，排序规则用 utf8mb4_general_ci 即可。版本选 5.7 或 8.0 都行，若依官方默认兼容这两类。需要注意 8.0 的驱动名和连接参数与 5.7 不同，后面配置数据源时要对应改。
Redis 方面，若依默认配置会要求 Redis 有密码，默认密码是 123456。这个密码不是改着玩的，而是框架里 RedisConfig 读取配置的默认值。如果你本机的 Redis 没设密码，后端启动时会有大量连接报错，但服务又不会立刻挂掉，看起来像“假死”。
2.3 配置清单：先改这四处
在启动任何代码之前，我把需要改的配置先列出来，避免部署到一半再回头翻文件。第一处是后端配置文件里数据库连接信息，第二处是 Redis 连接信息，第三处是前端环境变量里指向后端的接口地址，第四处是 Nginx 反向代理的转发目标。这四处不提前改好，后面无论怎么调都是白费功夫。
后端配置文件路径一般在若依代码的 ruoyi-admin 模块下，文件名类似 application-druid.yml 和 application.yml。MySQL 连接配置长这样：
spring: datasource: driverClassName: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8 username: root password: your_password逻辑说明：url 里指定了数据库名 ry-vue、编码格式、时区参数。serverTimezone=GMT%2B8 是必不可少的，否则 JDBC 驱动会拿本机时区去连库，一旦数据库服务器时区不同就会出现日期偏移。useSSL=true 在本地环境容易引发证书告警，如果连不上库，可以先把这个参数改为 false 再试。参数说明：username 和 password 按你本机 MySQL 实际账号填写，建议不要用 root，单独建一个业务账号并授权到 ry-vue 库，降低风险。
Redis 配置一般在同一个配置文件里：
spring: redis: host: localhost port: 6379 password: 123456逻辑说明：host 和 port 指向本机 Redis 服务。password 必须与你实际启动 Redis 时设置的密码一致，如果不一致，验证码功能和会话管理都会异常。
3. 后端部署：Maven打包到进程启动
3.1 代码结构与Maven多环境profile
拿到若依后端代码后，先看目录结构。它不是一个独立的 Spring Boot 单工程，而是多模块 Maven 项目。常见模块包括 ruoyi-admin（启动模块）、ruoyi-framework（框架核心）、ruoyi-system（系统业务）、ruoyi-common（公共工具）、ruoyi-quartz（定时任务）、ruoyi-generator（代码生成）。这种分模块结构的好处是业务代码和框架代码解耦，但打包时要注意依赖顺序，直接用 Maven 的 reactor 机制处理即可。
多环境支持是若依的一个亮点。在 ruoyi-admin 的 pom.xml 里通过 profile 定义了 dev、prod 等多套环境，每套环境对应不同的配置文件。比如 application-dev.yml 里数据源指向本地库，application-prod.yml 里指向生产库。打包时指定一个环境，Maven 会把对应配置打入最终产物。
3.2 修改application配置的最小改动
部署前我通常在 application-druid.yml 里只改三类内容：数据库地址、Redis地址、日志级别。日志级别默认是 info，生产环境可以调成 warn 减少输出，排查问题时临时调回 debug。改了配置文件后要同步修改多环境中的那一份，比如你准备用 dev 环境部署，就改 application-dev.yml。
另外注意一个隐藏点：若依整合了 Druid 连接池，Druid 有独立的监控页配置。部署后如果不小心把 Druid 的 Web 控制台暴露到公网，会有安全隐患。本地部署不需要看监控页时，建议把 Druid 的 stat-view-servlet 的 enabled 设为 false。
3.3 打包命令与启动、日志查看
打包这一步最常见的问题是 Maven 依赖下载慢或者下载失败。第一次构建要拉大量依赖，耗时可能超过十分钟。为了让构建不出幺蛾子，建议在 Maven 的 settings.xml 里配置国内镜像源后再执行打包。
mvn clean package -Dmaven.test.skip=true -P prod参数说明：clean 会先清掉旧的 target 目录，避免残留 class 文件影响打包结果；Dmaven.test.skip=true 跳过测试，若依自带了一些单元测试，跑测试不仅慢，还可能因环境差异失败；P prod 指定使用 prod 环境配置打包。命令执行完毕后，在 ruoyi-admin 模块的 target 目录下会生成一个 jar 文件。
启动后端服务时，如果直接在会话窗口里运行 java -jar，一旦关掉终端服务就停了。我用 nohup 方式启动：
nohup java -jar ruoyi-admin.jar --server.port=8080 > logs/run.log 2>&1 &逻辑说明：nohup 让进程忽略挂断信号，& 让命令后台执行，输出重定向到 logs/run.log，这样查看日志也方便。--server.port=8080 指定后端端口，后续接 Nginx 时这个端口会被作为反向代理目标。参数说明：日志文件路径可以自定义，但目录要先创建好，否则启动会报错。
启动后第一时间不是等“启动成功”提示，而是看日志有没有异常。Spring Boot 启动过程会打印数据源初始化、Redis 连接、Mapper 注册等关键日志。看到形如“Started RuoYiApplication”的字样才算真正成功。如果卡住不动，多半是连不上数据库或者 Redis，此时用下面命令看日志尾部：
tail -n 100 logs/run.log3.4 换成Docker部署怎么做
如果目标服务器上已经装了 Docker，用容器方式部署更加省心。常见做法是写一个 Dockerfile，把打包好的 jar 放进去，再用 docker run 指定端口和网络。这里给你一个最小可用的扩展用法：
docker run -d --name ruoyi-admin \ -p 8080:8080 \ -v /opt/ruoyi/logs:/logs \ -e TZ=Asia/Shanghai \ ruoyi-admin:latest逻辑说明：-p 把容器内的 8080 映射到宿主机 8080，-v 把日志目录挂载出来方便查看，-e TZ 设置容器时区。这么做之后要记住：MySQL 和 Redis 如果在宿主机上而不是容器里，连接地址不能写成 localhost，要改成宿主机在 Docker 网络中的 IP，或者用 --network=host 模式启动容器。这个坑我踩过两次，容器里连 localhost 连到的是容器自身，而容器里根本没有数据库服务。
4. 前端部署：Nginx托管与代理
4.1 前端环境与依赖安装
后端服务跑起来之后，前端部署相对简单一些。前端项目用 Vue CLI 构建，拿到源码后在项目根目录执行依赖安装。这里最让人头疼的是 node-sass 安装失败，因为需要本地编译，常有网络和 Python 环境问题。若依新版前端已经转向 sass 或者 dart-sass，但老分支还会遇到这个问题。
npm install --registry=https://registry.npmmirror.com参数说明：--registry 参数临时指定镜像源，避免默认源速度慢。这里不写死某个具体版本号，因为不同若依分支的 package.json 依赖版本差异较大。安装结束后执行 npm run build:prod 把前端代码打包成静态文件。注意区分 build:prod 和 build:dev，前者面向生产环境，后者面向开发联调，部署时要选 prod。
构建完成后，dist 目录就是 Nginx 要托管的静态文件。在构建之前，要先检查前端源码里的 .env.production 文件，里面配置了后端 API 的基础地址。通常写法是：
VUE_APP_BASE_API = '/prod-api'这个值不直接写死后端 IP，而是用一个路径前缀，由 Nginx 将 /prod-api 开头的请求转发到后端服务。好处是前端和后端解耦，换服务器时只需改 Nginx 配置，前端不用重新打包。
4.2 Nginx配置与参数说明
Nginx 配置是整个前端部署里最关键的环节。由于若依前端是单页应用，路由使用了 history 模式，所以 Nginx 必须做 try_files 配置来处理前端路由，否则刷新页面或直接访问子路由时会返回 404。
server { listen 80; server_name localhost; 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; } }配置说明：location / 负责托管前端静态文件，root 指向构建产物 dist 目录；try_files 的作用是当 Nginx 找不到对应文件时回退到 index.html，交给前端路由处理。location /prod-api/ 是反向代理关键，proxy_pass 后面写后端服务地址，注意 http://127.0.0.1:8080/ 末尾的斜杠，它会将 /prod-api/xxx 转换为 /xxx 转发给后端，换句话说后端接口路径里不需要带 prod-api 前缀。如果不带末尾斜杠，转发时会保留 prod-api 前缀。
改完 Nginx 配置后，先执行 nginx -t 验证语法，再执行 nginx -s reload 平滑加载。这一步非常关键，Nginx 语法检查报错不会影响现有进程，但 reload 会加载新配置，配置写错会导致服务异常。
4.3 前端构建包管理
构建产物 tracking。前端构建完成之后输出一堆编译提示，很多人只挑重点看。要养成一个习惯：检查 dist 目录下的 index.html 和 static 目录是否存在，并且文件权限是否允许 Nginx 进程读取。权限不足时 Nginx 会返回 403，日志里出现 permission denied。
5. 若依部署避坑清单：5个高频问题与排查路径
5.1 前端白屏，控制台报错找不到 chunk
现象：浏览器打开页面一片空白，F12 看到很多 chunk 文件加载失败，状态码 404。
原因：构建产物里的 JS 文件被拆分成多个 chunk，部署时 dist 目录没有完整复制，或者 Nginx 的 root 路径指错。
解决：核对 Nginx 的 root 路径与实际 dist 目录是否一致，用 ls 查看目录下文件。另外检查 index.html 里的资源引用路径是绝对路径还是相对路径，若依默认配置构建出的资源使用相对路径，需要确保 Nginx location 配置中 alias 或 root 与 dist 结构匹配。
5.2 登录接口报跨域，但前端代理已配置
现象：登录时请求能发出去，但浏览器控制台出现 CORS error，接口返回 401 或者 403。
原因：请求绕过 Nginx 直接打到了后端，或者 Nginx 和后端之间缺少请求头转发。若依后端本身配置了跨域支持，但仅对合法来源生效。当浏览器直接访问后端端口 8080 时，后端会校验来源域名；通过 Nginx 转发时，如果没带上 Host 头，后端拿到的 Host 与预期不一致。
解决：确保前端页面通过 Nginx 端口访问，而不是直接访问后端端口。同时按上文的 Nginx 配置补上 proxy_set_header Host $host。如果想彻底关闭跨域限制以便联调，可以修改后端 SecurityConfig 里的跨域配置，但生产环境不推荐。
5.3 验证码一直不显示，接口500
现象：登录页验证码图片一直转圈不加载，后端日志里提示 redis 连接失败。
原因：Redis 配置问题和密码不匹配。若依的验证码存储依赖 Redis，Redis 连不上时验证码接口就会报错。
解决：确认 Redis 服务启动，并用 redis-cli ping 验证。再检查后端配置里的 password 字段，与 Redis 启动时的 requirepass 参数保持一致。如果 Redis 是在 Docker 里启动的，注意端口映射是否正常。
5.4 菜单渲染出来了，但接口请求都是404
现象：登录成功后页面框架出来了，所有列表数据加载不出来，接口 404。
原因：后端接口前缀和 Nginx 转发规则不匹配。前端请求路径是 /prod-api/system/user/list，Nginx 转发时因为 proxy_pass 后缀写法不对，把 /prod-api 也转发到了后端，后端没有这个路径前缀所以 404。
解决：检查 proxy_pass 末尾是否写了斜杠。确保 /prod-api/ 转发时剥离前缀，也就是写成 proxy_pass http://127.0.0.1:8080/，让后端收到的路径是 /system/user/list。
5.5 日志里大量异常但服务没挂
现象：后台报很多类似“Error updating database. Cause: ... ”的异常，但服务进程还在运行。
原因：常见于 MySQL 连接池失效。MySQL 的 wait_timeout 默认 8 小时，长时间空闲的数据源连接被数据库断开，而连接池没有自动剔除，下次请求继续使用失效连接就会报错。本地部署开发时很少遇到，生产环境放一晚第二天必现。
解决：调整 Druid 连接池配置，在 application-druid.yml 中加入 testWhileIdle、validationQuery 等参数，让连接池定期检测连接可用性。也可以同时调大 MySQL 的 wait_timeout，但更省事的做法是配置 Druid 的 keepAlive 参数。
6. 部署完成后的验证与一个小技巧
6.1 一份五分钟冒烟验证清单
部署完成后，我会按顺序做一次冒烟验证，而不是直接开始搬业务。
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080 curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1/prod-api/captchaImage逻辑说明：第一条命令验证后端进程是否存活，第二条命令验证通过 Nginx 转发后端接口是否正常。如果第二条返回 200，说明 Nginx 转发链路、MySQL、Redis 三大件全部通了。然后打开浏览器访问前端域名，输入默认账号密码登录，检查菜单渲染、用户列表、角色管理三个页面是否能正常加载数据。
6.2 多环境切换的一个小技巧
部署成功后，最容易被忽视的是配置管理。若依的 Maven 多环境 profile 在生产环境切换时有一个坑：不同环境的配置文件里数据库密码、Redis 密码如果写明文，一旦源代码仓库泄露，所有环境都暴露。我习惯把密钥类配置提取到启动参数里，修改启动脚本如下：
java -jar ruoyi-admin.jar \ --spring.datasource.password=xxx \ --spring.redis.password=yyy \ --server.port=8080命令行参数优先级高于配置文件，这样做的好处是同一份 jar 包可以在多个环境共用，密钥不落在代码里。参数说明：Spring Boot 允许用 --key=value 方式动态覆盖配置，适合把敏感信息从代码仓库中剥离。
这套部署流程一路走下来，踩得最多的还是环境问题而不是框架本身。我现在的习惯是部署前先检查端口占用和中间件状态，部署后先验证接口通则确认页面通，最后再处理权限和业务细节。如果你刚接触若依，按照这篇文章的顺序走一遍，至少能省下一两天的排查时间，希望帮到你。
本文还有配套的精品资源，点击获取
