从零开始部署RuoYi-Vue-Pro完整避坑指南第一次接触RuoYi-Vue-Pro这个前后端分离的快速开发平台时我被它丰富的功能模块所吸引但在本地部署过程中却踩了不少坑。从npm依赖冲突到MySQL连接配置再到演示模式的关闭每一步都可能让新手开发者陷入困境。本文将分享我完整部署RuoYi-Vue-Pro的经验帮助你避开这些陷阱快速搭建起可用的开发环境。1. 环境准备与项目初始化在开始之前我们需要确保本地开发环境满足RuoYi-Vue-Pro的基本要求。这个平台基于Spring Boot和Vue.js构建因此需要准备以下工具Node.js建议安装LTS版本如16.x避免使用过高版本导致兼容性问题JavaJDK 1.8或更高版本MySQL5.7或8.0版本均可但配置方式有所不同Maven用于后端项目依赖管理Git用于克隆项目代码# 验证Node.js和npm版本 node -v npm -v # 验证Java版本 java -version下载项目代码后你会注意到RuoYi-Vue-Pro采用了典型的前后端分离结构ruoyi-vue-pro/ ├── yudao-ui/ # 前端项目 └── yudao-server/ # 后端项目2. 前端项目配置与依赖安装进入前端项目目录(yudao-ui)后首先需要安装依赖。这里往往是第一个坑点——现代npm版本对peer依赖的严格检查可能导致安装失败。常见问题及解决方案peer依赖冲突当看到类似peer eslint 1.6.0 7.0.0的错误时说明npm无法自动解决依赖版本冲突# 解决方案使用--legacy-peer-deps参数绕过严格检查 npm install --legacy-peer-depsnode-sass编译问题如果遇到node-sass相关错误可能是Node.js版本不兼容# 解决方案要么降低Node.js版本要么重建node-sass npm rebuild node-sass内存不足大型项目编译可能消耗大量内存# 解决方案增加Node.js内存限制 export NODE_OPTIONS--max_old_space_size4096安装完成后可以通过以下命令启动前端开发服务器npm run dev3. 后端数据库配置与连接后端项目(yudao-server)的数据库配置是另一个容易出错的环节。RuoYi-Vue-Pro默认配置是针对MySQL 8.0的如果你使用的是MySQL 5.7需要相应调整。关键配置文件位置yudao-server/src/main/resources/application-dev.ymlMySQL 5.7与8.0配置差异配置项MySQL 5.7MySQL 8.0驱动类com.mysql.jdbc.Drivercom.mysql.cj.jdbc.Driver时区参数serverTimezoneGMT%2B8serverTimezoneCTTSSL设置useSSLfalseallowPublicKeyRetrievaltrue典型MySQL 5.7配置示例spring: datasource: dynamic: datasource: master: url: jdbc:mysql://localhost:3306/ruoyi-vue-pro?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLfalseserverTimezoneGMT%2B8 driver-class-name: com.mysql.jdbc.Driver username: root password: yourpassword注意创建数据库时请确保字符集为utf8mb4以支持完整的Unicode字符集4. 演示模式关闭与功能启用RuoYi-Vue-Pro默认启用了演示模式(demo模式)这会限制许多写操作。要关闭演示模式需要修改以下配置找到application-dev.yml中的演示模式配置demo: enabled: false # 改为false关闭演示模式某些模块(如BPM工作流)默认是禁用的需要手动启用在根目录pom.xml中取消注释moduleyudao-module-bpm/module在yudao-server/pom.xml中取消注释BPM依赖dependency groupIdcn.iocoder.boot/groupId artifactIdyudao-module-bpm-biz/artifactId /dependency工作流模块需要额外的数据库表执行提供的SQL脚本创建bpm_开头的表5. 常见问题排查与解决在实际部署过程中你可能会遇到以下问题后端启动失败测试用例失败默认配置会运行测试用例可能导致启动失败!-- 在pom.xml中添加以下配置跳过测试 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId configuration skipTeststrue/skipTests /configuration /plugin端口冲突修改application-dev.yml中的server.port配置server: port: 9088 # 改为未被占用的端口前端开发建议使用VSCode作为开发IDE安装Vetur插件获得更好的Vue开发体验开发时开启ESLint实时检查保持代码规范合理利用RuoYi-Vue-Pro提供的代码生成器功能快速开发基础CRUD功能性能优化前端打包时启用gzip压缩后端适当调整Druid连接池参数生产环境务必关闭Swagger等开发工具6. 项目结构与核心功能探索成功部署后建议花时间了解RuoYi-Vue-Pro的项目结构和核心功能模块后端主要模块系统管理用户、角色、菜单、部门等基础权限控制工作流程基于Activiti的业务流程管理需额外配置代码生成自动生成前后端基础代码监控中心系统日志、服务监控等前端技术栈Vue 2.x Element UI主体框架Vue Router处理路由Vuex状态管理Axios HTTP客户端开发工作流建议使用代码生成器创建基础模块在前端src/views下开发页面组件在后端对应模块中添加业务逻辑利用内置的权限注解控制访问权限7. 进阶配置与优化当基本功能运行正常后可以考虑以下进阶配置多环境配置RuoYi-Vue-Pro支持通过profile区分不同环境# 启动生产环境配置 java -jar yudao-server.jar --spring.profiles.activeprodRedis集成默认使用内存缓存生产环境建议配置Redisspring: redis: host: localhost port: 6379 password: database: 0静态资源处理生产环境应该将前端构建产物部署到Nginxserver { listen 80; server_name yourdomain.com; location / { root /path/to/dist; index index.html; try_files $uri $uri/ /index.html; } location /prod-api/ { proxy_pass http://localhost:9088/; proxy_set_header Host $host; } }安全加固修改默认的Shiro加密密钥关闭不必要的API文档暴露定期更新依赖库版本部署RuoYi-Vue-Pro的过程就像组装一台精密仪器每个部件都需要正确配置才能协同工作。记得在每次重大修改后备份配置文件这样遇到问题时可以快速回滚。