1. 项目概述：为什么若依（RuoYi）值得你花时间配置？

如果你是一名Java开发者，或者正在负责一个中小型管理后台的快速搭建，那么“若依（RuoYi）”这个名字你大概率不会陌生。它不是一个新潮的玩具，而是一个在开源社区里经过多年实战检验、拥有庞大用户基数的后台管理系统解决方案。简单来说，若依帮你把用户管理、角色权限、菜单配置、日志监控这些后台系统的“基础设施”都预制好了，你只需要专注于自己的核心业务逻辑开发。这听起来很美好，对吧？但很多新手开发者拿到若依源码后，面对那一堆配置文件、数据库脚本和前后端分离的架构，常常会卡在第一步——环境配置上。我见过不少团队，因为初始配置没搞明白，导致后续开发、部署问题不断，白白浪费了大量时间。

所以，这篇教程的目的非常直接：带你从零开始，手把手、无死角地完成一个标准若依前后端分离版（RuoYi-Vue）的本地开发环境配置。我不会只给你一串命令，而是会解释清楚每一步在做什么、为什么要这么做，以及如果出错了该怎么排查。这不仅仅是“安装教程”，更是一份“避坑指南”。无论你是刚接触若依的新手，还是想系统梳理配置流程的老手，这篇文章都能让你对若依的骨架有一个清晰的认识，为后续的深度定制和业务开发打下坚实的基础。

2. 环境准备：搭建稳固的开发地基

配置若依的第一步，不是急着去下载代码，而是确保你的本地开发环境“五脏俱全”。一个稳定、版本匹配的环境，能避免90%的诡异问题。若依（这里以最流行的前后端分离版RuoYi-Vue为例）是一个典型的Spring Boot + Vue.js项目，因此我们需要准备后端和前端两套环境。

2.1 后端环境：Java与数据库的基石

后端是若依的核心，它依赖于Java运行环境、项目管理工具和数据库。

1. JDK 安装与配置若依官方推荐使用 JDK 1.8 或更高版本。我强烈建议你使用 JDK 8 或 JDK 11（LTS长期支持版），它们在稳定性和社区支持上最好。

• 安装：从Oracle官网或AdoptOpenJDK等开源站点下载对应你操作系统的安装包。安装过程很简单，一路“下一步”即可。关键在配置。
• 配置环境变量：这是新手最容易出错的地方。
  • JAVA_HOME：这个变量指向你的JDK安装目录（例如C:\Program Files\Java\jdk1.8.0_301）。很多工具（如Maven、IDEA）都依赖这个变量来找到Java。
  • Path：在Path变量中新增一项%JAVA_HOME%\bin。这让你能在命令行任何位置直接使用java、javac等命令。
• 验证：打开命令行（CMD或PowerShell），输入java -version和javac -version。如果正确显示版本号，说明配置成功。

注意：如果你的电脑上安装了多个JDK版本，JAVA_HOME变量的值决定了当前生效的是哪个。可以通过命令行echo %JAVA_HOME%（Windows）或echo $JAVA_HOME（Mac/Linux）来检查。

2. Maven 安装与配置Maven是Java项目的依赖管理和构建工具。若依通过pom.xml文件管理所有第三方库（Jar包）。

• 安装：从Apache Maven官网下载二进制压缩包，解压到任意目录（例如D:\apache-maven-3.8.6）。
• 配置环境变量：
  • MAVEN_HOME：指向你的Maven解压目录。
  • Path：新增%MAVEN_HOME%\bin。
• 配置本地仓库和镜像（关键优化步骤）：Maven默认从中央仓库下载依赖，在国内速度可能很慢。我们需要修改Maven安装目录下conf/settings.xml文件。
  • 本地仓库路径：找到<localRepository>标签，可以设置一个自定义路径，如<localRepository>D:\maven-repository</localRepository>，避免所有依赖都堆在C盘。
  • 镜像源：在<mirrors>标签内添加阿里云镜像，大幅提升下载速度。

    <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

• 验证：命令行输入mvn -v，显示版本信息即成功。

3. MySQL 安装与初始化若依使用MySQL作为默认数据库。你需要安装MySQL（5.7或8.0版本均可）并创建一个空的数据库。

• 安装：可以从MySQL官网下载社区版安装包。安装过程中会提示你设置root用户的密码，务必牢记。
• 创建数据库：安装完成后，使用命令行或MySQL客户端（如Navicat、MySQL Workbench）连接数据库，然后执行以下SQL语句：

  CREATE DATABASE IF NOT EXISTS `ry-vue` DEFAULT CHARACTER SET utf8mb4 DEFAULT COLLATE utf8mb4_general_ci;

  这里创建了一个名为ry-vue的数据库，并设置了utf8mb4字符集，以支持存储Emoji等四字节字符。
• 注意：记住你设置的数据库连接信息：主机（通常是localhost）、端口（默认3306）、数据库名（ry-vue）、用户名（如root）和密码。稍后我们需要在若依的配置文件中填写这些信息。

2.2 前端环境：Node.js与包管理器

前端部分基于Vue.js，需要Node.js运行环境。

1. Node.js 安装

• 下载：从Node.js官网下载LTS（长期支持）版本安装包。安装过程同样简单。
• 验证：安装完成后，命令行输入node -v和npm -v，应分别显示Node.js和npm（Node包管理器）的版本号。
• 关于版本：若依-Vue对Node.js版本有一定要求，太老的版本可能无法构建。使用官网推荐的LTS版本是最稳妥的选择。

2. 配置npm镜像源npm默认源在国外，下载速度慢且容易失败。我们需要将其替换为国内镜像。

• 命令行配置：在命令行中执行以下命令，将npm registry设置为淘宝镜像。

  npm config set registry https://registry.npmmirror.com/

• 验证：执行npm config get registry，检查是否已切换成功。
• 可选：使用yarn或pnpm：如果你觉得npm速度仍不理想，可以安装yarn或pnpm作为替代的包管理器，它们通常有更好的性能和缓存机制。安装后，同样需要配置国内镜像源。

3. 安装Vue CLI（可选但推荐）Vue CLI是一个官方脚手架工具，虽然若依前端已经是一个完整的项目，不需要用它来初始化，但安装它有助于你理解Vue的生态，并且其内置的vue-ui图形化界面在管理项目依赖时非常方便。

• 安装：在命令行中执行npm install -g @vue/cli。
• 验证：执行vue --version。

至此，你的开发环境已经准备就绪。这就像盖房子前打好了地基、备齐了砖瓦水泥。接下来，我们就要开始“施工”了。

3. 项目获取与基础配置

有了环境，下一步就是把若依的“蓝图”拿到手，并根据我们的本地环境进行初步调整。

3.1 获取项目源码

官方源码托管在Gitee和GitHub上。对于国内用户，从Gitee克隆速度更快。

• 克隆项目：打开命令行，切换到你希望存放项目的目录（如D:\projects），执行克隆命令：

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

  这条命令会将整个RuoYi-Vue项目下载到当前目录下的RuoYi-Vue文件夹中。
• 关于分支：默认克隆的是master分支，这是稳定版。如果你需要微服务版（RuoYi-Cloud），需要克隆对应的仓库。本篇我们聚焦于单体应用版RuoYi-Vue。

3.2 后端配置详解：连接数据库与调整参数

后端配置的核心是application.yml文件，它位于ruoyi-admin模块的src/main/resources目录下。这个文件决定了Spring Boot应用的行为。

1. 数据库连接配置找到spring.datasource配置节，修改为你本地MySQL的信息。

spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8 username: root password: 你的数据库密码

• driver-class-name：MySQL 8.0+ 驱动是com.mysql.cj.jdbc.Driver；如果是5.x版本，可能是com.mysql.jdbc.Driver。若依默认配置通常已适配。
• url：localhost:3306是数据库地址和端口；ry-vue是数据库名；后面的参数是连接选项，如编码、时区处理、SSL等。特别注意时区：serverTimezone=GMT%2B8表示东八区（北京时间），这对于避免时间字段存储错误至关重要。
• username/password：填写你安装MySQL时设置的用户名和密码。

2. Redis配置（可选但推荐）若依使用Redis来管理会话（Session）、缓存数据（如验证码、字典数据）。如果你不配置Redis，Spring Boot会使用内存存储Session，这在单机开发时没问题，但重启应用会导致登录状态丢失。配置Redis能获得更好的体验。

• 安装Redis：从Redis官网下载Windows版本或使用Docker快速启动一个Redis实例。Linux/Mac下安装也很方便。
• 修改配置：在application.yml中找到Redis配置部分。

  redis: host: localhost port: 6379 password: # 如果你设置了Redis密码就填，默认空 database: 0 # 使用的数据库编号

  确保这里的host和port与你运行的Redis服务一致。

3. 其他关键配置

• 服务器端口：server.port默认为8080。如果8080端口被占用，可以修改为其他端口，如8081。
• 日志级别：开发阶段可以将相关包的日志级别调整为DEBUG，方便排查问题，但上线前记得改回INFO或WARN。

3.3 前端配置解析：对接后端API

前端配置的核心是设置API请求的基地址，告诉Vue应用去哪里找后端服务。

进入RuoYi-Vue项目根目录下的ruoyi-ui文件夹，这是前端项目所在。

• 找到配置文件：配置文件通常位于ruoyi-ui/.env.development（开发环境）和ruoyi-ui/.env.production（生产环境）。我们修改开发环境的即可。
• 修改API地址：打开.env.development文件，你会看到类似下面的内容：

  # 开发环境配置 ENV = 'development' # 开发环境，API请求地址 VUE_APP_BASE_API = '/dev-api'

  这里的VUE_APP_BASE_API是一个会在Vue代码中全局访问的变量。它的值/dev-api是一个代理路径。
• 理解代理：在开发时，前端运行在独立的服务器（如localhost:80），后端运行在另一个端口（如localhost:8080）。由于浏览器同源策略的限制，直接跨端口请求API会有问题。因此，Vue CLI（或Webpack）提供了代理功能：所有以前缀/dev-api开头的请求，都会被转发到我们指定的后端地址。
• 配置代理：代理规则在ruoyi-ui/vue.config.js文件中定义。找到devServer.proxy配置：

  devServer: { host: '0.0.0.0', port: port, open: true, proxy: { [process.env.VUE_APP_BASE_API]: { target: `http://localhost:8080`, // 这里指向你的后端服务地址和端口 changeOrigin: true, pathRewrite: { ['^' + process.env.VUE_APP_BASE_API]: '' } } } }

  • target: 这是最重要的配置，必须确保它指向你后端Spring Boot应用启动的地址和端口（默认http://localhost:8080）。如果后端端口改了，这里也要同步修改。
  • pathRewrite: 这个配置会把请求路径中的/dev-api前缀重写为空字符串，这样转发到后端的请求就是干净的路径（例如，前端请求/dev-api/login，实际后端收到的是/login）。

实操心得：前后端联调时，90%的“404”或“连接失败”问题，都是因为这个代理配置的target地址不对，或者后端服务根本没启动。养成习惯，启动项目前先双击检查这两个配置文件的端口和地址是否匹配。

4. 数据库初始化与项目启动

配置完成后，我们需要用若依的“设计图”（SQL脚本）来构建数据库表，然后让整个项目运行起来。

4.1 执行SQL脚本，创建表结构

在克隆下来的项目根目录RuoYi-Vue下，找到sql文件夹。里面通常会有多个SQL文件。

• 主要脚本：
  • quartz.sql: 定时任务相关表（如果不用定时任务功能，可不执行）。
  • ry_202xxxxx.sql: 这是核心脚本，文件名带日期，包含了系统运行必需的所有表结构（用户、角色、菜单、部门等）以及初始数据（默认管理员账号admin/123456）。
• 执行方法：
  1. 使用客户端工具：打开Navicat或MySQL Workbench，连接到你的ry-vue数据库，然后直接打开这个SQL文件并执行。这是最直观的方式。
  2. 命令行执行：在MySQL安装目录的bin文件夹下打开命令行，或使用已配置环境变量的命令行：

     mysql -u root -p ry-vue < D:\projects\RuoYi-Vue\sql\ry_202xxxxx.sql

     输入密码后执行。
• 验证：执行成功后，在数据库客户端中刷新，应该能看到多出了几十张以sys_,gen_,qrtz_等为前缀的表。

4.2 后端启动与验证

后端是一个标准的Spring Boot项目，有多种启动方式。

• 使用IDE启动（推荐）：用IntelliJ IDEA或Eclipse打开整个RuoYi-Vue项目。IDE会自动识别为Maven项目。找到主启动类：RuoYiApplication（通常位于ruoyi-admin/src/main/java/com/ruoyi包下）。直接右键点击这个类，选择Run ‘RuoYiApplication‘。IDE会自动编译并启动应用。
• 命令行启动：在项目根目录下打开命令行，执行Maven命令：

  mvn clean package -Dmaven.test.skip=true # 跳过测试，打包项目 cd ruoyi-admin/target # 进入打包输出目录 java -jar ruoyi-admin.jar # 运行生成的jar包

• 启动验证：看到控制台输出包含“Started RuoYiApplication in X.XXX seconds”的字样，并且没有大量ERROR日志，说明启动成功。此时，你可以在浏览器访问http://localhost:8080（如果你改了端口，则访问对应的端口）。正常情况下，你会看到一个简单的提示页，或者直接跳转到/login页面（如果前端尚未启动，可能显示Whitelabel Error Page，这是正常的，说明后端服务在运行）。

4.3 前端启动与登录

前端需要独立启动一个开发服务器。

• 安装依赖：在命令行中，进入前端目录ruoyi-ui，执行：

  npm install

  这个过程会根据package.json文件下载所有依赖包到node_modules文件夹。网络状况好的话几分钟就能完成，如果卡住，请检查npm镜像源是否配置正确。
• 启动开发服务器：依赖安装完成后，执行：

  npm run dev

  这个命令会启动Vue的开发服务器，并自动打开浏览器。如果没自动打开，命令行会输出访问地址，通常是http://localhost:80。
• 登录系统：浏览器打开前端地址后，你会看到若依的登录界面。使用SQL脚本中初始化的默认账号：用户名：admin，密码：123456，进行登录。
• 验证前后端联通：登录成功后，你应该能看到完整的管理后台界面，左侧有菜单栏。点击任意菜单（如“系统监控”->“在线用户”），如果能够正常加载数据，说明前后端通信完全正常，整个若依系统已经成功在你的本地跑起来了！

5. 核心配置项深度解析与定制

系统跑起来只是第一步。若依的强大之处在于其高度的可配置性。理解这些配置，你才能随心所欲地定制它。

5.1 应用配置（application.yml）进阶

除了基础的数据库和Redis，application.yml里还有很多宝藏配置。

1. 文件上传路径配置若依内置了文件上传功能。默认配置可能将文件上传到系统临时目录，重启后丢失。你需要将其改为一个固定路径。

# 文件上传配置 file: path: /home/ruoyi/uploadPath # Linux示例 # path: D:/ruoyi/uploadPath # Windows示例

同时，你需要确保这个路径在服务器上真实存在，并且应用有读写权限。这个路径也用于存储用户头像、导入导出的Excel文件等。

2. 日志配置若依使用Logback记录日志。默认配置可能将日志输出到控制台和文件。你可以调整日志级别、文件滚动策略和存储路径。

logging: level: com.ruoyi: debug # 将若依自身包的日志级别调高，方便调试 file: name: logs/ruoyi-admin.log # 日志文件路径 logback: rollingpolicy: max-file-size: 10MB # 单个日志文件最大大小 max-history: 30 # 保留的日志文件天数

合理的日志配置是线上问题排查的生命线。

3. 跨域配置（CORS）在前后端分离部署时（即前端和后端不在同一个域名/端口下），浏览器会因同源策略阻止请求。虽然开发时我们用了代理，但生产环境需要后端配置CORS。 在application.yml中，若依通常通过ruoyi.cors或自定义配置项来管理。确保生产环境下，allowed-origins配置正确指向你的前端域名。

ruoyi: cors: allowed-origins: “http://your-frontend-domain.com“ # 生产环境前端地址

5.2 前端工程配置（vue.config.js）定制

vue.config.js是Vue CLI项目的核心配置文件，若依前端基于此做了大量定制。

1. 打包输出配置

• publicPath：这个配置决定了打包后，静态资源（JS、CSS、图片）的引用路径。如果你打算将前端部署在非根路径下（例如http://yourdomain.com/admin/），就需要修改它。

  module.exports = { publicPath: process.env.NODE_ENV === 'production' ? '/admin/' : '/', // 生产环境部署在/admin子路径下 // ... 其他配置 }

• 输出目录：outputDir可以指定打包生成的文件存放的目录，默认是dist。

2. 开发服务器配置除了代理，你还可以配置：

• host:‘0.0.0.0‘允许通过本地IP访问（方便手机等设备测试）。
• port: 开发服务器的端口，默认80，如果被占用可以修改。
• open: 设为true会在启动时自动打开浏览器。

3. 插件与链式配置若依集成了很多插件，比如svg-sprite-loader（用于图标）、compression-webpack-plugin（Gzip压缩）。在vue.config.js中可以看到对这些插件的配置。除非有特殊需求，一般不需要修改，但了解它们的存在有助于你未来进行性能优化或功能扩展。

5.3 权限与安全配置初探

若依的权限控制是其核心功能之一，主要基于Spring Security或Shiro（取决于版本）和自研的权限注解。

1. 权限注解在后端Controller的方法上，你会看到如@PreAuthorize(“@ss.hasPermi(‘system:user:list’)”)这样的注解。这表示调用此接口需要拥有system:user:list这个权限标识符。这个标识符与数据库sys_menu表中的perms字段对应。你可以在系统管理的“菜单管理”中，为菜单配置对应的权限标识符。

2. 安全框架配置配置类通常位于com.ruoyi.framework.config包下，如SecurityConfig。在这里，你可以：

• 配置哪些路径可以匿名访问（如登录接口、验证码接口）。
• 配置密码加密方式。
• 配置会话管理策略（结合Redis实现分布式会话）。
• 自定义登录成功/失败的处理逻辑。

3. 数据权限这是若依的高级特性。通过@DataScope注解，可以实现基于用户部门的数据行级过滤。例如，部门经理只能看到本部门的数据。这部分的配置相对复杂，涉及到自定义注解、AOP切面和SQL解析，在初期可以暂不深入，但需要知道它的存在和基本原理。

6. 部署上线配置要点

本地开发完成后，最终需要将项目部署到服务器。部署配置与开发配置有显著区别。

6.1 后端部署配置

1. 打包为可执行JAR使用Maven命令进行打包，并跳过测试以加快速度：

mvn clean package -Dmaven.test.skip=true -P prod

这里的-P prod表示激活prod这个Maven profile。在pom.xml或application-prod.yml中，你可以为生产环境定义特定的配置，比如连接生产数据库、关闭调试信息等。

2. 调整生产环境配置文件在src/main/resources下创建或修改application-prod.yml。这个文件的配置会覆盖application.yml中的默认值。

• 数据库：将连接信息改为生产服务器的数据库地址、用户名和密码。
• Redis：同样改为生产环境的Redis地址。
• 日志：调整日志输出路径为服务器上的固定目录，如/app/logs。
• 关闭Swagger：生产环境一定要关闭API文档工具Swagger，避免暴露接口信息。

  springfox: documentation: enabled: false

3. 启动脚本在服务器上，推荐使用脚本或系统服务（如systemd）来管理Spring Boot应用，实现优雅启停和日志管理。一个简单的启动脚本start.sh可能如下：

#!/bin/bash APP_NAME=ruoyi-admin.jar # 使用生产环境配置文件启动 nohup java -Xms512m -Xmx1024m -jar $APP_NAME --spring.profiles.active=prod > app.log 2>&1 & echo $! > pid.txt

这个脚本设置了JVM堆内存参数，指定了使用prod配置文件，并将日志输出到app.log文件。

6.2 前端部署配置

1. 构建生产版本在前端目录ruoyi-ui下，执行构建命令：

npm run build:prod

这个命令会使用生产环境配置（.env.production）进行构建，并对代码进行压缩、优化，生成的文件位于dist目录。

2. 配置生产环境API地址修改.env.production文件：

# 生产环境配置 ENV = 'production' # 生产环境，API请求地址 VUE_APP_BASE_API = '/prod-api'

这里的/prod-api是一个约定，你需要在前端部署的Web服务器（如Nginx）上配置反向代理，将所有/prod-api的请求转发到后端服务。

3. Web服务器配置（以Nginx为例）将dist目录下的所有文件上传到服务器，例如/usr/share/nginx/html。 然后配置Nginx，主要做两件事：1. 托管前端静态文件；2. 代理API请求到后端。

server { listen 80; server_name yourdomain.com; # 你的域名 # 前端静态资源 location / { root /usr/share/nginx/html; index index.html index.htm; try_files $uri $uri/ /index.html; # 支持Vue Router的history模式 } # 代理后端API请求 location /prod-api/ { proxy_pass http://localhost:8080/; # 后端服务地址 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 可以再配置一个用于直接访问后端（例如管理后台直接访问后端端口） # location /admin/ { # proxy_pass http://localhost:8080/; # ... 其他proxy设置 # } }

配置完成后，重启Nginx。现在访问你的域名，就应该能看到部署好的若依系统了。

7. 常见问题与排查技巧实录

即使按照教程一步步来，也难免会遇到问题。这里我整理了一些最常见的“坑”和解决方法。

7.1 后端启动失败类问题

问题1：端口被占用

• 现象：启动时报Web server failed to start. Port XXXX was already in use.
• 解决：
  1. 修改application.yml中的server.port为其他端口。
  2. 或者找到占用端口的进程并结束它。在命令行中：
     • Windows:netstat -ano | findstr :8080找到PID，然后taskkill /PID [PID] /F
     • Linux/Mac:lsof -i:8080找到PID，然后kill -9 [PID]

问题2：数据库连接失败

• 现象：启动时报Communications link failure或Access denied for user。
• 排查步骤：
  1. 检查配置：核对application.yml中的url,username,password是否百分百正确，注意密码是否有特殊字符需要转义。
  2. 检查MySQL服务：确保MySQL服务正在运行。
  3. 检查网络与权限：尝试用命令行或客户端工具，使用配置文件中的信息手动连接数据库，看是否能成功。如果失败，可能是用户权限问题（需要授权远程或本地连接），或者防火墙阻止了3306端口。

问题3：Redis连接失败

• 现象：启动时警告或报错连接Redis失败，但应用仍能启动。登录时验证码不显示或登录状态无法保持。
• 解决：
  1. 确认Redis服务已启动。
  2. 检查application.yml中的Redishost和port。
  3. 如果Redis设置了密码，确保配置文件中password项已填写。
  4. 如果是Linux服务器，检查防火墙是否开放了6379端口。

7.2 前端启动与编译问题

问题1：npm install 失败或极慢

• 现象：卡在node-sass等包，或直接报网络错误。
• 解决：
  1. 换源：再次确认已执行npm config set registry https://registry.npmmirror.com/。
  2. 清理缓存：执行npm cache clean --force，然后重试。
  3. 使用cnpm：如果npm问题依旧，可以安装淘宝的cnpm：npm install -g cnpm --registry=https://registry.npmmirror.com，然后用cnpm install代替npm install。

问题2：npm run dev 启动后，页面空白或报错

• 现象：浏览器控制台报Failed to load resource: net::ERR_CONNECTION_REFUSED或类似的网络错误。
• 排查：
  1. 检查后端是否启动：首先确认你的后端Spring Boot应用已经成功启动在localhost:8080（或你配置的端口）。
  2. 检查代理配置：核对vue.config.js中devServer.proxy的target地址，必须和后端服务地址完全一致。
  3. 检查前端服务端口：如果80端口被占用，npm run dev可能会启动在其他端口（如8081）。注意看命令行启动成功的输出信息，访问正确的地址。

问题3：打包（npm run build:prod）时报内存溢出

• 现象：报JavaScript heap out of memory。
• 解决：Node.js默认内存限制可能不够。可以通过设置环境变量临时增加内存：

  # Linux/Mac export NODE_OPTIONS=--max-old-space-size=4096 npm run build:prod # Windows (PowerShell) $env:NODE_OPTIONS="--max-old-space-size=4096" npm run build:prod

  这里的4096表示分配4GB内存，可以根据你的机器配置调整。

7.3 系统运行类问题

问题1：登录成功，但菜单加载不出来或页面空白

• 现象：登录后左侧菜单栏为空，或点击菜单没反应。
• 排查：
  1. F12看网络请求：打开浏览器开发者工具，切换到Network（网络）标签页，查看点击菜单时是否有API请求发出，请求的URL和响应状态码是什么。如果请求404，大概率是前后端路径没对上。
  2. 检查用户权限：用默认的admin/123456登录。如果用了自己创建的用户，确认该用户是否被分配了角色，以及角色是否关联了菜单权限。
  3. 检查前端路由：如果是部署后出现此问题，检查Nginx配置中try_files $uri $uri/ /index.html;这一行是否存在，这是支持Vue Router history模式的关键。

问题2：验证码不显示

• 现象：登录页面验证码区域显示一个裂图图标。
• 解决：
  1. 首选检查Redis：验证码是存储在Redis中的。确保Redis配置正确且服务可用。
  2. 检查Kaptcha配置：若依使用Kaptcha生成验证码。检查application.yml中关于Kaptcha的配置（如长、宽、字符数）是否异常。
  3. 查看浏览器控制台：看验证码图片的请求是否成功，如果请求地址错误或返回500，根据错误信息进一步排查。

问题3：文件上传失败

• 现象：上传头像或导入Excel时失败。
• 排查：
  1. 检查上传路径：确认file.path配置的目录在服务器上存在，并且运行Java应用的用户（如www-data,tomcat用户或你自己）对该目录有读写权限。
  2. 检查文件大小限制：Spring Boot默认对上传文件大小有限制（通常1MB）。如果上传大文件，需要在application.yml中调整：

     spring: servlet: multipart: max-file-size: 10MB max-request-size: 100MB

配置若依就像组装一台精密的仪器，每一步的严丝合缝决定了最终运行的顺畅度。这份教程涵盖了从环境准备到部署上线的完整链路，并重点解释了配置背后的逻辑和常见问题的根因。我的建议是，第一次配置时，严格遵循步骤，确保基础环境（JDK, Maven, MySQL, Node.js）版本匹配且安装正确。遇到问题时，不要慌张，多查看控制台日志和浏览器开发者工具的控制台（Console）与网络（Network）标签，那里藏着绝大部分问题的答案。当你成功在本地跑起若依，并完成一次简单的定制（比如修改登录页Logo，或增加一个测试菜单）后，你对这套框架的理解就会深刻得多。剩下的，就是深入其业务代码，去实现你真正的业务逻辑了。