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 内置的操作虽然方便，但往往把一些细节藏起来了。
如果你日常使用 Windows，TortoiseGit 也是一个很顺手的工具，它的优势在于目录右键直接操作，很多老程序员习惯这种方式。不过它有个缺点：不直观地展示当前分支和工作区状态，而 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 快捷键Ctrl+Shift+\`` 呼出终端，直接在 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.xml，IDEA 会自动识别为 Maven 项目并开始导入依赖。首次导入可能会下载大量 jar 包，耗时取决于网络。如果你使用的是阿里云 Maven 镜像，速度会快很多。这个可以在 Maven 的settings.xml中配置，找到mirrors节点，加入阿里云镜像地址：
<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://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 Level，RuoYi-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 地址换成git@gitee.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 二次开发中比较核心的菜单权限和代码生成器改造，到时候见。
