很多同学拿到RuoYi-App的源码之后卡的时间最久的往往不是写业务代码而是把项目先跑起来。这个项目从下载、解压、配好数据库、启动后端再到前端uni-app编译整个过程看起来步骤多其实只要把链条理清楚十分钟左右就能看到登录页。这篇文章就用“若依RuoYiApp版—项目下载运行”这个主题把从零启动的完整流程、关键配置和容易踩的坑一次讲完。适合刚开始接触若依移动端、想在自己电脑上把H5、小程序或App端跑通的人无论是刚毕业准备做项目经验的应届生还是想快速搭建移动端管理后台的开发者都可以直接照着操作。1. 先搞清楚RuoYi-App到底是一个什么项目1.1 版本生态与App版定位若依RuoYi在开发者圈子里的普及程度很高因为它把权限管理、代码生成、定时任务、日志监控这些后台系统标配功能都提前做好了降低了重复开发的成本。它并不是只有一个仓库常见的有单体应用版、前后端分离版、微服务版以及本文要讲的RuoYi-App移动端版本。很多人第一次接触时容易搞反以为RuoYi-App是一个独立后端工程其实它更像一个基于uni-app技术栈开发的客户端项目主要用来输出App、H5、微信小程序等移动端界面。真正的接口服务、登录认证、菜单权限仍然复用若依的后端Spring Boot框架。这样拆分有一个很实际的好处后台管理界面和移动端界面可以共用同一套后端能力不必维护两套登录体系。比如公司要给外勤人员做一个移动审批入口PC端已经用若依体系做好的岗位权限、流程审批App版客户端直接调接口就能复用。理解了这一点下载运行时的调试思路就会清晰很多后端不通前端做得再花哨也白搭。1.2 技术栈与运行逻辑RuoYi-App版的常见技术栈大概是这样的前端uni-app基于Vue配合uView或ThornUI这类移动端组件库后端Spring Boot MyBatis MySQL Redis中间件MySQL存储业务数据Redis存储验证码、Token和部分缓存开发工具HBuilderX、微信开发者工具、Android Studio或手机模拟器运行逻辑并不复杂。前端通过HTTP请求访问后端接口后端完成认证之后返回Token前端把Token存起来后续每次请求都在Header里带上。H5开发模式下访问的是本地开发服务器再由开发服务器把/api开头的请求转发给后端小程序和App则直接访问配置的后端地址。所以如果你想复现“下载运行”的完整效果核心就是让这条“前端页面 - 后端接口 - 数据库/Redis”的链路全部通起来。2. 下载项目前先把环境清单准备好2.1 下载代码与目录说明RuoYi-App的源码一般在代码托管平台就能找到搜索“若依”或“ruoyi”就能看到相关仓库。下载有两种方式一种是git clone一种是直接下载zip压缩包。我建议优先用git clone后续更新代码、切换分支都方便直接下载zip也没问题但解压后要记得把文件夹从带中文和空格的路径里移出来否则后面编译时有些工具会处理不好路径。拿到源码后不要晕结构其实很清晰。整个仓库一般包含后端工程和前端App工程两部分后端是平时非常熟悉的Spring Boot多模块结构前端则是uni-app工程。前端工程里最重要的一层是要有manifest.json和pages.jsonHBuilderX导入项目时一定要选到这一层导错层级会导致页面全部找不到。2.2 后端环境需求我建议在下载代码之前就把环境列成一张清单免得项目拿到手后一边装软件一边报错。后端部分至少需要JDK 1.8及以上建议直接用1.8很多老版本工程在更高版本上会报反射或依赖兼容问题Maven 3.6以上用来拉取Spring Boot依赖MySQL 5.7或8.0并准备好一个空的数据库Redis 3.2及以上Windows系统可以下载对应版本也可以装进Docker里跑装的时候有两点容易忽略。第一是Redis的启动方式Windows下很多同学直接解压后双击redis-server.exe记得看一下命令行窗口是否停留在运行状态而不是一闪而过。第二是MySQL的版本如果你是MySQL 8.0一定要检查驱动版本若依初版配置里写的是5.x驱动直接启动后端会报通信链路异常手动改成8.x驱动就好。2.3 前端与调试工具前端部分主要是Node环境和HBuilderX。Node版本需要特别注意我遇到过用新版本Node执行npm install时node-sass编译失败的情况后来按工程的package.json提示切换到建议的Node版本才顺利通过。如果不想折腾多个版本可以装一个Node版本管理工具在项目目录下切换版本。HBuilderX这个工具对uni-app项目特别友好它本身内置了Node运行环境但在命令行里跑npm又是另一套。所以我平时习惯把HBuilderX当作编辑器预览工具依赖安装和编译命令还是用系统终端来执行这样报错更直观。如果你要跑到微信小程序还得下载微信开发者工具并提前把它安装好。注意在开发者工具的“工具 - 安全设置”里打开服务端口不然HBuilderX点击“运行到小程序模拟器”时会提示连接失败。如果后面要跑原生App真机调试最好也装好Android SDK或者使用数据线连接手机并开启开发者选项里的USB调试。3. 后端启动这是整个链路的地基3.1 数据库初始化先把后端工程导入开发工具直接打开工程根目录等待Maven自动下载依赖。在等待的时候可以先把数据库准备好否则后端启动也会失败。打开数据库管理工具新建一个数据库字符集建议选择utf8mb4排序规则选择utf8mb4_general_ci。接着找到源码里的sql目录里面一般会有两个脚本一个是quartz.sql定时任务表另一个是以日期命名的数据库初始化脚本。执行顺序最好先quartz再执行业务表初始化否则某些外键关联表可能出现找不到父表的错误。实际操作中如果报错说表已存在说明你重复执行了脚本先把库删掉重新建一个再导入就行。数据源配置在application-druid.yml里。重点核对三项数据库地址、用户名、密码。默认连接串通常长这样jdbc:mysql://localhost:3306/ry?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLtrueserverTimezoneAsia/Shanghai如果你本地MySQL用户名是root、密码不是默认的一定要改对。MySQL 8.0用户要在连接串里保留serverTimezone否则后端启动时可能因为时区问题报错。这个细节看起来小但截图报错的时候十有八九都会指向它。3.2 配置文件修改与启动验证Redis配置在application.yml里默认连接localhost:6379。如果Redis设过密码需要在配置里写入对应密码否则验证码功能会一直报“Unable to connect to Redis”。都改好之后直接运行RuoYiApplication主类看到Console输出类似“Started RuoYiApplication in xxx seconds”的字样就说明后端启动了。打开浏览器访问http://localhost:8080如果能看到若依的登录页并且验证码图片能正常显示说明MySQL和Redis都是好的。注意这里还不需要启动前端后端登录页能打开才代表接口服务没有大问题。如果启动失败最常见的几个现象我后面单独列在排查章节。这里想强调一点后端是整个链路的地基不要急着去折腾前端。我见过有同学前端运行起来了但验证码一直刷不出来折腾半天才想起Redis没开。4. 前端App版启动从依赖到三端预览4.1 HBuilderX导入与依赖安装前端工程是uni-app类型目标平台是H5、小程序和App。用HBuilderX打开工程目录时要选择包含manifest.json的那一层而不是仓库的根目录。打开之后先不要急着点运行。我一般会先看看工程有没有package.json有的话就打开系统终端执行依赖安装npm install如果网络条件不理想依赖下载会很慢甚至卡在某个包上面。可以先切换npm镜像源再装npm config set registry https://registry.npmmirror.com npm install装的时候注意看日志是否有node-sass、canvas这类需要本地编译的包报错。如果报“Failed at the node-sassxxx install script”大概率是Node版本不匹配切换Node版本后删掉node_modules目录重新install。4.2 H5运行调试依赖装好后在HBuilderX里选择“运行 - 运行到浏览器 - Chrome”首次编译会慢一点等浏览器弹出页面就好。H5模式下前端默认的开发端口可能是8080或8081如果你同时开着后端最好先确认有没有端口冲突。H5开发模式下前端页面要能请求到后端接口通常靠manifest.json里配置的devServer代理。默认配置会把/api前缀的请求转发到http://localhost:8080。如果你后端端口改过这里也要同步修改。改完配置后需要重新编译因为HBuilderX不一定每次都会自动热更新代理配置。打开页面后按F12观察Network。如果登录接口返回404或500先别改前端回到后端看控制台有没有异常日志。如果响应里出现“跨域”字眼大概率是代理没生效检查代理配置里路径和target是否与后端一致。4.3 小程序运行小程序端和H5不一样H5可以靠代理解决跨域小程序直接请求后端接口时需要注意域名校验。开发阶段最简单的方案是在微信开发者工具里点击“详情”勾选“不校验合法域名、web-view业务域名、TLS版本以及HTTPS证书”。这样本地开发时即使后端是http://localhost:8080也能被访问。在HBuilderX里点击“运行 - 运行到小程序模拟器 - 微信开发者工具”如果提示“未配置微信开发者工具路径”在设置里选择安装目录即可。第一次编译Project会被自动打开窗口里会生成一个临时项目目录这个目录不要手动删除否则下次运行会重新编译。跑通小程序的关键检查点有两个一是微信开发者工具的服务端口是否开启二是当前微信扫码登录的账号是否已经实名。很多人在第二步卡住的时候会怀疑代码有问题其实只是工具侧没有准备好。4.4 App真机运行App真机的坑通常出在地址上。如果用数据线连接手机并运行到自定义调试基座手机端访问后端的地址不能是localhost因为手机上的localhost指向手机自己。需要把后端地址改成电脑的局域网IP同时确保手机和电脑连接的是同一个局域网然后检查本机防火墙是否放行8080端口。要获取局域网IPWindows下可以打开命令行输入ipconfig找到无线局域网适配器的IPv4地址填到前端的请求地址配置里。如果前后端不在同一个网络环境下比如电脑连的是有线网、手机连的是另外一个WiFi即使IP填对了也访问不到。如果不方便真机调试可以先跑通H5再说。H5能把登录流程跑通App端只是多了一个网络地址跨越的问题思路是一样的。另外首次在手机上显示登录页时如果图片验证码请求非常慢多半是后端Redis的TTL策略或者网络延时属于正常体验问题不影响调试。5. 下载运行阶段的常见坑位与排查实录5.1 后端起不来的问题我把实际遇到过的坑按现象整理一下。现象一后端启动时报端口被占用。这个最简单查看8080端口netstat -ano | findstr 8080找到占用进程后结束它或者改掉若依的server.port。现象二启动过程报“Unable to connect to Redis”。检查Redis有没有运行Windows下直接看窗口是否还在Linux下用ps -ef | grep redis检查。如果有密码看redis.conf里的requirepass和application.yml是否一致。现象三数据库连接报错“Public Key Retrieval is not allowed”。这是MySQL 8.0配合新版连接驱动时常见提示方法是在JDBC连接串里加上allowPublicKeyRetrievaltrue。现象四启动成功但页面验证码不显示。这种情况通常是Redis连接成功但数据没写进去或者前端H5代理把验证码接口解析错了。可以先用浏览器直接访问后端验证码接口看有没有JSON返回。5.2 前端接口请求不到前端编译成功、页面能打开但一登录就提示“网络异常”这是下载运行阶段最高频的问题。排查顺序建议是这样第一确认后端有没有起来访问http://localhost:8080看登录页是否能显示。第二确认前端代理是否生效H5打开后在控制台看请求路径如果请求地址里端口是8081而不是8080说明代理没有匹配。第三直接调用接口测试例如登录接口返回的状态码是200但逻辑失败问题在前端参数格式如果返回的是连接失败问题在链路或防火墙。把这三个层次分清楚就不会在前端反复改代码了。大多数情况下后端没起来或代理没匹配是主因。还有一次我遇到前端页面能打开但验证码请求地址里根本没有/api前缀那是因为没有重新编译代理配置改了但没有生效。5.3 多端编译的奇奇怪怪问题小程序白屏先看编译日志其次是微信开发者工具里是否有JS报错。常见是没有完整安装依赖或者引用了浏览器独有的API这种API在小程序环境不存在。H5页面样式错乱uView这类组件库的样式在H5和小程序可能表现不一致优先确认组件库版本和uni-app编译器版本是否匹配。App端请求超时90%是地址问题。说过很多次把localhost改成电脑局域网IP。另外检查手机和电脑是否同一局域网有些路由器开启AP隔离后两个设备连同一个WiFi但互相访问不通这种就要换热点或者关掉隔离功能。5.4 常见问题速查表现象可能原因快速处理办法后端启动时提示端口占用8080端口被其他程序占用结束占用进程或修改server.port验证码一直加载失败Redis未启动/密码错误启动Redis并核对application.yml数据库连接报错MySQL驱动版本或时区问题更新驱动连接串加serverTimezonenpm install卡住或失败网络或Node版本不匹配切换npm镜像切换Node版本后重装H5能开但接口404代理配置未生效/端口不一致检查manifest.json里的devServer与target小程序请求不到接口域名校验拦截开发者工具详情里勾选“不校验合法域名”App真机调接口超时地址写成了localhost改成电脑局域网IP核对防火墙编译时提示找不到模块依赖不完整删除node_modules后重新install这张表基本覆盖了RuoYi-App下载运行阶段七成的问题。如果你遇到的不在上面建议打开后端控制台和前端控制台把两边的报错时间线对齐往往能更快定位。6. 跑通之后我想说的几点实际心得我前前后后帮身边的同事和朋友跑过好几台电脑的RuoYi-App踩得最多的不是代码本身而是环境假设不一致。比如有人项目没下完整有人MySQL密码记错有人微信开发者工具没开服务端口。所以如果你第一次没跑通别急着怀疑代码先把环境项逐条对一遍。有一个顺序上的小技巧不管是哪台电脑我都是先启动Redis再启动MySQL接着启动后端最后才动前端。后端的启动日志其实已经把问题暴露得很充分只要看到验证码接口能出东西这条链路基本稳了。另外建议H5跑通之前不要直接挑战小程序或真机。H5是最容易定位问题的环境浏览器控制台、Network面板都能直接用。等H5完全正常再切换到其他端遇到问题也知道从哪个环节入手。最后想说的是RuoYi-App这个项目本身的意义不是让你学会怎么启动而是给你一套可以快速扩展的移动端基座。下载运行只是第一步真正有价值的是登录权限、路由拦截、接口封装这些已经做好的模块后续改页面、加业务逻辑时你会省下很多事。