从零搭建若依前后端分离项目：本地开发环境配置全攻略

1. 开发环境准备第一次接触若依框架的开发者往往会被复杂的配置步骤劝退。其实只要按照正确的顺序搭建环境整个过程可以非常顺畅。我经历过三次完整的若依项目部署总结出了一套最适合新手的配置方案。首先需要准备以下工具后端开发工具IntelliJ IDEA社区版完全免费前端开发工具WebStorm或VS Code推荐后者更轻量版本控制Git客户端运行环境JDK 1.8、Node.js 14这里有个常见误区很多教程会推荐安装最新版JDK但实测JDK 1.8与若依框架的兼容性最好。我曾在JDK 11环境下遇到奇怪的类加载问题切换回1.8后立即解决。Node.js则建议选择14.x或16.x的LTS版本避免使用太新的版本导致依赖冲突。2. 项目获取与初始化2.1 克隆项目代码打开Git Bash执行以下命令国内用户推荐使用Gitee镜像git clone https://gitee.com/y_project/RuoYi-Vue.git克隆完成后用IDEA打开项目时有个关键技巧不要直接点击Open而是选择Open as Maven Project。这样IDEA会自动识别pom.xml并建立正确的项目结构。我第一次部署时就栽在这里直接Open导致Maven依赖全部报错。2.2 数据库配置在MySQL中创建名为ry-vue的数据库然后执行项目sql目录下的两个脚本ry_20240629.sql- 核心业务表结构quartz.sql- 定时任务相关表特别提醒若依默认使用MySQL 5.7的语法如果你用的是MySQL 8.0可能会遇到GROUP BY语法问题。解决方法是在application-druid.yml中增加连接参数url: jdbc:mysql://localhost:3306/ry-vue?useSSLfalseserverTimezoneAsia/Shanghaisql_modeSTRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION3. 后端服务启动3.1 依赖问题排查首次导入项目后Maven可能需要较长时间下载依赖。如果遇到某些依赖下载失败可以尝试以下方案检查Maven配置的镜像源是否为阿里云删除本地仓库中对应的依赖目录后重新下载对于顽固性报错的依赖可以手动下载jar包放入本地仓库3.2 启动主类找到RuoYiApplication.java右键运行常见启动问题及解决方案端口冲突修改application.yml中的server.portRedis连接失败确保已启动Redis服务检查密码配置数据库连接失败检查application-druid.yml中的用户名密码启动成功后控制台会打印出Swagger文档地址通常为http://localhost:8080/swagger-ui.html这是验证接口是否正常工作的好方法。4. 前端环境搭建4.1 Node.js环境配置进入ruoyi-ui目录后建议先执行以下命令切换淘宝镜像源npm config set registry https://registry.npmmirror.com然后安装依赖npm install如果遇到peer dependency冲突可以尝试npm install --legacy-peer-deps4.2 启动前端服务执行开发模式启动命令npm run dev成功启动后浏览器访问http://localhost:80应该能看到登录页面。这里有个细节若依前端默认使用80端口如果被占用会导致启动失败。修改端口可以在vue.config.js中调整devServer.port。5. 常见问题解决方案5.1 跨域问题处理开发模式下常见的前后端跨域问题可以通过配置前端代理解决。修改vue.config.js中的proxy配置proxy: { /api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: } } }5.2 静态资源404生产环境部署后出现静态资源404通常需要检查Nginx配置中的root路径是否正确指向dist目录前端路由模式是否与Nginx配置匹配history模式需要特殊配置静态资源路径是否使用了绝对路径5.3 权限校验失败如果遇到接口返回401未授权检查是否在请求头中携带了有效的tokentoken是否已过期默认有效期2小时后端是否启用了权限校验开发时可暂时关闭6. 开发效率优化技巧6.1 代码热更新配置在前端开发时可以通过调整webpack配置加快编译速度。在vue.config.js中添加configureWebpack: { cache: { type: filesystem } }6.2 接口Mock方案前后端并行开发时可以使用Mock.js模拟接口数据。在ruoyi-ui中已经内置支持只需在src/api目录下创建对应的mock文件即可。6.3 自动化部署脚本编写简单的shell脚本可以简化部署流程#!/bin/bash # 后端打包 mvn clean package -DskipTests # 前端打包 cd ruoyi-ui npm run build:prod经过这样完整的配置后你的若依开发环境就已经准备就绪了。这套配置方案在我参与的三个企业级项目中都验证过稳定性遇到任何问题都可以参考官方文档或社区讨论。