保姆级教程：从零到一搞定 RuoYi-Vue-Pro 本地部署（含 npm 依赖、MySQL 连接、演示模式关闭全流程）
从零开始部署RuoYi-Vue-Pro：完整避坑指南
第一次接触RuoYi-Vue-Pro这个前后端分离的快速开发平台时，我被它丰富的功能模块所吸引，但在本地部署过程中却踩了不少坑。从npm依赖冲突到MySQL连接配置，再到演示模式的关闭，每一步都可能让新手开发者陷入困境。本文将分享我完整部署RuoYi-Vue-Pro的经验，帮助你避开这些陷阱，快速搭建起可用的开发环境。
1. 环境准备与项目初始化
在开始之前，我们需要确保本地开发环境满足RuoYi-Vue-Pro的基本要求。这个平台基于Spring Boot和Vue.js构建，因此需要准备以下工具：
- Node.js：建议安装LTS版本（如16.x），避免使用过高版本导致兼容性问题
- Java：JDK 1.8或更高版本
- MySQL：5.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-deps- node-sass编译问题：如果遇到node-sass相关错误，可能是Node.js版本不兼容
# 解决方案：要么降低Node.js版本，要么重建node-sass npm rebuild node-sass- 内存不足：大型项目编译可能消耗大量内存
# 解决方案：增加Node.js内存限制 export NODE_OPTIONS=--max_old_space_size=4096安装完成后，可以通过以下命令启动前端开发服务器：
npm run dev3. 后端数据库配置与连接
后端项目(yudao-server)的数据库配置是另一个容易出错的环节。RuoYi-Vue-Pro默认配置是针对MySQL 8.0的，如果你使用的是MySQL 5.7，需要相应调整。
关键配置文件位置：yudao-server/src/main/resources/application-dev.yml
MySQL 5.7与8.0配置差异：
| 配置项 | MySQL 5.7 | MySQL 8.0 |
|---|---|---|
| 驱动类 | com.mysql.jdbc.Driver | com.mysql.cj.jdbc.Driver |
| 时区参数 | serverTimezone=GMT%2B8 | serverTimezone=CTT |
| SSL设置 | useSSL=false | allowPublicKeyRetrieval=true |
典型MySQL 5.7配置示例：
spring: datasource: dynamic: datasource: master: url: jdbc:mysql://localhost:3306/ruoyi-vue-pro?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%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中取消注释：
<module>yudao-module-bpm</module>- 在
yudao-server/pom.xml中取消注释BPM依赖：
<dependency> <groupId>cn.iocoder.boot</groupId> <artifactId>yudao-module-bpm-biz</artifactId> </dependency>- 工作流模块需要额外的数据库表，执行提供的SQL脚本创建
bpm_开头的表
5. 常见问题排查与解决
在实际部署过程中，你可能会遇到以下问题：
后端启动失败：
- 测试用例失败：默认配置会运行测试用例，可能导致启动失败
<!-- 在pom.xml中添加以下配置跳过测试 --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skipTests>true</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.active=prodRedis集成：
默认使用内存缓存，生产环境建议配置Redis：
spring: redis: host: localhost port: 6379 password: database: 0静态资源处理：
生产环境应该将前端构建产物部署到Nginx：
server { 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的过程就像组装一台精密仪器，每个部件都需要正确配置才能协同工作。记得在每次重大修改后备份配置文件，这样遇到问题时可以快速回滚。