RuoYi-Vue-Plus 前端项目实战指南

快速上手：从环境搭建到开发启动

准备工作：哪些工具是必备的？

在开始使用 RuoYi-Vue-Plus 前，请确保你的开发环境已安装以下工具：

• Node.js 14.x 或更高版本（JavaScript 运行环境）
• npm 6.x 或更高版本（Node.js 包管理工具）
• Git 版本控制工具（代码管理必备）

如何获取项目代码？

通过 Git 克隆项目仓库到本地：

git clone https://gitcode.com/dromara/plus-ui
cd plus-ui

如何选择合适的分支版本？

项目提供两个主要分支供选择：

• ts 分支：稳定主分支，适合生产环境使用
• dev 分支：开发测试分支，包含最新功能但可能不稳定

切换到稳定分支的命令：

git checkout ts

开发环境如何启动？

完成前期准备后，通过以下步骤启动开发服务器：

1. 安装依赖（使用国内镜像源加速）：

npm install --registry=https://registry.npmmirror.com

2. 启动开发服务器：

npm run dev

⚠️ 注意：开发环境默认访问地址为 http://localhost:80，确保该端口未被其他应用占用

图：RuoYi-Vue-Plus 登录页面背景图，展示了项目现代科技感的UI设计风格

技术解析：核心架构与API设计

技术栈有哪些关键组件？

本项目采用现代前端技术栈，主要包含： Vue3 TypeScript Element Plus Vite Pinia Vue Router 4.x

• Pinia：Vue3官方推荐的状态管理库，替代传统的Vuex
• Vite：新一代构建工具，比Webpack启动速度更快
• Element Plus：基于Vue3的UI组件库，提供丰富的界面元素

项目结构是如何组织的？

src/
├── api/               # API接口管理：按业务模块划分的请求函数
├── assets/            # 静态资源：图片、样式等
├── components/        # 公共组件：可复用的UI元素
├── directives/        # 自定义指令：扩展Vue功能
├── enums/             # 枚举类型：统一管理常量定义
├── hooks/             # 自定义hooks：封装可复用的逻辑
├── layout/            # 布局组件：页面整体结构
├── router/            # 路由配置：页面导航管理
├── store/             # 状态管理：使用Pinia存储全局数据
├── utils/             # 工具函数：通用辅助方法
├── views/             # 页面组件：具体业务页面
├── App.vue            # 根组件：应用入口
└── main.ts            # 入口文件：初始化应用

API调用有什么规范？

项目采用统一的API请求模式，以下是核心规范：

1. 请求前缀：所有接口统一使用/api前缀

2. 请求方法：

   • GET：用于数据查询操作
   • POST：用于数据新增操作
   • PUT：用于数据修改操作
   • DELETE：用于数据删除操作

3. 典型API调用示例：

// 导入请求工具
import { request } from '@/utils/request'

// 用户列表查询接口
export function getUserList(queryParams: any) {
  return request({
    url: '/api/system/user/list',
    method: 'get',
    params: queryParams
  })
}

4. 响应格式：

{
  "code": 200,          // 状态码：200表示成功
  "msg": "操作成功",     // 提示信息
  "data": {}            // 业务数据
}

功能特性：项目核心能力解析

租户管理 🏢

完整支持多租户架构，包括租户套餐管理、过期时间控制、用户数量限制等功能，满足SaaS平台的多租户隔离需求。

文件管理 📁

提供全面的文件操作功能，支持文件上传、下载、删除、预览等操作，可对接多种存储方案（本地存储、云存储等）。

代码生成 🚀

支持从数据库表结构自动生成前后端代码，包括页面、接口、模型等，大幅提升开发效率。支持多数据源配置，适应复杂业务场景。

服务监控 🖥️

集成系统监控功能，可实时查看服务器CPU、内存、磁盘、网络等状态，支持集群环境监控，及时发现系统瓶颈。

定时任务 ⏱️

完整的任务调度系统，支持任务创建、编辑、删除，提供任务执行日志和状态监控，支持分布式执行器部署。

使用案例 📚

内置丰富的功能使用示例，覆盖常用业务场景，帮助开发者快速理解和使用系统功能。

部署方案对比：如何选择适合你的部署方式？

开发环境部署

适合开发测试阶段，特点是配置简单、热更新快：

# 启动开发服务器
npm run dev

💡 提示：开发环境默认使用.env.development配置文件，可根据需要修改API代理地址

生产环境构建

用于正式环境部署前的代码构建：

# 构建生产环境代码
npm run build:prod

构建后的文件位于dist目录，可直接部署到Nginx等Web服务器。

Docker容器化部署

适合现代化部署流程，具有环境一致性和快速扩展的优势：

1. 构建生产环境代码：

npm run build:prod

2. 构建Docker镜像：

docker build -t ruoyi-vue-plus .

3. 运行容器：

docker run -d -p 80:80 --name ruoyi-frontend ruoyi-vue-plus

⚠️ 注意：-p 80:80参数表示将容器的80端口映射到主机的80端口，如需使用其他端口可修改前一个数字（如-p 8080:80）

多环境配置管理

项目通过.env文件管理不同环境的配置：

• .env.development：开发环境配置
• .env.production：生产环境配置

可在配置文件中设置API基础地址、超时时间等参数，实现不同环境的灵活切换。

常见问题解决

开发环境启动后无法访问后端API？

检查vite.config.ts中的代理配置，确保API请求被正确代理到后端服务地址。

生产环境构建后页面空白？

可能是路由模式问题，如使用history模式需在Nginx配置中添加重写规则，或改用hash模式。

依赖安装失败？

尝试清除npm缓存后重新安装：

npm cache clean --force
npm install

Docker部署后无法访问？

检查容器是否正常运行（docker ps），端口映射是否正确，以及防火墙设置是否允许相应端口访问。