1. 环境准备别急着敲代码先把“地基”打牢很多新手朋友一拿到若依前后端分离版的源码就迫不及待地想运行起来看看效果结果往往在第一步就卡住了。我见过太多人因为环境没装对折腾一整天项目都跑不起来最后心态爆炸。所以咱们第一步必须稳扎稳打把运行若依项目所必需的所有“原材料”都准备好并且确保它们的版本是兼容的。这就像盖房子地基打歪了后面砌再漂亮的砖墙也白搭。首先你需要准备四样核心工具JDK、MySQL、Redis和Node.js。它们的版本要求官方文档写得很清楚但我必须强调强烈建议使用推荐版本不要盲目追求最新。比如JDK官方推荐1.8你就用1.8。别觉得Java 17、21更新潮若依框架里很多依赖库可能还没适配你装上之后各种莫名其妙的类找不到错误排查起来能让你怀疑人生。MySQL也是5.7版本是个非常稳定且广泛兼容的选择用8.0当然可以但可能会在连接驱动或密码加密方式上遇到小麻烦对于新手来说5.7能帮你避开这些不必要的坑。Redis是很多新手最容易忽略的一环。你可能觉得我还没开始写业务代码缓存组件晚点装也行。但若依分离版的权限认证、会话管理等核心功能默认就依赖Redis如果本地没启动Redis服务后端项目是绝对启动不起来的控制台会直接报连接拒绝的错误。所以请务必在启动项目前确保Redis已经安装并成功运行在默认的6379端口上。你可以打开命令行输入redis-cli ping如果返回PONG那就说明Redis服务是正常的。至于前端环境Node.js的版本选择也有讲究。虽然官方说10但现在社区主流版本已经到了16、18甚至20。我的经验是选择**Node.js 16 LTS长期支持版**是一个比较稳妥的方案它在稳定性和对新特性的支持上取得了很好的平衡。安装Node.js时会自带npm包管理器但国内直接使用npm安装依赖可能会非常慢。这里有个关键避坑点不要图快直接安装cnpm很多教程会推荐你用cnpm但cnpm的包管理机制和npm有些差异可能会导致依赖树不一致引发各种诡异的运行时错误比如某些模块找不到或者样式加载异常。正确的做法是继续使用npm但为其配置国内的镜像源比如淘宝源这样既能保证稳定性又能提升速度。2. 项目获取与初始化克隆不是终点配置才是开始环境齐备后我们就可以把若依的代码“请”到本地了。最推荐的方式是使用Git克隆这能让你后续方便地更新代码。打开你的终端或Git Bash找一个合适的目录执行克隆命令。这里有个小细节确保你克隆的是RuoYi-Vue这个仓库它是前后端分离版。有时候新手会误克隆成单体版那代码结构就完全不一样了。代码下载完成后别急着运行。先用你熟悉的IDE比如IntelliJ IDEA或Eclipse以Maven项目的形式打开后端项目根目录。IDE会自动识别pom.xml文件并开始下载依赖。这个过程可能会花点时间取决于你的网速。如果卡在某个依赖下载不动可以检查你的Maven配置是否使用了国内的镜像仓库如阿里云Maven镜像这能极大提升下载速度。接下来是数据库初始化。你需要手动在MySQL中创建一个数据库名字可以按官方推荐的ry-vue也可以自定义。创建完成后找到项目sql目录下的那两个SQL脚本ry_2023xxxx.sql或类似命名的初始化脚本和quartz.sql。务必按顺序执行先执行主数据脚本再执行quartz定时任务相关的脚本。这一步经常出的问题是字符集如果导入后中文显示乱码记得在创建数据库时就指定字符集为utf8mb4排序规则为utf8mb4_general_ci。做完这些还有一个至关重要的步骤修改数据库连接配置。项目里关于数据库的配置通常不在一个地方新手容易改漏。核心文件是ruoyi-admin模块下的src/main/resources/application-druid.yml。你需要把里面的url、username、password改成你自己MySQL服务的地址、用户名和密码。注意如果你的MySQL不是安装在本地或者端口不是默认的3306一定要在url里修改正确。我见过有人改了密码但没改IP一直连不上本地数据库还以为是MySQL服务没启动。3. 后端启动与排错第一个“拦路虎”怎么过配置搞定激动人心的启动时刻到了。找到后端的主启动类RuoYiApplication.java直接运行它。如果一切顺利你会在控制台看到Spring Boot的Logo以及一系列初始化成功的日志。但根据我的经验一次启动成功的概率不高总会遇到些“拦路虎”。下面我就把最常见的几个错误和解决办法给你捋一捋。第一个经典错误RedisConnectionFailureException。控制台疯狂报错说连不上Redis。别慌按以下步骤排查第一你的Redis服务真的启动了吗去服务列表或者用redis-cli确认一下。第二Redis是不是设置了密码若依的默认配置是无密码的如果你安装Redis时设置了密码就需要在application.yml文件里找到spring.redis.password这个配置项填上。第三端口被占用了默认6379端口可能被其他程序占用你可以通过修改配置文件的spring.redis.port来换一个端口或者停掉占用端口的程序。第二个常见错误Unknown database ‘ry-vue‘或Access denied for user ‘root‘‘localhost‘。这显然是数据库的问题。前者是数据库没创建回去检查第二步的数据库初始化做了没。后者是账号密码错误或者root用户不允许从本地连接。你可以先用MySQL客户端工具如Navicat、命令行试试用配置文件里的账号密码能不能连上先确保数据库层面是通的。第三个可能遇到的麻烦端口冲突。若依后端默认使用8080端口。如果你电脑上已经运行了其他服务比如另一个Tomcat或者某个软件占用了8080启动就会失败。解决方法有两种一是关闭占用8080端口的程序二是在application.yml中修改server.port属性比如改成8081。改完之后记得前端配置里访问后端的地址也要相应调整。当你看到控制台打印出“RuoYi启动成功”的字样并且没有持续的错误日志刷屏时就可以打开浏览器访问http://localhost:8080如果你没改端口的话。如果能正常看到页面可能是个空白页或简单的接口测试页再用Postman或浏览器访问一个内置的API比如http://localhost:8080/api/xxx看看能否返回数据。能返回数据就证明后端服务真的在健康运行了。4. 前端启动与联调让页面“活”过来后端跑通了只是成功了一半。前后端分离项目前端是用户直接交互的界面。进入项目根目录下的ruoyi-ui文件夹这是前端Vue项目的所在地。首先我们需要安装依赖。在ruoyi-ui目录下打开终端执行npm install。这里再次强调为了避免不可预知的问题请通过以下命令指定镜像源安装而不是使用cnpmnpm install --registryhttps://registry.npmmirror.com这个过程会下载所有前端依赖包速度取决于网络请耐心等待。如果遇到某个特定包安装失败可以尝试清除npm缓存npm cache clean --force后重试。依赖安装成功后运行启动命令npm run dev这条命令会启动一个本地开发服务器通常运行在http://localhost:80端口。如果80端口被占用比如你有IIS或Apache在运行命令行会提示端口冲突。这时你需要修改前端项目的配置文件。找到ruoyi-ui目录下的vue.config.js文件里面有一个devServer配置项将其中的port属性修改为一个未被占用的端口比如8088。前端成功启动后浏览器会自动打开登录页面。但是你会发现输入默认账号密码admin/admin123点击登录后页面一直在转圈或者直接提示“网络错误”。这是前后端联调最关键的一步。问题在于前端开发服务器localhost:80在请求后端APIlocalhost:8080时由于端口不同违反了浏览器的同源策略请求被拦截了。解决方案是配置前端代理。同样在vue.config.js文件中找到devServer配置在里面添加或修改proxy设置devServer: { port: 8088, // 你修改后的前端端口 proxy: { /api: { target: http://localhost:8080, // 你的后端地址 changeOrigin: true, pathRewrite: { ^/api: /api } }, /auth: { target: http://localhost:8080, changeOrigin: true } } }这段配置的意思是将所有以/api或/auth开头的请求转发到http://localhost:8080这个后端服务上。配置完成后需要重启前端服务按CtrlC停止再重新执行npm run dev。重启后再尝试登录应该就能成功跳转到系统主页了。看到那个熟悉的若依管理后台界面恭喜你本地开发环境已经全部打通5. 生产环境部署从“能跑”到“稳如老狗”在本地开发调试没问题了接下来就要考虑如何把项目部署到服务器上让其他人也能访问。部署和开发运行是两码事目标是把前后端代码打包成独立的、可在外网运行的产品。后端部署相对简单。我们需要先打包出一个可执行的JAR文件。在项目根目录下执行Maven打包命令mvn clean package -Dmaven.test.skiptrue-Dmaven.test.skiptrue参数是为了跳过测试加快打包速度。打包成功后在ruoyi-admin模块的target目录下你会找到ruoyi-admin.jar名字可能带版本号。将这个JAR文件上传到你的Linux服务器。在服务器上只需要安装好Java运行环境JRE然后使用命令运行即可java -jar ruoyi-admin.jar为了让服务在后台稳定运行不受终端关闭的影响通常会使用nohup命令nohup java -jar ruoyi-admin.jar app.log 21 这行命令会让服务在后台运行并将日志输出到app.log文件中。你还需要在服务器的防火墙或安全组规则中放行后端应用使用的端口默认8080。前端部署则是生成静态资源。在ruoyi-ui目录下执行生产环境构建命令npm run build:prod这个命令会进行代码压缩、优化最终在ruoyi-ui目录下生成一个dist文件夹。这个文件夹里就是纯粹的HTML、CSS、JavaScript文件了。你需要将这些文件部署到一个Web服务器上最常用的就是Nginx。将整个dist文件夹上传到服务器然后配置Nginx。一个基本的Nginx配置示例如下server { listen 80; server_name your-domain.com; # 你的域名或IP location / { root /path/to/your/dist; # dist文件夹的绝对路径 index index.html index.htm; try_files $uri $uri/ /index.html; # 支持Vue Router的history模式 } location /api/ { proxy_pass http://localhost:8080/; # 转发API请求到后端 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这个配置做了两件事一是将根路径的请求指向前端静态文件二是将以/api/开头的请求代理到后端Java服务。配置完成后重启Nginx通过访问你的服务器IP或域名就应该能看到完整的若依系统了。部署环节的坑主要在于路径配置错误和权限问题务必仔细检查配置文件的每一个路径并确保Nginx进程有权限读取dist目录下的文件。6. 功能扩展实战手把手教你新增一个业务模块若依框架的强大之处在于它的可扩展性。当你熟悉基本环境后肯定会需要开发自己的业务功能。这里我以一个简单的“学生信息管理”模块为例带你走一遍从建表到页面展示的完整流程这里面有几个关键点容易出错。首先在MySQL中创建一张学生表。建表语句除了字段一定要记得加注释因为若依的代码生成器会读取表注释和字段注释来生成对应的中文标签。表创建好后登录若依系统进入“系统工具” - “代码生成”菜单。点击“导入”按钮选择你刚创建的学生表。导入后在列表中点击“编辑”这里需要仔细配置生成信息。生成路径的配置是第一个坑。默认的生成路径可能不符合你的模块规划。比如你想把代码生成到一个独立的ruoyi-student模块里那么“生成包路径”就要修改为com.ruoyi.student而“前端路径”可以设置为ruoyi-student。这样生成的代码就会按这个结构来组织。模块名和包名一定要提前规划好避免生成后需要大量移动文件。配置完成后点击“生成代码”会下载一个ZIP包。解压后你会看到清晰的目录结构main下是Java后端代码controller, service, mapper, entity等vue下是前端页面代码。接下来是整合。假设你提前在IDEA里通过New - Module创建了一个Maven模块叫ruoyi-student那么你需要将ZIP包中main/java下的所有内容拷贝到ruoyi-student模块的src/main/java对应包下。在父工程的pom.xml和ruoyi-admin模块的pom.xml中添加对ruoyi-student模块的依赖。执行下载包中的sql脚本通常是menu.sql在数据库中生成访问这个新模块的菜单和权限。将ZIP包中vue文件夹下的文件拷贝到前端ruoyi-ui项目的src/views目录下建议新建一个student文件夹来存放。全部拷贝完成后重启前后端服务。这是第二个容易忘记的步骤新增了模块和菜单必须重启后端新增了前端页面文件开发模式下热更新可能不生效最好也重启一下前端服务。重启后刷新系统你应该能在侧边栏菜单里看到新增加的“学生信息管理”菜单点进去就能进行增删改查操作了。这个过程看似步骤多但理顺了就是一套固定流程多做两次就熟练了。关键就是细心确保文件放对了位置依赖添加正确。