1. 为什么在VSCode里用Gitee而不是GitHub如果你是一个在国内做开发的朋友大概率遇到过这样的场景想从GitHub上clone一个开源项目结果速度慢得像在爬或者想把自己的代码推上去结果因为网络问题反复失败。这时候一个稳定、快速的国内代码托管平台就显得尤为重要。Gitee码云就是这样一个选择它提供了与GitHub类似的核心功能——代码托管、版本管理、协作开发但服务器在国内访问速度和稳定性对国内开发者友好得多。Visual Studio Code简称VSCode作为当下最流行的轻量级代码编辑器其强大的扩展生态让它几乎无所不能。将Gitee与VSCode结合意味着你可以在一个熟悉、高效的编辑环境里完成从代码编写、本地版本管理到远程仓库同步的完整闭环。你不再需要频繁地在命令行和多个图形化工具之间切换所有Git操作都可以在VSCode的侧边栏、状态栏和源代码管理视图中直观完成。这篇文章的目的就是帮你把这个闭环搭建起来并且讲透每一个细节。我会假设你是一个刚接触版本控制或者对命令行有畏惧感的开发者从零开始手把手带你完成环境配置、仓库关联、日常操作并分享那些官方文档里不会写的、只有踩过坑才知道的经验。我们不止讲“怎么做”更会深入讲“为什么这么做”以及“怎么做更高效、更安全”。2. 环境准备不仅仅是安装软件在开始连接VSCode和Gitee之前我们需要确保三样东西就位VSCode编辑器、Git版本控制系统以及一个Gitee账户。听起来简单但每一步都有需要注意的细节。2.1 安装与配置Git奠定版本管理的基石Git是这一切的引擎没有它版本管理无从谈起。第一步下载与安装前往Git官网下载对应你操作系统的安装包。对于Windows用户安装过程中有几个关键选项需要注意选择默认编辑器这里推荐选择“Use Visual Studio Code as Gits default editor”。这样当你需要编写提交信息或者解决合并冲突时会自动调用VSCode体验更统一。调整PATH环境建议选择“Git from the command line and also from 3rd-party software”。这个选项会将Git添加到系统的PATH环境变量中并允许你在VSCode这样的第三方软件中使用它。这是VSCode能调用Git命令的前提。配置行尾转换这是一个容易引发跨平台协作问题的设置。对于主要在Windows下开发的用户可以选择“Checkout Windows-style, commit Unix-style line endings”。Git会在你提交时自动将行尾符转换为LFUnix/Linux/macOS风格在检出时转换为CRLFWindows风格。这能最大程度保证代码在不同系统间的一致性。安装完成后打开终端Windows上是CMD或PowerShellmacOS/Linux是Terminal输入git --version如果能看到版本号说明安装成功。第二步必要的全局配置安装完Git后第一件事就是设置你的用户身份。这个身份信息会记录在你每一次的代码提交历史中。git config --global user.name 你的Gitee用户名 git config --global user.email 你的Gitee注册邮箱这里的邮箱强烈建议使用你在Gitee上注册账号时使用的邮箱。因为Gitee以及GitHub会通过这个邮箱来关联提交记录和你的平台账户这样在你的仓库贡献者图表里才能正确显示你的头像和链接。注意--global参数表示这是全局配置对你这台电脑上所有的Git仓库生效。如果你有为特定项目使用不同身份的需求比如公司用公司邮箱个人用个人邮箱可以在项目目录下使用不带--global参数的命令进行局部覆盖。2.2 在VSCode中集成Git让编辑器成为控制中心VSCode对Git的支持是内置的无需额外安装扩展即可进行基本的提交、拉取、推送操作。但是为了获得更佳的体验我推荐安装一个官方扩展。打开VSCode进入扩展市场快捷键CtrlShiftX搜索并安装“GitLens”。这个扩展功能极其强大它会在你的代码行内显示最近的提交信息、作者提供强大的提交历史查看、代码比对blame功能并且极大地丰富了源代码管理视图的交互。安装后你可以在左侧活动栏看到一个类似Git分支的图标那就是GitLens的视图。现在打开VSCode的设置Ctrl,搜索“git.path”。如果VSCode没有自动检测到你的Git安装路径你需要在这里手动指定Git可执行文件的完整路径例如Windows上可能是C:\Program Files\Git\bin\git.exe。确保这一步正确是VSCode能与Git通信的关键。2.3 注册与配置Gitee账户准备你的远程仓库访问Gitee官网注册一个账号。注册过程很简单这里不再赘述。注册完成后有一件非常重要的事配置SSH公钥。为什么是SSH而不是HTTPS因为SSH连接方式更安全并且在每次推送/拉取时不需要反复输入用户名和密码配置一次即可。对于需要频繁与远程仓库交互的开发工作流来说这是必须的。生成SSH密钥对在你的终端中执行以下命令邮箱替换为你的Gitee注册邮箱ssh-keygen -t rsa -b 4096 -C your-emailgitee.com连续按三次回车接受默认的存储路径~/.ssh/id_rsa和不设置密码为方便起见生产环境可根据安全要求设置密码。完成后你会在~/.ssh/目录下得到两个文件id_rsa私钥绝对不要泄露和id_rsa.pub公钥。在Gitee中添加公钥登录Gitee点击右上角头像进入“设置”。在左侧菜单中选择“SSH公钥”。在“标题”栏为你这个密钥起个名字比如“My Laptop”。用文本编辑器打开刚才生成的id_rsa.pub文件将其全部内容复制到“公钥”栏中。点击“确定”。验证连接回到终端输入ssh -T gitgitee.com如果看到类似 “Hi XXX! Youve successfully authenticated...” 的欢迎信息说明配置成功。如果遇到问题通常是公钥未正确复制注意不要有多余的空格或换行或者Gitee服务端未及时更新稍等片刻再试。至此我们的“地基”已经全部打牢。VSCode、Git、Gitee三者已经准备就绪并且通过SSH密钥建立了安全的通信通道。接下来我们就可以开始真正的版本管理之旅了。3. 从零开始初始化仓库与首次推送现在我们手上有一个即将开始的新项目或者一个已经写了一些代码的本地文件夹。如何把它变成一个受Git管理并且能同步到Gitee的正式项目呢有两种主要场景。3.1 场景一本地已有项目需要关联到新的Gitee仓库这是最常见的情况。假设你已经在D:\my_project文件夹里写了一些代码。在VSCode中打开项目文件夹直接打开这个文件夹。初始化本地Git仓库点击左侧活动栏的源代码管理图标或按CtrlShiftG你会看到一个“初始化仓库”的按钮。点击它选择当前文件夹作为仓库根目录。瞬间这个文件夹就变成了一个Git仓库。VSCode会在后台执行git init命令。进行首次提交初始化后源代码管理视图会列出所有未被跟踪的文件。你可以点击文件旁边的号将它们暂存Stage或者直接点击“更改”上方的号暂存所有更改。在顶部的输入框里撰写你的第一次提交信息例如“feat: 项目初始化包含基础框架”。然后点击输入框上方的勾号✓提交。至此你的代码有了第一个本地版本记录。在Gitee上创建远程仓库打开浏览器登录Gitee点击右上角的“”号选择“新建仓库”。填写仓库名称如my_project补充描述这里有一个关键选择“是否选择初始化仓库”请务必选择“不初始化”因为我们已经有本地仓库和代码了不需要Gitee帮我们生成README等文件否则后续关联时会遇到冲突。关联远程仓库并推送创建成功后Gitee会给出仓库的SSH地址格式如gitgitee.com:yourname/my_project.git。回到VSCode在源代码管理视图的“···”更多操作菜单中选择“远程” - “添加远程”。输入一个远程仓库名称通常叫origin。然后粘贴刚才复制的SSH地址。最后再次点击“···”菜单选择“推送”并在弹出的远程分支选择中选择origin分支选择master或main取决于你的默认分支名。稍等片刻刷新你的Gitee仓库页面代码就上去了。3.2 场景二从Gitee克隆现有项目到本地如果你想参与一个已有的项目或者想把自己的项目从另一台电脑上拉下来继续开发克隆是最直接的方式。获取仓库地址在Gitee上找到你想克隆的项目点击绿色的“克隆/下载”按钮选择“SSH”方式复制地址。在VSCode中克隆有多种方式命令面板按F1或CtrlShiftP输入 “Git: Clone”回车。欢迎页面如果是VSCode启动后的欢迎页也有“克隆Git仓库”的选项。源代码管理视图点击“克隆仓库”按钮。粘贴地址并选择路径将复制的SSH地址粘贴到输入框回车。接着选择一个本地文件夹来存放这个项目。VSCode会自动完成克隆并询问你是否打开克隆下来的仓库。选择“打开”项目就在你的本地并完全关联好了远程。实操心得我强烈建议无论是自己的新项目还是参与别人的项目优先使用SSH协议进行克隆和关联。HTTPS协议虽然简单但每次推送都可能需要输入密码甚至可能因为网络策略问题导致失败。SSH一劳永逸。如果你之前用HTTPS克隆了仓库可以运行git remote set-url origin gitgitee.com:xxx/xxx.git来修改远程地址为SSH格式。4. 日常开发工作流提交、分支与同步日常开发中我们绝大部分时间都在与提交、分支、拉取和推送打交道。在VSCode中这些操作变得非常直观。4.1 提交更改不仅仅是点一下“提交”提交是版本管理的最小单位。一个好的提交习惯能让历史记录清晰可读。查看更改当你修改了文件后源代码管理视图的“更改”列表会实时更新。点击任意一个文件右侧的编辑器区域会分成两栏清晰地展示“当前修改”与“上一个提交版本”的差异Diff。这是审查自己代码改动的最佳时机。暂存更改Git有一个“暂存区”Staging Area的概念。你可以选择性地将部分修改的文件甚至一个文件里的部分代码块添加到暂存区准备组成一次提交。在VSCode中你可以点击文件旁的号暂存整个文件或者将鼠标悬停在修改的代码块上点击出现的“”号来暂存特定代码块。这是进行精细提交的利器。比如你同时修复了一个bug和重构了一个函数应该分成两次提交这时就可以用此功能分别暂存。撰写提交信息在顶部的输入框撰写提交信息。我推荐使用 约定式提交 的格式例如feat: 添加用户登录功能fix: 修复首页图片无法加载的问题docs: 更新README安装说明style: 调整代码缩进格式非功能修改refactor: 重构用户数据验证模块这种格式能让提交历史像一本结构清晰的日志也便于后续自动化生成更新日志。提交点击输入框上方的勾号✓完成提交。提交后本次更改就从“更改”列表移到了下方的提交历史中。4.2 分支管理并行开发的基石分支是Git的杀手锏功能让你可以在独立的时间线上开发新功能或修复bug而不影响主线。创建新分支在VSCode左下方的状态栏你会看到当前分支名如main。点击它在弹出的顶部命令面板中选择“创建新分支”输入分支名例如feature/user-authentication。VSCode会自动创建并切换到新分支。切换分支同样点击状态栏的分支名你会看到本地和远程的所有分支列表选择你想切换的分支即可。合并分支当功能开发完成并测试通过后需要将其合并回主分支。首先切换到目标分支如main。然后在源代码管理视图的“···”菜单中选择“分支” - “合并分支”再选择你想要合并过来的源分支如feature/user-authentication。如果合并过程没有冲突会自动创建一个合并提交。删除分支合并完成后那个功能分支通常就没用了。你可以在“···”菜单 - “分支” - “删除分支”中将其删除。注意这只会删除本地分支。如果这个分支也曾被推送到远程Gitee你还需要在推送时使用git push origin --delete branch_name命令来删除远程分支或者在Gitee的网页端进行操作。4.3 与远程仓库同步拉取、推送与冲突解决团队协作中保持本地与远程仓库的同步至关重要。拉取在开始一天的工作前或者推送前最好先执行一次拉取将远程最新的更改同步到本地。点击源代码管理视图顶部的“···”菜单选择“拉取”。这相当于执行git pull。如果远程有更新它们会被自动合并到你的当前分支。推送当你完成了一些本地提交并希望将它们分享到远程仓库Gitee时就需要推送。点击“···”菜单选择“推送”。如果你的本地分支是第一次推送VSCode会提示你设置上游分支确认即可。处理冲突这是版本控制中无法避免的一环。当你和同事修改了同一文件的同一区域并且他先推送了你再拉取或推送时Git就会报告冲突。VSCode提供了非常好的冲突解决界面发生冲突的文件会在源代码管理视图中被标记出来。点击该文件编辑器会进入“合并编辑器”模式清晰地展示“当前更改”你的、“传入的更改”远程的和“结果”解决后的。你可以直接在上面选择接受“当前”或“传入”也可以手动编辑“结果”区域合并双方的修改。解决完所有冲突后必须将冲突文件暂存点击文件旁的号然后完成一次提交这次提交信息通常是“Merge branch ...“或”Resolve conflicts”。最后再次执行推送将解决冲突后的结果同步到远程。避坑指南养成“先拉取后推送”的习惯。在推送前务必先拉取一下远程的最新状态确保本地是基于最新的代码进行修改的这能极大减少冲突的发生概率和解决复杂度。一个简单的口诀Pull - Code - Commit - Pull Again - Push。5. 进阶技巧与高效配置掌握了基本操作后一些进阶技巧和配置能让你和团队的工作效率倍增。5.1 使用.gitignore文件保持仓库清洁你肯定不希望将编译产物、本地配置文件、依赖包如node_modules等文件提交到仓库中。.gitignore文件就是用来指定哪些文件或目录应该被Git忽略。在VSCode中在项目根目录新建一个名为.gitignore的文件。VSCode会对它有语法高亮支持。你可以根据项目类型添加规则例如对于一个Node.js项目# 依赖目录 node_modules/ # 构建产物 dist/ build/ # 环境变量文件 .env .env.local # 日志文件 *.log # 编辑器/IDE配置文件 .vscode/ .idea/你可以在 gitignore.io 这个网站输入你的开发语言、工具如Node, Windows, macOS, VisualStudioCode它会生成一个非常全面的.gitignore模板。重要提示.gitignore只对尚未被Git跟踪的文件生效。如果一个文件已经被提交过即已被跟踪那么即使后来把它加入.gitignoreGit依然会继续跟踪它的变化。这时你需要先用git rm --cached file命令将其从Git索引中移除但保留本地文件然后再提交。5.2 利用GitLens挖掘代码历史之前安装的GitLens扩展现在可以大显身手了。行内注解将鼠标悬停在任何一行代码上GitLens会显示这行代码最近是谁、在什么时候、因哪次提交而修改的。这在进行代码审查或追溯Bug来源时极其有用。提交图谱在GitLens视图或源代码管理视图的提交历史中你可以看到一个可视化的分支合并图谱清晰地展示了项目的开发脉络。文件历史在资源管理器中右键点击任何一个文件选择“GitLens: Open File History”可以单独查看这个文件的完整提交历史。比较任意版本你可以轻松地比较当前工作区与任意一次历史提交的差异或者比较任意两次历史提交之间的差异。5.3 配置VSCode的Git相关设置打开VSCode设置Ctrl,搜索“git”有很多可以优化的点Git: Autofetch设置为trueVSCode会定期在后台自动获取fetch远程仓库的更新让你能及时看到远程分支的状态变化。Git: Confirm Sync设置为false。当你点击源代码管理视图顶部的“同步更改”按钮时一个带箭头的循环图标它会一次性执行拉取然后推送。如果设置为true每次都会弹窗确认有点烦人。关闭后操作更流畅。Git: Post Commit Command可以设置为sync。这样每次本地提交后会自动执行同步拉取推送适合个人项目或习惯快速同步的开发者。对于团队项目建议保持为none手动控制推送时机。5.4 处理大文件与仓库瘦身Git不适合管理二进制大文件如图片、视频、设计稿源文件、数据集等因为它们会使得仓库体积急剧膨胀克隆和拉取速度变慢。虽然Gitee支持Git LFS大文件存储但配置稍复杂。一个更简单的实践建议是将需要版本控制的、非代码的大文件放在另一个独立的仓库或使用专门的云存储/网盘链接管理而在主代码仓库中只通过一个文本文件如assets/README.md来记录这些资源的存放地址和版本信息。这样既保持了代码仓库的轻量又能追踪资源的变化。如果你不小心将一个大文件提交并推送了后续即使删除它历史记录里依然存在仓库体积不会减小。这时需要进行Git历史重写使用git filter-branch或BFG Repo-Cleaner工具但这属于高风险操作会改变提交哈希如果仓库已被多人克隆会造成严重混乱。因此最好的办法就是一开始就不要提交不该提交的东西。6. 团队协作与Pull Request工作流当项目不止你一个人开发时一个规范的协作流程能避免很多麻烦。在Gitee上最常用的协作模式是“分支 Pull RequestPRGitee中称为‘合并请求’”。不直接在主分支上提交团队每个成员都不应该直接向main或master分支推送代码。主分支应被视为稳定、可随时部署的分支。功能分支开发每个新功能或Bug修复都从主分支拉出一个新的功能分支如feature/xxx或fix/xxx进行开发。推送分支并创建PR在本地功能分支上完成开发并提交后将其推送到Gitee。此时在Gitee的仓库页面上通常会自动出现一个“创建合并请求”的提示。点击它填写PR的标题和描述详细说明这个分支做了什么、为什么做、以及测试情况。描述越清晰审查者效率越高。代码审查其他团队成员或指定的审查者会在Gitee的PR页面上查看代码变更Diff并提出评论或修改建议。这是一个非常重要的质量保证和知识共享环节。迭代与更新如果审查中提出了修改意见你只需要在本地同一个功能分支上继续修改、提交然后再次推送到远程。PR会自动更新包含你最新的提交。你可以在PR的评论中与审查者进行讨论。合并与清理当所有审查通过并且可能需要的自动化检查如CI/CD流水线也通过后项目的维护者或有合并权限的人就可以将这个PR合并到主分支。合并后这个功能分支的使命就完成了可以在Gitee页面上或本地将其删除。在VSCode中虽然没有直接的Gitee PR创建界面但你可以安装像“GitHub Pull Requests and Issues”这样的扩展它对Gitee的API支持有限但查看和评论基本功能可用或者更简单地直接在浏览器中完成PR的创建和审查工作而VSCode专注于本地代码的编写和提交。这套流程看似繁琐但它强制了代码审查、保持了主分支的清洁、提供了清晰的变更历史是任何严肃的软件项目都应该采用的协作规范。从个人项目开始就养成这样的习惯对未来参与团队项目有莫大的好处。7. 常见问题排查与实战心得即使流程再规范也难免会遇到问题。这里分享几个我高频遇到的问题和解决方法。问题一推送被拒绝提示“non-fast-forward”现象执行git push时失败错误信息包含[rejected]和non-fast-forward。原因这意味着远程分支有你本地没有的新提交。Git为了保护这些提交不被覆盖拒绝了你的推送。解决永远不要使用git push -f强制推送来覆盖远程历史除非你百分百确定只有你一人在操作这个分支且愿意丢弃远程的更改。正确的做法是先拉取git pull。这会将远程的更改合并到你的本地分支可能会产生冲突按前面讲的方法解决冲突后再次提交然后推送。问题二拉取失败提示“有未提交的更改”现象执行git pull时失败提示你有未暂存的更改需要先提交或贮藏。原因Git不允许在有未提交的本地修改时直接合并远程更改因为这可能导致混乱。解决有两个选择提交如果当前的修改已经是一个完整的逻辑单元那就先提交它们。贮藏如果修改还没完成不想提交可以使用“贮藏”功能。在VSCode的源代码管理视图顶部点击“···”菜单选择“贮藏” - “贮藏所有更改”。这会将你所有未提交的修改暂时保存起来并恢复工作区到上一次提交的状态。然后你就可以安全地拉取了。拉取完成后再点击“···”菜单选择“贮藏” - “应用最新的贮藏”将刚才的修改恢复回来继续工作。问题三提交历史混乱想合并多次提交现象在功能开发过程中你可能有多次“WIP”工作进行中的临时提交希望在合并到主分支前将它们整理成一次或几次清晰的提交。解决使用交互式变基。这是一个高级但极其有用的功能。在VSCode中可以通过命令面板CtrlShiftP执行 “Git: Rebase Interactive…”。它会让你选择从哪次提交开始变基然后弹出一个编辑器列出你选择的提交。你可以将某些提交前面的pick改为squash或fixup将它们合并到前一个提交中。调整提交的顺序。编辑某次提交的信息。删除某次提交。 保存并关闭编辑器后Git会按照你的指令重写提交历史。警告变基会改变提交的哈希值只适用于你本地尚未推送的提交。如果已经推送重写历史会给协作者带来麻烦。个人心得善用“Fetch”我个人的工作流中“拉取”Pull用得并不多我更常用的是“获取”Fetch。点击源代码管理视图的“···”菜单选择“获取”。Fetch操作只会将远程仓库的最新信息下载到本地更新远程分支指针如origin/main但不会自动合并到你的当前工作分支。这让你可以清晰地看到远程分支领先了你多少提交然后你可以决定是现在合并通过“合并”或“变基”还是继续你的工作稍后再处理。这种工作方式让你对同步过程有更强的控制力避免了git pull可能带来的意外合并冲突。将VSCode和Gitee搭配使用本质上是在打造一个高度集成、可视化的本地开发环境。它降低了Git的使用门槛但并没有削弱其强大功能。通过图形界面完成大部分常规操作在需要精细控制时辅以命令行或高级扩展功能这种组合能让你的开发流程既流畅又强大。记住工具的目的是提升效率理解其背后的原理比如暂存区、分支、合并的原理才能在任何情况下都游刃有余。