RuoYi-Vue 前端环境搭建与部署完整教程

一、环境准备（必备工具）

1. 核心依赖

|----------|------------------|------------------------|
| 工具 | 版本要求 | 作用说明 |
| Node.js | 14.x ~ 16.x（推荐） | 前端运行环境（避免 17 + 版本兼容问题） |
| npm/yarn | 随 Node.js 自带 | 依赖包管理工具 |
| Git | 任意稳定版本 | 拉取 RuoYi-Vue 源码 |
| IDE | VS Code（推荐） | 前端开发编辑器 |
| 浏览器 | Chrome/Firefox | 本地调试预览 |

2. 工具安装步骤

（1）安装 Node.js

• 下载地址：Node.js 官网（选择 14.x 或 16.x 的 LTS 版本）

• 安装后验证（命令行输入以下命令，显示版本号即成功）：

node -v # 示例输出：v14.21.3

npm -v # 示例输出：6.14.18

• （可选）配置 npm 淘宝镜像（加速依赖下载）：

npm config set registry https://registry.npm.taobao.org

（2）安装 Git

• 下载地址：Git 官网

• 安装后验证：

git --version # 示例输出：git version 2.39.1.windows.1

（3）安装 VS Code

• 下载地址：VS Code 官网

• 推荐安装插件（提升开发效率）：

• • Vetur（Vue 语法高亮）

• • ESLint（代码规范检查）

• • Prettier（代码格式化）

二、获取 RuoYi-Vue 源码

1. 克隆官方仓库

命令行执行以下命令，拉取源码到本地（默认拉取 master 分支，稳定版）：

# 克隆Gitee仓库（国内速度快，推荐）

git clone https://gitee.com/y_project/RuoYi-Vue

2. 进入前端目录

克隆完成后，进入项目的前端子目录 ruoyi-ui：

cd RuoYi-Vue/ruoyi-ui

三、安装前端依赖

在 ruoyi-ui 目录下，执行以下命令安装项目依赖（耐心等待，首次安装可能需要 3-10 分钟）：

# 使用npm安装（默认）

npm install

# 若npm安装失败，尝试用yarn（需先安装yarn：npm install -g yarn）

yarn install

依赖安装失败解决方案

• 问题 1：网络超时 → 切换淘宝镜像（参考步骤一.2.（1））

• 问题 2：依赖冲突 → 删除 node_modules 文件夹和 package-lock.json，重新执行安装命令：

rm -rf node_modules package-lock.json # Windows系统直接手动删除

npm install

• 问题 3：权限不足（Linux/Mac）→ 命令前加 sudo：sudo npm install

四、本地开发环境配置与运行

1. 配置后端接口地址

RuoYi-Vue 前端需连接后端服务才能正常使用，修改配置文件：

• 打开 ruoyi-ui/.env.development 文件（开发环境配置）

• 找到 VUE_APP_BASE_API 字段，修改为后端服务地址（默认后端端口 8080）：

# 本地后端地址（后端启动后默认地址）

VUE_APP_BASE_API = 'http://localhost:8080'
注意：若后端部署在远程服务器，需改为服务器 IP + 端口（如 http://192.168.1.100:8080）

2. 启动本地开发服务

在 ruoyi-ui 目录下执行以下命令，启动前端开发服务器：

npm run dev

3. 访问本地页面

启动成功后，命令行会输出访问地址（默认：http://localhost:80），打开浏览器访问：

• 登录页默认账号：admin，密码：admin123

• 若能正常登录并显示系统菜单，说明本地开发环境搭建成功！

五、生产环境打包配置

1. 配置线上接口地址

修改生产环境配置文件 ruoyi-ui/.env.production：

# 线上后端接口地址（改为你的服务器后端地址）

VUE_APP_BASE_API = 'http://www.example.com:8080'

2. 执行打包命令

在 ruoyi-ui 目录下执行打包命令，生成生产环境静态文件：

# 打包生产环境（默认生成dist目录）

npm run build:prod

3. 打包结果验证

打包完成后，ruoyi-ui 目录下会生成 dist 文件夹，包含以下核心文件：

• index.html（入口页面）

• static/（静态资源：JS、CSS、图片）

• favicon.ico（网站图标）

确保 dist 目录下文件完整，无报错信息。

六、部署上线（三种常见方式）

RuoYi-Vue 前端是纯静态资源（HTML/CSS/JS），可部署在 Nginx、Tomcat、云服务器等，推荐 Nginx 部署（性能最优）。

方式 1：Nginx 部署（推荐）

（1）安装 Nginx

• 下载地址：Nginx官网（选择稳定版）

• 安装后验证（Windows 双击 nginx.exe，Linux 执行 nginx）：

访问 http://localhost，显示 Nginx 欢迎页即成功。

（2）配置 Nginx

• 找到 Nginx 配置文件（默认路径）：

• • Windows：nginx-xxx/conf/nginx.conf

• • Linux：/etc/nginx/nginx.conf 或 /usr/local/nginx/conf/nginx.conf

• 编辑配置文件，替换为以下内容（关键配置已标注）：

  worker_processes 1;

  events {
  worker_connections 1024;
  }

  http {
  include mime.types;
  default_type application/octet-stream;
  sendfile on;
  keepalive_timeout 65;

    server {
        listen       80;  # 前端访问端口（可修改为8081等）
        server_name  localhost;  # 你的域名或服务器IP
  
        # 配置静态资源路径（指向dist目录）
        location / {
            root   D:/RuoYi-Vue/ruoyi-ui/dist;  # Windows路径（替换为你的dist目录绝对路径）
            # root   /usr/local/ruoyi-ui/dist;  # Linux路径（替换为你的dist目录绝对路径）
            index  index.html index.htm;
            try_files $uri $uri/ /index.html;  # 解决Vue路由刷新404问题
        }
  
        # 反向代理后端接口（避免跨域，可选）
        location /prod-api/ {
            proxy_pass http://www.example.com:8080/;  # 你的后端接口地址
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
  
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }

  }

（3）启动 Nginx 并访问

• 重启 Nginx（使配置生效）：

• • Windows：命令行进入 Nginx 目录，执行 nginx -s reload

• • Linux：nginx -s reload

• 访问测试：打开浏览器输入 http://服务器IP:80（或你的域名），能正常登录即部署成功！

方式 2：Tomcat 部署

1. 下载 Tomcat：Tomcat 官网（选择 8.x 或 9.x 版本）

1. 将 dist 目录下的所有文件复制到 tomcat/webapps/ROOT/ 目录（覆盖原有文件）

1. 编辑 tomcat/conf/server.xml，修改端口（默认 8080，可改为 80）：

<Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443"/>

1. 启动 Tomcat：运行 tomcat/bin/startup.bat（Windows）或 startup.sh（Linux）

1. 访问：http://服务器IP（无需加端口，默认 80）

方式 3：云服务器（如阿里云 ECS）部署

1. 服务器环境准备：安装 Nginx（参考方式 1.（1））

1. 上传 dist 文件：用 Xshell、FileZilla 等工具，将本地 dist 目录上传到服务器（如 /usr/local/ruoyi-ui/dist）

1. 配置 Nginx：参考方式 1.（2），修改配置文件中的 root 为服务器上的 dist 路径

1. 开放端口：在云服务器控制台开放 80 端口（安全组规则添加入方向 80 端口）

1. 访问：http://服务器公网IP

七、常见问题排查

1. 本地启动后无法连接后端

• 检查后端服务是否已启动（访问 http://localhost:8080 看是否有响应）

• 确认 .env.development 中的 VUE_APP_BASE_API 与后端地址一致

• 后端是否配置了 CORS 跨域（RuoYi-Vue 后端默认已配置，无需额外操作）

2. 打包后页面空白 / 刷新 404

• 页面空白：检查 VUE_APP_BASE_API 配置是否正确，是否跨域

• 刷新 404：Nginx 需配置 try_files uri uri/ /index.html;（Vue 路由 history 模式要求），Tomcat 需配置 web.xml 支持 HTML5 路由

3. 部署后静态资源加载失败

• 检查 Nginx/Tomcat 配置的静态资源路径是否正确（绝对路径需准确）

• 查看浏览器 F12 控制台，确认资源请求地址是否正确（如 JS/CSS 路径是否 404）

4. 端口被占用

• 本地开发：修改 ruoyi-ui/vue.config.js 中的 devServer.port（如改为 8081）

• Nginx/Tomcat：修改配置文件中的 listen 端口（如改为 8081）