前阵子带一个刚入职的同事熟悉项目他问我怎么才能把写了一半的代码安全地放到Gitee上换台电脑还能接着写我告诉他这事说穿了就是三样东西配合VS Code负责写代码Git负责记录每次改动Gitee负责把代码放到云端存着。这三者接好了拉取、更新、提交、推送全是顺手的事。这篇东西就是写给准备把VSCode和Gitee连起来用的朋友。不管你是刚装好VS Code还是已经在本地写了一堆代码想托管到Gitee又或者代码已经传上去了但还搞不清怎么拉取更新都可以按下面的流程走一遍。我会把每一步为什么要这么做讲清楚也会把最容易踩的坑提前指出来。1. 先弄懂VS Code、Gitee和Git三者是什么关系1.1 三者的分工很多人一开始就卡在概念上觉得VSCode连Gitee是个很高深的事。其实不复杂打个比方就能说清楚。VS Code是你的工作台你在上面写代码、改代码它本身不关心代码怎么保存、怎么上传。Git是装在电脑上的一个版本管理工具它负责记录你每一次改动哪一行改了、哪个文件删了、什么时候改的这些记录都存在你电脑本地的.git目录里。Gitee是一个代码托管平台相当于网上的一个备份仓库你本地Git里的记录和文件可以推送到Gitee上存一份反过来Gitee上的最新版本也可以拉到你的本地。所以VSCode连接Gitee这个说法严格来说不太准确。VS Code并不是直接和Gitee通信而是VS Code内置了Git客户端通过Git命令和Gitee交互。VS Code只是把git操作包装成了可视化的按钮让你不用敲太多命令行而已。1.2 连接的两种地址HTTPS和SSH要让本地Git和远端Gitee仓库通信需要给本地指定一个远端地址。Gitee每个仓库都会提供两种地址。HTTPS地址形如https://gitee.com/用户名/仓库名.git。用这种方式连接每次推送或者拉取私有仓库时大概率会要求输入Gitee的用户名和密码如果是私有仓库甚至需要输入账号密码验证比较麻烦。SSH地址形如gitgitee.com:用户名/仓库名.git。用这种方式连接靠的是本机和Gitee之间配好的一对密钥私钥留在本地公钥填到Gitee后台。配好之后推送拉取都不需要再输密码。我的建议很简单如果你只是临时下载公开仓库的代码用HTTPS就行如果你要把自己的项目长期管理起来、日常频繁推送更新优先配SSH。这篇文章后面的流程主要按SSH方式走因为这才是连上之后不用反复验证密码的正解。2. 装机、注册、配密钥连接Gitee前必做的三件事2.1 安装Git和VS Code时最容易忽略的细节Git的安装包在官网下载Windows系统直接下载exe安装包双击安装。安装过程中多数选项保持默认即可但有一个选项要特别注意在Adjusting your PATH environment这一步务必选择Git from the command line and also from 3rd-party software。如果选成Use Git from Git Bash only后续VS Code的终端里可能就无法直接使用git命令你会以为是VS Code的问题其实是PATH没配上。安装完之后在VS Code里按Ctrl \打开终端输入git --version能输出版本号就说明装好了。如果提示找不到命令检查一下是不是安装时PATH选项选错了或者安装完没有重新打开终端。VS Code本身的安装没什么可说的注意一点安装完成后建议先装中文语言包。在扩展市场搜索Chinese安装Chinese (Simplified) Language Pack for VS Code重启后界面就变成中文。这不是必须的但对新手来说中文界面的源代码管理按钮比英文的Source Control好认得多。2.2 注册Gitee账号与安全验证Gitee注册很简单手机号或者邮箱都可以注册。这里有一个我在实践中见过很多次的问题注册完账号之后在Gitee上创建Issue或者做某些操作时提示验证码错误明明输入的验证码跟图片上的一模一样还是报错。这个问题大概率不是你没看清验证码而是浏览器自动填充或者输入法把验证码的字母转成了全角字符。Gitee的验证码区分大小写建议在输入前把输入法切到英文半角状态必要时关掉浏览器的自动填充插件再试。另外注册和首次登录时它会要求设置用户信息和绑定手机号这些信息尽量一次填对后续改起来比较烦。2.3 SSH密钥的生成与配置密钥的生成和配置是整个流程里新手最容易被劝退的环节但只要你理解它其实很机械。打开VS Code终端输入下面的命令。这里的-C后面填你自己的邮箱不用纠结必须和Gitee注册邮箱一致它只是给密钥加个备注。ssh-keygen -t rsa -b 4096 -C 你的邮箱example.com回车之后它会问密钥文件保存位置默认是C:\Users\你的用户名\.ssh\id_rsa直接回车用默认值就行。接着它会让你设置passphrase密钥密码这里可以理解成给私钥再加一道锁通常本地个人电脑可以不设置直接回车跳过。如果设置了后面每次使用密钥时都要输一次密码虽然更安全但便利性会打折扣。密钥生成完成后在终端输入下面命令查看公钥cat ~/.ssh/id_rsa.pub输出的内容是一长串以ssh-rsa开头的字符串这就是公钥。把整段复制下来登录Gitee进入设置页面找到安全设置里的SSH公钥标题随便填把公钥粘贴到文本框里确定保存。这里有个细节值得留意公钥是可以公开的它相当于一把锁私钥id_rsa是绝对不能泄露的它相当于开锁的钥匙。很多新手搞反了把整个.ssh目录都打包发到网上去这是非常危险的操作。私钥一旦泄露别人就能用你的身份往Gitee仓库里推代码。2.4 验证连接是否成功公钥填完之后在终端里执行ssh -T gitgitee.com如果是第一次连接会出现一个确认提示询问是否继续连接输入yes回车。然后如果看到类似Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.的提示就说明本机和Gitee之间的通道已经打通了。看到这个提示也不用慌Gitee就是不提供shell权限的它只是在告诉你身份验证通过了。到这里环境准备才算真正结束。很多教程把这一步省略了导致后面克隆仓库时直接报权限错误然后开始瞎猜是不是仓库名写错了、账号密码不对。提前做一次连通性验证能帮你在后续步骤里节省大量排查时间。3. Gitee仓库创建与VS Code绑定第一次拉取的完整流程3.1 仓库的可见性、许可证与初始文件怎么选登录Gitee点击页面上方的号选择新建仓库。创建仓库时有几个选项需要你亲手选很多人在这里拿不定主意。第一个是仓库名称。名称建议用英文和短横线比如my-blog、note-taking-app。因为仓库名会成为仓库地址的一部分中文名或者带空格的名字会在克隆时被URL编码容易出问题。第二个是仓库的可见性。Gitee提供私有仓库和公开仓库两种选择。私有仓库只有你和被你邀请的协作者能看到适合个人项目、公司内部项目公开仓库所有人都能看到适合开源分享。建议刚开始做练习时选私有等确定要开源了再改公开反正仓库可见性随时可以改。第三个是初始化仓库相关的几个选项README、.gitignore、开源许可证。这里新手最容易犯的错误是什么都不勾选直接创建空白仓库然后去本地执行各种命令关联结果因为远端没有任何初始提交而报错。反过来也有人全勾上结果生成了一个带着README的仓库本地代码推送时又出现冲突。我的建议是如果你准备把本地已有代码推上去创建仓库时不勾选README和.gitignore直接创建一个空仓库然后按照后面4.2节的方法关联推送。如果你是从零开始、想直接在Gitee上把框架搭起来再克隆到本地那可以把README和.gitignore都勾上。第四个是开源许可证。如果你选了公开仓库Gitee会要求你选一个许可证。这个东西简单说就是你允许别人怎么使用你的代码。最常用的是MIT许可证它非常宽松别人可以用你的代码做任何事只要保留你的版权声明就行。如果你的项目不想让别人商用可以选择GPL类的许可证。如果只是自己用的私有仓库许可证选什么都无所谓。3.2 拿到仓库地址区分两种克隆方式仓库创建好之后会自动跳转到仓库主页。页面上的克隆/下载按钮会给你两个地址HTTPS和SSH。如果你按照第二章配好了SSH密钥这里直接复制SSH地址。然后打开VS Code按Ctrl 打开终端或者直接用终端窗口进到你想要存放代码的目录执行git clone gitgitee.com:你的用户名/仓库名.git克隆完成后当前目录下会出现一个以仓库名命名的文件夹里面就是Gitee上的所有文件。用VS Code的打开文件夹功能选择这个目录你会发现左侧的源代码管理图标上多了个数字角标那表示一个Git仓库已经被VS Code正确识别了。3.3 VS Code中克隆代码的另一种方式除了用终端命令行克隆VS Code也支持纯界面操作。打开VS Code按Ctrl Shift P打开命令面板输入Git: Clone然后粘贴仓库地址选择本地存放目录VS Code会自动帮你克隆。克隆完成后右下角会弹出提示问你是否打开克隆的仓库点打开即可。两种方式没有优劣之分命令行更适合想搞清楚原理的人界面操作更适合快速上手。我个人的习惯是命令行因为克隆发生在终端里更直观而且克隆完成后会自动停在仓库目录下方便继续执行后续命令。3.4 本地已有代码怎么和Gitee新仓库关联如果你不是从Gitee克隆下来的而是本地已经有一份代码想在Gitee上给它建个远程仓库流程也简单。先在Gitee上创建一个空仓库不勾选任何初始化选项然后在本地代码目录里执行git init git add . git commit -m 首次提交 git remote add origin gitgitee.com:你的用户名/仓库名.git git push -u origin master这里的逻辑很容易理解git init是让本地目录变成一个Git仓库git add .把所有文件放入暂存区git commit形成第一次提交记录git remote add origin把Gitee的远程仓库命名为origin保存下来git push -u origin master把本地的master分支推送到远程并且设置好默认的上游关联。这里有个常见的坑如果Gitee仓库创建时勾选了README你本地git push时就会收到一个rejected错误说远程分支包含本地没有的提交。原因是远端有一个自己的README提交而本地没有。解决办法是执行git pull --rebase origin master这会把远端的README提交合并到本地然后再推送就不会报错了。关于合并的原理后面第四章会详细说。4. 日常更新从拉取到提交推送的完整协作闭环4.1 拉取到底在做什么很多人对拉取的理解就是把最新的代码下载下来。对但不够精确。理解一下Git的三层存储结构后续操作会更顺畅。Git仓库里代码存在三个区域工作区就是你在VS Code里看到的文件、暂存区用git add放进去的改动、本地仓库用git commit提交后的记录。Gitee上的远端仓库是第四个区域它对应你本地仓库的一个远程副本。拉取的完整意思是把远端仓库的最新提交记录和文件变化合并到你本地仓库和工作区。它不是简单地把文件覆盖到你本地而是先获取远端的提交记录然后再与本地记录做合并所以如果本地有未提交的改动拉取时可能会提示冲突或者拒绝合并。在VS Code里最简单的拉取方式是打开源代码管理面板点击右上角的更多操作图标三个点选择拉取。或者直接按Ctrl Shift P输入Git: Pull回车。终端则是执行git pull这相当于git fetch加git merge两步操作。先说fetch它只把远端的新提交记录下载到本地但不会改变你工作区的文件。再说merge它把下载下来的新提交合并到当前分支。4.2 修改、提交、推送的完整操作把代码拉到本地之后你在VS Code里改文件比如修改index.html保存后回到源代码管理面板你会发现这个文件出现在更改列表里前面有一个字母M代表Modified已修改。提交应该遵循三步顺序暂存、提交、推送。第一步暂存。在源代码管理面板的更改列表里你可以在单个文件上点击号或者直接点击列表顶部的号暂存所有更改。这相当于命令行里的git add .。理解暂存区的一个好方法是先暂时放下我把所有修改都提交上去这个想法暂存是让你先挑一挑哪些改动要进入本次提交哪些留下不要。第二步提交。在源代码管理面板顶部的输入框里写一段提交说明比如修复首页导航栏样式然后点击提交按钮或者按Ctrl Enter。这相当于命令行里的git commit -m 提交说明。提交形成一条不可回溯的记录写清楚说明对后续排查问题是极大的帮助。第三步推送。提交完成之后本地仓库领先于远端仓库代码还没有离开你的电脑。点击源代码管理面板右上角的三个点选择推送或者执行git push。这时本地记录才会同步到Gitee上。很多刚接触Git的人会把提交和推送当成一回事以为点了提交代码就上传了。实际不是这样。提交是本地的动作推送才涉及网络传输。如果你提交了但没推送换个电脑或者重装系统这些提交就会丢。4.3 提交说明写得好少加很多班提交说明这件事看着不起眼但对长期维护的项目太重要了。三个月前你自己写的代码如果没有清晰的提交说明翻history时你可能都猜不到当初为什么那么改。我个人习惯用统一格式类型加描述。比如fix: 修复登录按钮点击无响应、feat: 新增文章搜索功能、docs: 更新README文档。常见类型就几类——fix修bugfeat加功能docs文档refactor重构style格式化。这样以后看git log一眼就能看出这个提交是干什么的。还有一个经常被问到的问题提交完发现说明写错了想改怎么办用git commit --amend。这个命令的作用是修改最近一次提交的说明或者把刚才漏掉的改动补进同一次提交里。用法如下git commit --amend执行后会打开编辑器让你修改提交说明改完保存退出即可。也可以一步到位写新说明git commit --amend -m 修改后的提交说明但注意--amend改的是本地的提交记录如果已经执行了push就不要再用它了。因为远端已经保存了旧提交信息本地强行改写会导致两边的提交哈希不一致下次推送时又要处理复杂的历史改写新手别碰这个。4.4 fetch和pull的区分再深挖一层。git pull虽然日常够用但遇到复杂场景时灵活使用git fetch能帮你避免一些莫名其妙的合并问题。比较直观的例子你和同事同时在一个仓库工作。你在本地提交了3个改动同事往远端推送了2个改动。此时你执行git pullGit会把同事的2个改动拉下来并尝试和你本地的3个改动合并。如果两边改的不是同一个文件合并会很安静地成功你接着写代码就行。如果两边改了同一个文件的不同位置Git也大概率能自动合并。但如果两边改的正好是同一个文件的同一段逻辑就会产生冲突Git会在文件里插入冲突标记要求你手动处理。如果你想先看看远端到底有哪些提交、哪些文件变了再决定怎么合并就不要用pull改用git fetchfetch只更新本地的远程跟踪分支比如origin/master,不会动你的工作区。然后你可以用git log origin/master看看远端的最新记录确认没有坑之后再执行git merge origin/master效果等同于git pull。这种先看再合的做法对多人协作的项目是很实用的习惯。5. 高频踩坑清单拉取失败、密钥失效、上传冲突怎么办5.1 SSH权限被拒的排查链路最典型的报错是Permission denied (publickey)。字面意思就是公钥验证失败。很多新手这时会马上跑回去重新生成密钥反复折腾。其实排查顺序应该按照下面这条链来走省时省力。第一步确认本机有没有加载密钥。终端执行ssh-add -l如果提示The agent has no identities说明密钥没有被SSH-agent加载。在Windows上可以执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_rsa第二步重新验证连通性。执行ssh -T gitgitee.com如果仍然提示权限不足进入第三步。第三步终端执行cat ~/.ssh/id_rsa.pub把输出的公钥和Gitee后台已添加的SSH公钥逐字对比。重点看结尾Gitee上保存的公钥末尾不能有多余的空格或换行而复制公钥粘贴时非常容易混入全角字符。第四步确认本机的known_hosts没有被污染。如果你多年前就连过Gitee后来Gitee换了密钥本机的known_hosts里可能还留着旧指纹。解决办法是把~/.ssh/known_hosts里关于gitee.com的行删掉然后重新连接。这条链路走下来九成的密钥问题都能解决。还有一招能快速判断是不是密钥问题换用HTTPS地址克隆一次。比如你原本用SSH地址克隆失败改用https://gitee.com/用户名/仓库名.git克隆如果HTTPS能成功问题几乎肯定出在SSH密钥配置上。5.2 push被拒两种最常见的冲突场景推送时被拒绝是每个人都会遇到的。常见的报错是Updates were rejected because the remote contains work that you do not have locally或者failed to push some refs。看到这类提示千万别急着用git push -f强推。-f是--force的意思它会用本地版本覆盖远端把远端已有的提交全部冲掉。如果远端有同事的改动你这么一盖同事的代码就没了这是高危操作。正确思路是先拉取远端的内容合并冲突再推送。git pull git push如果git pull自动合并失败Git会标出冲突文件你需要手动打开冲突文件你会看到类似下面的标记: HEAD 本地修改的内容 远端修改的内容 origin/master工作是把到之间和到之间的内容按你的业务需要整理成一段删掉三对标记保存文件然后执行git add . git commit -m 合并冲突 git push这里有个经验之谈合并冲突的处理宁可多花十分钟逐段看也不要图快直接选一边。有时候你觉得远端的旧版本才是对的但对方可能本来就有改动意图。如果不确定找修改对应代码的人确认一下比猜着合并靠谱。5.3 同时使用Gitee和GitHub多个账户时的密钥冲突搜索热词里有个问题很真实本机全局配置了Gitee和GitHub两个库两边账户不同使用时总出问题。问题的根源在于默认情况下Git会把同一套密钥用于所有连接。你注册Gitee用的是密钥A注册GitHub用的是密钥B连接Gitee时它却可能用密钥B去验证自然失败。解决思路是让不同的域名走不同的密钥不要一刀切。修改~/.ssh/config文件没有就新建配置如下内容Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_rsa_gitee IdentitiesOnly yes Host github.com HostName github.com User git IdentityFile ~/.ssh/id_rsa_github IdentitiesOnly yes然后在~/.ssh/目录下分别生成id_rsa_gitee和id_rsa_github两套密钥把对应的公钥分别填到Gitee和GitHub后台。这样git就会根据连接的主机名自动选择对应的私钥。配好之后分别执行ssh -T gitgitee.com和ssh -T gitgithub.com两边都验证通过就可以在两套托管平台之间自由操作了。如果你不用GitHub只配Gitee一套密钥就不会遇到这个问题但既然提前了解了机制以后多平台协作也心里有底。5.4 换电脑、重装系统后连不上Gitee的思路换新电脑或者重装系统之后发现ssh -T gitgitee.com提示权限拒绝这很正常。因为新电脑没有你原来的私钥而Gitee后台还挂着旧公钥。处理方式很简单在新电脑上重新生成一套密钥把新公钥添加到Gitee后台然后可以顺手把旧公钥从后台删除。这个操作不影响仓库内容只影响本机与Gitee的认证及时的清理能避免旧设备丢失后的安全隐患。还有一种更彻底的想法换电脑时直接迁移整个~/.ssh目录。把旧电脑的id_rsa和id_rsa.pub复制到新电脑的对应位置保持文件权限正确Windows下一般注意目录归属即可这样密钥就不用重新生成。但私钥文件的传输必须通过安全渠道别发到聊天工具里。另外很多人遇到使用TortoiseGit拉取Gitee代码拉不下来的问题。如果你熟悉了SSH密钥的原理就会知道这通常不是TortoiseGit本身的问题而是它使用的PUTTY密钥格式与OpenSSH密钥格式不一致或者密钥根本没有配置到Gitee后台。解决办法是在TortoiseGit的设置里指定使用整套OpenSSH的私钥或者在TortoiseGit的PuTTY Pageant中导入私钥。核心判断思路始终是一样的换工具不换原理先确认密钥通道是否通。6. 让日常操作更顺手的小习惯6.1 善用VS Code源代码管理面板VS Code的源代码管理面板其实比很多新手以为的还要好用。它不只可以提交、推送还能直接显示文件改动点击任意文件编辑器会打开一个diff视图左边是旧版本右边是新版本改动一目了然。这种可视化对比比命令行里的git diff直观太多。建议你养成一个操作顺序改动代码前先看源代码管理面板确保没有未提交的改动残留改动之后提交前先看一眼diff确认自己的改动都在预期范围内。这两个习惯能帮你挡掉不少刚才还好好的我改完就崩了的问题。6.2 让.gitignore替你管理不想上传的文件很多新手第一次git push后打开Gitee仓库发现里面塞满了node_modules、target、数据库配置、本地环境变量文件等等仓库迅速变得臃肿。这时候就需要.gitignore文件出手。.gitignore是仓库根目录下一个文本文件里面列出的文件或目录不会被git跟踪。原则就是只要不是别人克隆代码后必要的内容都该忽略。常见有node_modules/、.idea/、*.log、dist/、build/等。Gitee在创建仓库时如果勾选了.gitignore选项会自动根据你选择的语言模板生成一份基础版本但里面未必覆盖你自己的项目特有文件需要手动补充。有一点容易误导人.gitignore只对未跟踪的文件生效。如果你的文件已经被git add跟踪了再在.gitignore里写它也来不及了需要先执行git rm --cached 文件名把它从跟踪列表中移除然后再提交。这个命令只是解除跟踪不会删除你本地的文件。6.3 分支不是洪水猛兽是工作的边界很多刚接触Git的人看到分支两个字就头大其实分支的作用通俗理解就是在一条主线上干活时开一条临时的小路在小路上折腾折腾好了再合并回主线折腾坏了就把小路封掉不影响主线。在VS Code里新建分支很简单点击状态栏左下角的分支名默认显示master或者main输入新分支名回车即可。切换分支也一样点击分支名选择要切换的目标分支。日常使用中最安全的操作模式是平时都在主分支上保持稳定可运行的状态要改大功能时开新分支去改功能验证完毕再合并回主分支。这个习惯可能一开始觉得麻烦但当你被自己主分支上的半成品代码坑过一次就会明白为什么人人都推荐这么干了。写在最后从配好第一把SSH密钥到第一次从Gitee拉下自己的项目再到第一次把本地修改稳稳推送上去这个过程我走过也知道中间会卡在哪些地方。最让我感慨的是很多看似难住人的问题本质都是对本地、暂存区、远程这三个概念的关系没理顺。把这几个概念想透了Gitee、GitHub、GitLab换哪个平台都只是换一个地址的事。如果你照着这篇文章走通了流程建议接下来自己动手做个小实验在Gitee上建一个测试仓库用另一台电脑或者手机网页端往里面提交一次改动然后回到你的VS Code执行一次拉取看看改动是怎么流回你本地的。这个过程亲手走一遍比看十篇教程都管用。等这套操作成了肌肉记忆你会发现VS Code连接Gitee这件事真的只是开发的起点而已。