1. 写在前面为什么把拉项目、切分支单独写一篇如果评选程序员最常踩的坑环境准备绝对排前三。你以为的二次开发是从改代码开始的实际上大多数人的二次开发死在第一步——项目拉不下来、分支选错了、跑起来一堆报错最后发现是版本不对。RuoYi-Vue是目前国内使用面很广的一套后台管理脚手架基于Spring Boot Vue代码生成、权限管理、定时任务这些基础能力都封装好了。做二次开发的人通常分两类一类是公司内部系统需要快速落地另一类是接私活想省时间。无论哪种拿到这套代码之后的第一件事绝对不是写功能而是把项目干净、正确地拉到本地并锁定一个合适的分支作为开发基线。这篇是RuoYi-Vue二次开发系列的第一篇只讲一件事怎么把项目从Gitee上拉下来以及为什么切换分支这件事值得单独拿出来说。内容基于我过往多次搭建这套环境的实际操作经验尽量把每一步的为什么也讲清楚。2. 拉取前的关键决策你要的是哪个版本的RuoYi-Vue2.1 先搞清楚RuoYi的几个兄弟项目很多人搜RuoYi会出来一堆仓库RuoYi、RuoYi-Vue、RuoYi-Cloud、RuoYi-App还有RuoYi-Vue-Plus这类第三方分支。初次接触特别容易懵。简单梳理一下RuoYi单体版基于Thymeleaf服务端渲染前后端不分离适合小型项目。RuoYi-Vue前后端分离前端Vue 后端Spring Boot是目前最主流的选择。RuoYi-Cloud微服务版本引入了Nacos、Gateway等组件适合中大型项目。RuoYi-App移动端版本基于uni-app。RuoYi-Vue-Plus社区维护的增强版集成了更多工具但不是官方仓库。如果你不是明确要做微服务架构我的建议是直接选RuoYi-Vue。它是在官方仓库中活跃度最高、问题解决方案最多、社区资料最全的一个版本。二次开发最怕的不是功能不够而是踩了坑搜不到解决方案选RuoYi-Vue能让你在遇到问题时多出好几倍的搜索命中率。2.2 官方仓库地址与分支结构RuoYi-Vue的官方Gitee仓库地址是https://gitee.com/y_project/RuoYi-Vue。注意如果你在GitHub上搜也能搜到RuoYi-Vue的镜像仓库但Gitee这边是主仓库更新最及时优先从Gitee拉。仓库默认分支是master但实际项目里master不一定是你该用的分支。RuoYi-Vue的官方仓库会维护多个分支常见的有master当前开发版和以版本号命名的分支如v3.8.7这类以及一些标识为不再维护的旧分支。这里有个很关键的认知分支的命名背后是版本策略。master分支上的代码是持续更新的今天拉的和下个月拉的可能就不一样。如果你要基于一套稳定的代码做二次开发并希望后续能跟着官方升级打补丁那么选择一个固定的版本分支会更稳妥。我之前接过一个项目客户要求在这套框架上做三年以上的长期维护。当时我直接选了当时最新的版本号分支作为基线而不是master原因很简单master上随时可能引入新功能或调整接口一旦跟着更新自己改过的业务代码就可能冲突。锁死版本分支等于锁死了一个可预期的边界。3. 实操环境准备与拉取动作拆解3.1 你需要提前装好的工具在真正执行git clone之前先把环境检查一遍。清单不复杂但每一件都别漏Git客户端Windows建议用Git for Windows装完自带Git Bash。TortoiseGit可选但Windows下操作小乌龟确实直观尤其是右键菜单式操作对新手友好。JDKRuoYi-Vue基于JDK 8开发虽然新版能兼容更高版本但建议用JDK 8如1.8.0_202避免后续编译遇到莫名问题。Maven版本3.6以上即可需要配置国内镜像仓库否则首次拉依赖会非常痛苦。Node.js前端基于Vue 2建议使用Node 14或16版本不要直接上最新的Node 20Vue 2项目的依赖兼容性会出问题。IDE后端用IntelliJ IDEA前端用VSCode或IDEA都行我这里以后端为主的流程来演示。3.2 Gitee与Git的关联配置拉取项目之前需要先配置好SSH密钥否则每次Push/Pull都要输账号密码而且部分操作会受限于HTTPS方式。虽然标题里写的是拉取项目但日常开发中你不可能只拉一次后续迭代提交、拉取更新都会用到所以一次性配置好SSH很有必要。在Git Bash中执行以下步骤# 第一步检查是否已有SSH密钥 ls -al ~/.ssh # 第二步如果没有生成新的密钥邮箱换成你自己的 ssh-keygen -t rsa -b 4096 -C your_emailexample.com # 第三步查看公钥内容 cat ~/.ssh/id_rsa.pub复制公钥内容打开Gitee网站进入设置 - SSH公钥粘贴保存。然后验证一下ssh -T gitgitee.com看到Hi xxx! Youve successfully authenticated就说明配置成功。如果你用TortoiseGit还可以在右键菜单里找到Settings - Network - SSH Client确认指向的SSH工具路径正确。这个细节容易被忽略特别是装了多个Git客户端的情况下TortoiseGit可能找不到正确的SSH客户端导致连接失败。3.3 拉取项目的两种方式与选择建议方式一直接用Git Bash。# 推荐用SSH方式避免了HTTPS的密码问题 git clone gitgitee.com:y_project/RuoYi-Vue.git方式二用TortoiseGit。在本地目录右键 - SVN Checkout这里不是SVN是TortoiseGit的右键菜单翻译问题实际是Git Clone - 填写仓库URL和目录 - 确认。如果你第一次接触我用个生活化的类比说明这两种方式的区别Git Bash是命令行工具就像用手机手工输号码打电话TortoiseGit是图形化界面就像通讯录里点名字直接拨号。前者灵活但需要记忆命令后者直观但功能入口有时候藏得深。我自己的习惯是命令行为主TortoiseGit作为辅助查看状态和对比差异因为命令行在脚本化和批量操作上有不可替代的优势。拉取完成后你会看到RuoYi-Vue目录下有ruoyi-admin、ruoyi-framework、ruoyi-system、ruoyi-ui、ruoyi-generator、ruoyi-common等模块还有个sql目录是数据库脚本这个后续初始化数据库会用到先记住它的位置。4. 分支切换这不是一个动作而是一套规范4.1 为什么拉完代码第一件事是切分支我见过不少人拉完项目直接就在默认分支上开始改代码。短期的确省事但问题很快就来了你改了一半官方推送了新代码你git pull之后发现自己改的文件和官方的更新冲突了解决冲突花掉的时间和精力远超最开始切分支那两分钟。正确的做法是拉取完成后立即切换到你要作为开发基线的分支然后在该分支上拉一条自己的开发分支或者如果只是个人维护就基于该分支直接开发。用一句通俗的话说你租房子住不能直接改造房东的房子得先签好租约明确自己住在哪套房里再考虑怎么装修。分支就是这层租约边界它保证你的改动和官方维护的版本互不污染。4.2 查看分支与切换分支的具体操作先用命令看当前仓库有哪些分支# 查看本地分支 git branch # 查看远程分支 git branch -r # 查看全部分支含远程跟踪信息 git branch -a刚拉下来的项目本地默认会在master分支上远程分支信息已经同步。此时你可以查看远端有哪些版本分支git branch -a官方仓库通常输出类似这样* master remotes/origin/HEAD - origin/master remotes/origin/master remotes/origin/v3.8.7 remotes/origin/v3.8.8切换分支的命令特别简单git checkout -b v3.8.8 origin/v3.8.8这里拆开解释下这个命令的含义git checkout -b表示创建并切换到一个新分支v3.8.8是这个新分支的本地名称origin/v3.8.8是指定这个本地分支跟踪远程的v3.8.8分支。这条命令同时完成创建本地分支、关联远程分支、切换到该分支三件事。如果你想基于master创建自己的开发分支可以这样git checkout -b dev_mine origin/master这样你就有了一个属于自己的本地开发分支之后所有改动都提交在这个分支上不会影响master。4.3 TortoiseGit下切换分支的操作路径如果你习惯图形界面在项目文件夹上右键 - TortoiseGit - Switch/Checkout。弹出的对话框里在Branch下拉框选择远程分支带上origin/前缀的那个或者直接在Ref输入框里填写分支名。下方有个Create New Branch的选项勾选后可以输入新的本地分支名效果等同于git checkout -b。这里有个容易踩的坑窗口下方的Branches列表里默认显示的是本地分支很多人选完本地分支点了确定结果发现代码没变成远程的新版本。正确的操作是先选中远程分支再点击OK。刚开始用TortoiseGit切分支的朋友在这一点上翻车概率极高建议操作完立刻执行git branch核实一下当前所在分支。4.4 切换分支后立刻要做的验证切换分支成功不等于万事大吉你还得确认环境是否匹配。做三件事第一确认当前分支。git branch第二查看当前分支与远程的同步状态。git status如果输出Your branch is up to date with origin/v3.8.8说明分支已正确关联。第三检查项目版本标识。打开RuoYi-Vue目录下的pom.xml看version标签里的版本号是否与你的分支号一致。这个检查看似多余但能避免一种常见失误分支切过去了但IDE缓存里还是旧版本的依赖后续启动报错让你怀疑人生。5. 实操记录从Gitee拉取到本地跑通的完整过程5.1 拉取项目实录我以一次实际操作为例完整记录从拉取到项目导入的过程。在本地创建好工作目录比如D:\workspace打开Git Bash执行cd /d/workspace git clone gitgitee.com:y_project/RuoYi-Vue.git这里我用的是SSH地址。如果你没配置SSH也可以用HTTPS地址git clone https://gitee.com/y_project/RuoYi-Vue.git两种方式的结果一样但HTTPS每次推送会要求输入Gitee的账号密码SSH则不需要这也是我推荐SSH的原因。克隆完成后进入项目目录cd RuoYi-Vue git branch -a看到远程分支列表后执行git checkout -b v3.8.8 origin/v3.8.8我用v3.8.8举例实际操作时你以仓库当前存在的版本分支为准也可以直接用master。不过我做二次开发的习惯是选择发布版分支因为维护性和稳定性都更好这点前面已经解释过。5.2 数据库初始化与后端启动RuoYi-Vue需要MySQL数据库版本建议5.7或8.0。在MySQL中创建数据库CREATE DATABASE IF NOT EXISTS ruoyi-vue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;然后找到项目里的sql目录里面有ry_2024xxxx.sql和quartz.sql两个脚本。ry_开头的是主库脚本quartz.sql是定时任务相关的表。用命令行导入mysql -u root -p ry_2024xxxx.sql mysql -u root -p quartz.sql或者用Navicat直接导入注意选择目标数据库后再运行脚本不然表会建到别的库里。导入完成之后修改后端配置。打开ruoyi-admin/src/main/resources/application-druid.yml把数据库连接信息改成自己的url: jdbc:mysql://localhost:3306/ruoyi-vue?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLtrueserverTimezoneGMT%2B8 username: root password: 你的密码然后启动ruoyi-admin模块下的RuoYiApplication主类看到Spring Boot启动日志里出现Started RuoYiApplication就说明后端起来了。最后执行mvn clean install -DskipTests或直接通过IDE构建确保所有模块编译通过。5.3 前端依赖安装与启动前端在ruoyi-ui目录下。打开终端进入该目录cd ruoyi-ui npm install这里有个实战提醒如果npm install非常慢大概率是因为没有配置淘宝镜像。执行npm config set registry https://registry.npmmirror.com然后再跑npm install。安装完成后启动开发服务器npm run dev默认端口是80启动成功后浏览器访问http://localhost用默认账号admin、密码admin123登录看到首页就说明前后端联调通了。6. 分叉点上的决策master当基线还是版本分支当基线6.1 两种选择的利弊对比很多人在用哪个分支做二次开发基线上拿不定主意。我做了张简表方便你权衡对比维度用master分支用发布版本分支功能新鲜度最新包含未发布的改动相对稳定经过测试文档匹配度低网上教程可能对不上高大多教程基于版本分支编写官方升级路径直接拉取即可需手动合并版本间差异长期维护成本高易发生冲突低基线明确适合场景尝鲜、学习、短期项目正式二次开发、商用交付表格总结一句话如果你打算把这个项目当真项目来养选版本分支如果你只是随便看看功能选master也行。6.2 我踩过的一次分支选择坑我曾经在某个项目里直接用master做基线开发开发到第三个月官方推送了一次比较大的依赖版本升级涉及Spring Boot和某安全组件的版本调整。我执行git pull后自己改过的几个核心业务类全部冲突而且因为官方调整了整个依赖体系导致本地编译都过不了。那一次花了我整整一天去解决冲突和适配新版本。后来我总结了一个原则二次开发的主分支一定要和官方维护分支划清界限。要么选一个发布版本分支做开发基线要么基于master拉一条独立开发分支并删除本地的master跟踪关系避免误操作把官方更新拉进自己的代码中。正确的隔离方式# 基于发布分支创建业务开发分支 git checkout -b dev_company origin/v3.8.8 # 推送业务分支到自己的远程仓库如果你有 git push origin dev_company这样你的dev_company分支和官方的v3.8.8有共同的起点但之后各走各路你的业务提交全在dev_company上官方更新只在v3.8.8上。需要同步官方更新时再单独执行合并git checkout dev_company git merge origin/v3.8.8这个流程兼顾了代码隔离和可升级性两个诉求。6.3 本地分支太多导致混乱的解决办法分支管理还有一个很实际的问题开发时间长了本地一堆分支有时候自己都忘了哪些是干嘛的。我建议建立一套分支命名约定比如dev_业务名_日期日常开发分支fix_问题编号bug修复分支feat_功能名新功能开发分支如果你的团队规模小也可以更简单只有一个develop分支作为集成分支个人开发时直接在上面提交。关键是团队内部要达成一致否则分支规范本身会成为新的混乱源。7. 常见问题与排查技巧实录7.1 Gitee拉取项目时报Permission denied (publickey)这个报错几乎每个刚配SSH的人都会遇到。原因基本有三种第一种你没有把公钥添加到Gitee后台。回到cat ~/.ssh/id_rsa.pub完整复制公钥内容粘贴到Gitee的SSH公钥设置页面。第二种你添加公钥的时候带了空格或换行符。这个坑很容易被忽略特别是从终端复制长串文本时末尾可能带上一个换行。粘贴完保存后重新测试ssh -T gitgitee.com。第三种多SSH密钥环境下Git选错了密钥。如果你本机有多个SSH密钥比如公司GitLab一个、个人Gitee一个需要在~/.ssh/config中配置指定Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_rsa_gitee7.2 切换分支后代码内容没变化这种情况通常不是你操作错了而是你切换的目标分支和当前分支在目标目录下的内容相同。比如v3.8.8和master在某个文件上没有差异你切过去当然看不到变化。但如果确认两个分支应该不同却没有任何变化那很可能是工作区有未提交的修改Git阻止了切换。此时用git status查看工作区状态把改动提交或暂存后再切分支。7.3 npm install 报 ERESOLVE unable to resolve dependency tree这个问题在Vue 2项目里太常见了尤其是Node版本太高时。RuoYi-Vue基于Vue 2和旧版依赖在高版本Node里容易出现依赖解析失败。解决办法有两种第一种降低Node版本到14或16。可以用nvm管理Node版本在项目目录下执行nvm use 16第二种使用legacy-peer-deps强制兼容旧依赖解析模式npm install --legacy-peer-deps这个参数等于告诉npm依赖冲突先不管按传统方式装。RuoYi-Vue这种经过大量实践的项目依赖关系实际上是兼容的只是新版npm的解析规则太严格。7.4 后端启动时报数据库连接失败先确认MySQL服务是否启动Windows下可以在服务管理里查看MySQL服务状态。再检查application-druid.yml里的用户名密码是否匹配特别注意密码中的特殊字符是否被YAML解析成其他含义。如果密码包含或冒号这类字符建议用单引号包起来。还有一个小概率问题数据库字符集。RuoYi-Vue的初始化脚本包含中文数据如果库字符集不是utf8mb4启动后查询数据可能乱码。建库时一定带上DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci。7.5 前端能打开但接口全部401后端权限过滤器在起作用说明前端没带上登录token。先确认前端访问的接口地址和后端实际地址是否一致看ruoyi-ui/.env.development里的VUE_APP_BASE_API配置ENV development VUE_APP_BASE_API /prod-api这里的/prod-api是前端代理前缀真正转发的地址在vue.config.js里的proxy配置。如果后端接口地址和代理目标不一致登录接口就会请求到错误地址自然拿不到token。8. 分支切换之外定义一个自己的上游管理策略分支切换这个主题讲到最后我想补充一个很多人忽略但长期收益极高的习惯定义清楚你的上游是什么。在Git世界里上游指的是你的本地分支跟踪的远程分支。默认拉取RuoYi-Vue官方仓库后本地分支的上游是origin/master或origin/v3.8.8这里的origin指向官方仓库。但在真实二次开发中你不应该直接往这个origin推送代码。正确姿势在Gitee上创建自己的仓库比如company/RuoYi-Vue把它添加为另一个remote命名为myorigingit remote add myorigin gitgitee.com:company/RuoYi-Vue.git git push -u myorigin dev_company这样你的工作区同时拥有两个remoteorigin代表官方仓库myorigin代表自己的代码仓库。日常开发中从origin拉取官方更新向myorigin推送自己的代码。这个拓扑结构干净清晰也便于多人协作时彼此之间用myorigin作为交互中枢。别嫌麻烦这个动作值得做。原因很简单它把官方代码和我的代码变成了两个物理隔离的仓库无论后续官方仓库怎么变化自己的代码仓库始终是稳定的交付基线。9. 关于这套环境的几个实践体会我在不同阶段用RuoYi-Vue做过几个大小不一的项目感触比较深的有几点第一分支切换的复杂度往往不在执行而在决策。什么时候切、切到哪里、切完怎么办这些问题想清楚命令本身两秒钟就能执行完。第二刚拉完项目别急着写代码先把数据库初始化 - 后端启动 - 前端启动 - 页面可登录这条链路完整跑通一遍。这一步确认了相当于给你的开发环境交了个底后面所有功能开发都有了一个可验证的起点。第三RuoYi-Vue这类成熟脚手架最大的价值不是代码本身而是它帮你规范了项目结构、权限模型和通用能力。二次开发的时候尽量顺着它的既定模式走不要一上来就推翻它的架构设计。很多功能官方已经预留了扩展点在扩展点上做加法比在核心逻辑上做替换省力且安全得多。下一篇我会讲真正进入二次开发后的第一个核心动作——代码生成器的使用和前后端联调细节。代码生成器是RuoYi-Vue拉开和其他脚手架差距的地方也是最容易出体验问题的地方到时候边操作边聊。