1. 前言RuoYi-Vue 二次开发的第一脚从拉代码开始后台管理系统做久了你会发现市面上能直接拿来改的开源项目就那么几个RuoYi-Vue 绝对算得上绕不开的一个。它是基于 Spring Boot Vue 的经典前后端分离脚手架权限、菜单、定时任务、代码生成器全都有拿来就能跑省去从零搭框架的功夫。不过真正到了二次开发阶段第一步不是急着写业务而是先把项目从远端拉到本地、把分支切对这一步搞不好后面全是坑。我最早接手 RuoYi-Vue 的时候光拉代码就遇到过仓库地址不对、分支切不过去、依赖下载卡半天这些琐碎问题。这篇就专门记录 RuoYi-Vue 二次开发系列的第一篇拉取项目并切换分支。目标非常明确——把仓库克隆下来确认分支状态并且能顺利切换到你要开发的分支。内容覆盖 Git 基础操作、IDEA 和命令行两种方式、实操过程中最常见的报错和解决办法后面做二次开发时少在这一步上浪费时间。这里先提醒一句如果你是从 Gitee 或者 GitHub 上直接下载 zip 包再解压那你就跳过了一个关键环节——Git 历史。二次开发过程中你很可能需要回溯某个版本的改动或者对比不同分支之间的差异没有 .git 目录就完全无法做这些操作。所以强烈建议走 Git clone 而非 zip 下载这也是这篇文章的主线。2. 项目整体设计与思路拆解2.1 RuoYi-Vue 的仓库结构长什么样RuoYi-Vue 这个项目其实是一个聚合工程拉下来之后你会发现根目录下有多个子模块比如ruoyi-admin、ruoyi-framework、ruoyi-system、ruoyi-common、ruoyi-quartz、ruoyi-generator还有一个ruoyi-ui前端目录。RuoYi 官方将这些模块分得比较清楚每个模块承载的功能也相对独立二次开发时经常会改到ruoyi-system下的业务逻辑、在ruoyi-ui下写页面。了解仓库结构背后有另一层含义拉取项目后你需要用对应的开发工具对 Maven 多模块进行整体导入而不是单纯把某个目录当成普通文件夹打开。以我个人的实际操作来看推荐用 IDEA 直接打开根目录下的pom.xml让 IDEA 以 Maven 项目的方式加载整个工程这样ruoyi-admin中的启动类才能正确识别依赖。拉项目这个动作本身并不复杂但如果你已经在这个仓库上做过一些修改那么拉取时就要注意分支的选择。RuoYi-Vue 官方在 Gitee 上提供了master主分支同时也有v3.x这样的分支用于维护不同版本。二次开发时大部分人并不会直接在主分支上写代码而是基于某一个版本分支拉出一个属于自己的开发分支。你也要先看仓库的默认分支是哪一个再决定切换到哪儿别一上来就 clone 完然后直接闷头写。2.2 为什么切换分支是二次开发的必经之路可能有的朋友会问我直接把项目下载下来改代码不管分支行不行答案是可以但只适用于一个人单机开发且永远不跟别人协作、不需要版本回溯的情况。但凡团队协作或者你需要在不同的需求任务之间来回切换分支的作用就立刻体现出来了。切分支的本质是让你的工作区在那个时刻与某个分支的代码快照保持一致。比如你在develop分支上开发某个功能写到一半发现线上有个紧急 bug 需要修复你就先暂存当前改动切到master或release分支去改 bug修完切回来继续开发。如果没有分支你只能把半成品代码覆盖到正式代码上极易酿成事故。RuoYi-Vue 二次开发还有一个典型场景不同客户的管理系统可能基于不同版本。客户 A 用的是 3.8.0客户 B 用的是 3.8.7如果你只维护一套代码那升级和定制之间就会反复冲突。所以比较稳妥的做法是给老客户拉一个长期维护分支给新客户基于最新版拉一个新分支两个分支各自演进。这个时候git clone之后的第一次git checkout就显得格外重要。2.3 工具选型解析命令行还是 IDEA 图形界面拉取项目并切换分支核心操作就是 Git。不过操作 Git 的方式大致分成三类原生的命令行、IDEA 内置的 Git 面板以及 TortoiseGit 这类右键菜单工具。我的选择是命令行做 clone 和分支管理IDEA 做日常的代码查看和分支切换。原因很简单命令行会让你对 Git 的执行逻辑更清晰尤其是报错的时候命令行给出的提示信息最完整而 IDEA 内置的操作虽然方便但往往把一些细节藏起来了。如果你日常使用 WindowsTortoiseGit 也是一个很顺手的工具它的优势在于目录右键直接操作很多老程序员习惯这种方式。不过它有个缺点不直观地展示当前分支和工作区状态而 IDEA 右下角的分支名称一看就知道你在哪个分支。对于 RuoYi-Vue 这种多模块项目我通常会先在 IDEA 里用终端工具执行 Git 命令这样既能看到完整日志也免去切换窗口的麻烦。需要说明一下工具只是手段并不存在哪个工具绝对正确。你只要能清楚地回答三个问题——当前在哪个分支、工作区是否干净、远端最新提交是什么——用什么工具其实无所谓。接下来我会把命令行的核心步骤写出来再补充 IDEA 图形界面的对应操作让你能根据自己的习惯选一套。3. 环境准备与核心细节解析3.1 拉取前必须确认的 4 个前置条件在真正执行git clone之前我建议先花一分钟检查环境免得拉下来的项目跑不起来你还要反过头来排查到底是代码问题还是环境问题。JDK 版本RuoYi-Vue 目前的主流版本要求 JDK 1.8 及以上如果你用的是 JDK 11 或 17大部分情况也能跑但某些旧版本依赖可能会有兼容性问题。我自己的环境用的是 JDK 1.8实测最稳。Maven 版本RuoYi-Vue 依赖 Maven 管理建议 Maven 3.6 以上。版本太低可能无法正确解析部分插件。Node.js 版本前端ruoyi-ui是 Vue 2 项目Node.js 版本不宜过高。我用的是 Node 14安装依赖和构建都没问题。如果你用 Node 18 以上个别依赖可能报错需要额外处理。Git 客户端的安装与配置这个看起来是废话但我真的遇到过同事机器上 Git 没配user.name和user.email导致提交代码时报错的情况。clone 不受影响但后续提交一定会卡住。另外要说一下代码托管平台的选择。RuoYi-Vue 的镜像在很多平台都有Gitee 在国内访问最快GitHub 上也有官方仓库。如果你在拉取时觉得速度慢可以优先考虑 Gitee 的镜像地址。有些时候公司的内部 GitLab 也会维护一份 RuoYi-Vue 的镜像这种情况直接拉内网地址速度和安全性最好。3.2 拉取项目命令行完整操作步骤命令行操作没什么神秘的就是把 Git 的几个基础动作串起来。你打开终端进入你希望存放项目的目录然后依次执行下面的命令# 进入工作目录比如 D:/workspace cd D:/workspace # 克隆远程仓库 git clone https://gitee.com/y_project/RuoYi-Vue.git # 进入项目目录 cd RuoYi-Vue # 查看本地分支和远端分支情况 git branch -a # 拉取远端最新的分支信息 git fetch --all # 切换到目标开发分支比如基于 master 创建自己的 dev 分支 git checkout -b dev origin/master说几个容易踩的点。git clone默认会拉取远端所有分支的信息但本地只会在默认分支上建立工作区。假如远端默认分支是master而你想直接基于develop分支开发那你就必须先执行git fetch将最新分支数据同步下来再执行git checkout -b 本地分支名 origin/远端分支名。-b参数的意思是基于远端分支创建一个新的本地分支如果你只是想切换到一个已存在的本地分支去掉-b直接写分支名即可。这里有一个细节很多初学者分不清git checkout dev和git checkout -b dev origin/dev的区别。前者是切换到本地已有的dev分支如果本地没有这个分支命令会直接报错而后者表示基于远端的origin/dev创建并切换到新的本地分支dev。在第一次拉取项目后本地往往只有master所以你想要一个dev分支必须用带-b的形式。RuoYi-Vue 官方仓库的分支命名通常和版本号挂钩比如v3.8.0、v3.8.7。如果公司内部会有定制需求我建议你从某个官方版本分支出发创建custom-xxx分支别直接基于master。这样后续官方更新时你可以把官方版本合并进来不至于因为直接改master而导致大量冲突。3.3 在 IDEA 中图形化切换分支很多新手不习惯命令行那么 IDEA 的图形化操作路径也很清晰。用 IDEA 打开项目根目录或者直接打开pom.xml等待 Maven 加载完成之后看右下角。IDEA 界面的右下角会显示当前分支的名字比如master。点击它会弹出一个窗口里面有所有本地分支和远端分支。如果你要从远端创建一个新分支选origin/master然后选择New Branch from Selected输入新分支名字IDEA 会自动帮你执行checkout -b的动作。如果你只是切换已有分支直接双击目标分支即可。还有一个容易被忽略的地方就是 IDEA 的Git面板。在 IDEA 顶部菜单栏的View - Tool Windows - Git可以打开 Git 日志面板这里面能看到分支图谱直观了解当前 HEAD 指向哪个提交。二次开发过程中这个面板非常有用比如你能看到某个分支是从哪个提交点分出来的也能看到两个分支之间的差异。我个人的习惯是clone 用命令行日常开关分支用 IDEA 快捷键CtrlShift\ 呼出终端直接在 IDEA 的终端里敲命令。这样命令行和 IDE 都能兼顾而且 IDEA 的终端默认已经进入了项目目录省去了手动cd 的麻烦。3.4 切换分支时工作区未提交的改动怎么办这是新人必踩的一个坑。假设你在dev分支上改了一个文件突然想切到master分支Git 可能会阻止你切换提示本地改动会被覆盖。Git 的保护机制是合理的如果两个分支上该文件的内容不同直接切换会导致你的修改丢失或混乱。解决办法有三种把改动提交到当前分支git add .和git commit -m temp但这样会产生一个临时代码提交不太优雅。使用git stash暂存改动git stash将未提交的改动保存到一个栈里工作区瞬间干净可以正常切换分支。之后切回来执行git stash pop恢复改动。用git stash save 改动说明给暂存的内容加备注方便后续识别。我在实际操作中更推荐第二种方式。它的好处是保证了提交历史的整洁又能随时恢复到原来的工作状态。有人会觉得git commit临时提交也无所谓反正后面会丢弃但这个习惯一旦养成很容易把临时提交混进正式分支后面处理起来非常麻烦。4. 实操过程与核心环节实现4.1 首次拉取 RuoYi-Vue 的完整流程实录下面是我最近一次在 Windows 机器上拉取 RuoYi-Vue 的过程把每个步骤、每个输出都记录下来方便你对照操作。首先打开 CMD 或 PowerShell进入目标目录。这个过程里我习惯新建一个专门的代码目录比如D:/ruoyi_dev避免项目散落各处。D: mkdir ruoyi_dev cd ruoyi_dev git clone https://gitee.com/y_project/RuoYi-Vue.git克隆过程快慢取决于网络我在内网环境大概花了 20 多秒。克隆完成后目录下会生成一个RuoYi-Vue文件夹进入它。cd RuoYi-Vue git branch -a输出会显示类似这样的内容* master remotes/origin/master remotes/origin/v3.8.0 remotes/origin/v3.8.7注意当前分支前面的星号表示master但我们实际开发通常不会直接在这个分支上。下面我打算创建一个名为feature/my-business的分支基于远端的v3.8.7分支。之所以基于版本分支是因为v3.8.7相对稳定而master可能包含一些尚未充分测试的变化。git fetch --all --prune git checkout -b feature/my-business origin/v3.8.7如果执行成功终端输出会提示Switched to a new branch feature/my-business。接着用git branch再验证一下确认星号在feature/my-business前面。到这里拉取和分支创建就搞定了接下来你可以在 IDEA 里打开项目正常加载依赖。这里插一个实用小技巧如果git checkout -b时提示fatal: origin/v3.8.7 is not a commit那多半是因为你还没执行git fetch本地不知道远端有v3.8.7这个分支。执行git fetch --all后远端分支信息就会同步到本地问题自然解决。4.2 Maven 依赖加载与前端依赖安装分支切好之后并不是说项目就能直接跑了。RuoYi-Vue 后端是 Maven 多模块项目前端是 npm 项目两者都需要单独处理依赖。后端方面用 IDEA 打开根目录下的pom.xmlIDEA 会自动识别为 Maven 项目并开始导入依赖。首次导入可能会下载大量 jar 包耗时取决于网络。如果你使用的是阿里云 Maven 镜像速度会快很多。这个可以在 Maven 的settings.xml中配置找到mirrors节点加入阿里云镜像地址mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror前端方面打开ruoyi-ui目录在终端里安装 npm 依赖cd ruoyi-ui npm install如果 npm 安装速度慢可以把 npm 源切到淘宝镜像npm config set registry https://registry.npmmirror.com然后再次执行npm install。安装完成后你可以用npm run dev启动前端开发服务器默认端口是 80在 IDEA 里启动 RuoYiApplication 主类就能看到完整的登录页。4.3 分支切换后需要注意的配置文件差异RuoYi-Vue 的配置文件集中在ruoyi-admin/src/main/resources下包括application.yml和application-druid.yml。不同分支之间数据库地址、Redis 地址、端口号可能都不一样。你从v3.8.0切换到v3.8.7时可能会发现application-druid.yml里的数据库连接串变了这是正常的。所以每次切换分支之后我建议立刻检查三处配置数据库连接信息spring.datasource.druid.master.url包括 IP、端口、数据库名。Redis 配置spring.redis.host和spring.redis.port本机开发通常是localhost:6379。启动端口server.port默认 8080。如果你的本地环境和分支默认配置不一致一定要先改配置再启动否则项目能启动但数据的读写会报错。我之前就遇到过一次切到另一个分支后忘了改 Redis 配置登录功能一直转圈排查了好久才发现是连了错误的 Redis 实例。另外切换分支不会自动覆盖本地未跟踪的配置文件。也就是说如果新分支里某个配置文件发生了变更而你上次切换分支时手动改过它Git 通常会尝试合并或直接报冲突。这个时候你得仔细看冲突内容搞清楚哪些是本地定制、哪些是分支默认值。4.4 验证项目是否能正常编译运行分支切换完成后最好做一轮基本验证避免带着坏代码往下走。后端的验证方式很简单在 IDEA 中执行 Maven 生命周期中的clean和install或者直接运行RuoYiApplication的 main 方法。启动成功后控制台会打印出 Spring Boot 的启动日志并出现端口监听的信息。前端验证方式是在ruoyi-ui目录执行npm run dev然后浏览器访问http://localhost:80如果能看到登录页面说明前端环境没问题。当然前端启动前确保后端已经启动否则页面会提示接口请求失败。如果编译报错先别急着赖代码。我一贯的排查顺序是Maven 依赖有没有完全下载看本地仓库.m2/repository/org/springframework这类目录是否正常或者重新执行mvn clean install -U强制更新快照依赖。JDK 编译级别是否匹配检查项目结构和模块的 Language LevelRuoYi-Vue 老版本一般要求 Java 8。数据库是否初始化RuoYi-Vue 的sql目录下有两个脚本ry_2021xxxx.sql和quartz.sql如果没导入启动不会报错但登录时验证码和菜单可能加载不出来。这里多说一句sql脚本在项目根目录下的sql文件夹里需要在你的 MySQL 中新建一个数据库比如ry-vue然后导入这两个脚本。数据库字符集建议使用utf8mb4以避免 emoji 或生僻字存储时报错。5. 常见问题与排查技巧实录5.1 拉取项目时提示“Failed to connect to gitee.com port 443”这个报错十有八九是网络问题。Gitee 本身在国内访问比较稳定但如果你在公司内网需要配置代理才能访问外网就会遇到这类错误。解决方案有两个层次第一检查代理设置。在命令行中设置环境变量git config --global http.proxy http://代理IP:端口 git config --global https.proxy http://代理IP:端口如果你用的是公司代理填上代理地址即可。如果是个人网络用完后记得取消代理git config --global --unset http.proxy git config --global --unset https.proxy第二切换协议。Gitee 支持 https 和 ssh 两种方式有时候 https 不通但 ssh 能通。你在 Gitee 上配置好 SSH 公钥之后把 clone 地址换成gitgitee.com:y_project/RuoYi-Vue.git再试一次。我在实际工作中遇到过几次 https 被防火墙拦的情况ssh 反而畅通。5.2 切换分支报错“error: Your local changes to the following files would be overwritten by merge”这个报错在前面提过本质是工作区有未提交改动而目标分支上的同名文件内容不同。解决方案就是先处理本地改动无非三条路提交、暂存、放弃。具体操作看情况。如果你确定当前改动不需要保留执行git checkout -- 文件名如果你不确定最好不要用这个命令因为改动不可恢复。稳妥做法是git stash git checkout 目标分支 # 处理完分支上的工作后 git checkout 原分支 git stash pop有一次我临时切分支直接用了git checkout --把别人写了两天的代码给覆盖了虽然没有报错但损失惨重。从那之后我宁愿多敲几个stash命令也不轻易丢代码。5.3 切换到远端分支时提示“branch not found”如果执行git checkout feature/xxx报错branch not found基本可以确定是本地没有这个分支并且远端分支信息也没有同步到本地。先执行git fetch --all git branch -rgit branch -r会列出所有远端分支确认有两个可能要么远端根本没有你拼写的分支名要么远端分支存在但你没有拉取。前端拼写错误的情况也不少注意大小写和斜杠符号。对于拉取远端分支精确的做法git checkout -b local-branch origin/remote-branch这样本地分支名可以任意取不一定非得和远端分支名一致。但在团队协作中我建议本地分支名和远端分支名保持一致否则推代码时要写额外的参数容易让同事混乱。5.4 clone 之后代码仓库过大或 clone 中断RuoYi-Vue 因为带完整 Git 历史仓库体积不小。如果网络不稳定git clone可能在中途断开重新执行 clone 又要从头下载。这时可以考虑git clone --depth 1 https://gitee.com/y_project/RuoYi-Vue.git--depth 1表示只拉取最新一次提交不保留完整历史速度会快很多。代价是牺牲了历史版本回溯的功能。如果后期需要历史可以再执行git fetch --unshallow恢复完整历史。这个方法适合依赖包下载超时的应急处理日常协作开发我还是建议完整 clone。5.5 IDEA 中项目加载后包找不到或依赖标红这个问题在 RuoYi-Vue 二次开发中也很常见。你切换到新分支后某个模块的代码标红提示找不到RuoYiConfig或者BaseController等类往往不是代码真的缺了而是 Maven 模块没有正确同步。我的处理方式右键根目录pom.xml选择Maven - Reload project。如果还不行删除本地的ruoyi-common、ruoyi-framework等模块的 target 目录再重新执行mvn clean install -DskipTests。检查 IDEA 的 Maven 设置确保Maven home path、User settings file、Local repository都指向正确路径。还有一种可能是你切换分支后别的同事往某个模块里新增了依赖而你的 Maven 没有重新加载。所以每次切换分支后我都建议做一次 Maven Reload而不是等到标红再去处理。6. 关于切换分支与二次开发的几个额外建议这个系列是二次开发所以除了基本操作之外我还想多说几个跟团队协作相关的点。第一分支命名尽量语义化。比如feature/xxx表示功能开发fix/xxx表示 bug 修复release/xxx表示发布版本。RuoYi-Vue 官方仓库的分支命名虽然不完全遵循这套规则但你个人维护的分支最好规范。不然过两个月回来看分支列表满屏的test1、new、1自己都不知道哪个是哪个。第二完事后记得建标签。RuoYi-Vue 二次开发往往对应特定客户或特定版本每完成一个能交付的稳定版本就打个 tag比如v1.0.0-custom。这样以后客户反馈问题你直接git checkout v1.0.0-custom就能回到当时的代码状态不用靠记忆找分支。第三如果你在多个功能分支之间切换非常频繁建议用好git stash list和git stash apply stash{0}查看临时保存的代码。我有一次git stash之后忘了几天后想恢复却不知道哪份才是最新的后来养成了给 stash 加注释的习惯。第四也是我最深的体会二次开发过程中不要轻易去动ruoyi-framework底层的代码。很多初学者为了省事直接在框架代码里改需求逻辑短期看是快但后面的升级基本没法做。正确的做法是尽可能在ruoyi-system或者新增模块里实现业务把框架层的改动压缩到最小。这样你切换分支、合并代码时冲突也会少很多。最后再分享一个小技巧算是这个系列的开胃菜。每当你拉取一个全新的 RuoYi-Vue 分支别急着敲业务代码先花十分钟做三件事编译后端、启动前端、登录一次系统。这三个动作全部通过再开始写代码。我见过太多人在没验证基础环境的情况下猛写代码最后发现是数据库配置错了浪费整整一天。拉取项目和切换分支听起来简单实际却是 Git 协作的根基。这一步走稳了后面无论是合并代码、解决冲突还是进行多分支迭代都会顺畅很多。下一篇文章我会接着聊 RuoYi-Vue 二次开发中比较核心的菜单权限和代码生成器改造到时候见。