不知道你有没有过这种经历打开 VS Code 准备提交代码侧边栏的“源代码管理”图标上亮着一个数字点进去全是一堆 M/U 标识却不知道该按哪个按钮或者好不容易把代码 push 上去了第二天同事告诉你他拉下来的版本跟你推上去的冲突了你看着满屏的“ HEAD”一头雾水。这套东西我第一次碰是在 Windows 上当时连 Git 是什么都说不清楚全靠搜索“git 安装教程”“vscode 提交代码到 git 远程仓库”这类关键词硬啃。折腾了整整两个晚上才把从创建本地仓库到推送到远程仓库的整条链路跑通。后来用熟了才发现很多看起来吓人的报错其实翻来覆去就是那几个原因。这篇不是我抄官方文档是我把自己在 VS Code 里用 Git 做完整流程的经验串一遍环境准备、创建本地仓库、关联远程仓库、推送、克隆、拉取、解决冲突每个环节我都会把为什么这么做讲清楚并且标出我踩过的坑。无论你是刚接触 Git 的前端、刚开始用 VS Code 写脚本的新人还是想系统理顺版本控制流程的开发者这篇都能给你一条可以直接照着走的路。1. 环境准备先把 Git 装好再让 VS Code 连通很多人以为 VS Code 自带 Git 功能就能直接用其实它只是“壳”真正干活的是你装在系统里的 Git 程序。VS Code 的源代码管理面板会去调用系统 PATH 里的 git.exe如果没装 Git 或者装在奇怪的位置就会看到那个经典报错“无法将‘git’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。1.1 Windows 下安装 Git 的细节下载地址不多说网上搜 Git 官网就能找到 Windows 版本。装的时候有几个选项值得注意不是一路 Next 就完事。第一是安装路径。我最初图省事直接装在 C 盘默认路径后来发现同学装在带空格的路径下VS Code 有时识别不到位。建议装一个纯净路径比如D:\Git尽量避免中文和特殊字符路径。第二是 PATH 环境变量那块。安装过程中会让选择调整 PATH选“Git from the command line and also from 3rd-party software”那项这样不仅 Git Bash 能用VS Code 的终端也能直接敲 git 命令。第三是换行符转换那步。Windows 默认是 CRLFLinux 和 Mac 默认是 LFGit 安装时一般建议选“Checkout Windows-style, commit Unix-style line endings”。我一直保持这个默认设置跨平台协作时踩的坑会少很多。装完之后在 VS Code 里打开任意终端输入git --version能输出版本号说明 Git 已装好。如果提示找不到命令去系统环境变量检查一下 Path 里有没有 Git 的 bin 目录。1.2 配置用户名和邮箱提交记录的“署名”这一步很多人会跳过但它是第一次 commit 时必定报错的原因。执行完下面两行git config --global user.name 你的名字 git config --global user.email 你的邮箱--global 表示全局生效这组配置会写在用户主目录下的 .gitconfig 文件里。不配置的话Git 不知道你的提交该署名给谁会直接阻止提交。还有个容易忽略的点提交记录上的邮箱最好和你远程仓库账号绑定的邮箱一致。比如你在 Gitee 或 GitHub 上用 163 邮箱注册的账号本地提交邮箱也用同一个这样提交记录能正确关联到你的账户不然头像和统计是挂不上的。1.3 SSH 密钥配置关联远程仓库的钥匙连接远程仓库有 HTTPS 和 SSH 两种方式。HTTPS 每次推送都可能要输账号密码虽然可以配置记住凭据SSH 配置好之后免密推送更方便。这也是“git 配置 gitee 密钥”这个搜索词出现频率很高的原因。在终端里执行ssh-keygen -t rsa -b 4096 -C 你的邮箱生成过程中会询问保存路径和密码短语直接回车走默认路径就行。密码短语如果设置了每次推送时还得输入一次个人用的话建议留空纯回车跳过。生成完会得到两个文件私钥id_rsa和公钥id_rsa.pub。私钥留在自己电脑上千万别泄露公钥要复制到远程仓库平台。在终端里查看公钥cat ~/.ssh/id_rsa.pub把输出的整段内容复制打开 Gitee 或 GitHub 的设置页面找到“SSH 公钥”配置项粘贴保存。之后再用 SSH 地址克隆或推送就不会弹密码输入框了。1.4 VS Code 侧的准备VS Code 打开“设置”(快捷键Ctrl ,)搜索“git.path”可以指定 git.exe 的绝对路径。大多数情况下不手动设置也能自动识别只有 Git 装在自定义路径且识别失败时才需要干预。另外VS Code 左下角状态栏有个小图标绕圈圈时表示在获取远程更新。你可以自定义它的显示文字但一般保持默认就行。2. 创建本地仓库并关联远程仓库第一次推送的完整走位第一次推送到远程仓库是新手最容易卡住的地方。我把这个过程拆成四步每步都说明白在干什么。2.1 在 VS Code 中初始化本地仓库打开你准备放项目的文件夹比如写了一半的 Python 脚本项目左侧点开源代码管理图标顶部会有个“初始化仓库”按钮。点击后在确认框里选择该文件夹Git 就会在项目根目录下生成一个隐藏的.git文件夹。这里我要强调一个概念.git文件夹就是 Git 的灵魂里面记录了全部提交历史、分支引用、配置信息。如果哪天误删了.git整个项目的版本历史就灰飞烟灭了剩下的只是一堆普通文件。所以初始化之前先考虑清楚哪些文件不应进 Git。比如 Node.js 项目里的node_modules、Python 的缓存目录、IDE 配置、机密文件等都需要靠.gitignore文件排除掉。VS Code 里即使你在“初始化仓库”之后没有手动创建.gitignoreGit 也会帮你把所有文件都纳入跟踪。更好的做法是新建项目时就先加一个.gitignore然后右键重要的文件选“添加到 .gitignore”。我通常这样操作在 VS Code 的扩展市场里装一个 GitLens它会在源代码管理面板上方显示 untracked 文件数量还会注明哪些文件已被忽略。每次新项目开始时先写.gitignore再写代码这个好习惯能在后期省不少心。2.2 暂存与提交理解“三段式”状态Git 对文件的管理可以简化成三个区域工作区你看到的文件、暂存区准备提交的内容、本地仓库已提交的历史。在 VS Code 的源代码管理面板里改动文件会以 Mmodified或 Uuntracked开头显示。Uuntracked从未被 Git 跟踪过的新文件Mmodified已被跟踪但内容有改动Ddeleted已被删除的文件要把改动加入暂存区在文件上点那个加号图标。全部加入的话点标题栏的“暂存全部更改”。然后在上面的消息框里写提交说明比如“完成登录接口初版”点击“提交”按钮。暂存区这个概念用生活类比就是提交相当于把一批文件打包寄出去暂存区就像一个“待发件箱”你先把要寄的东西放进去检查无误后再点发送。这样你就可以把一次复杂的修改拆成多个逻辑清晰的小提交。第一次提交之前最好先创建.gitignore。比如我的 Python 项目通常会这样写venv/ __pycache__/ *.pyc .DS_StoreVS Code 还可以在源代码管理面板的右键菜单里直接选择“从列表中删除文件仅工作区”这样就不会误提交缓存文件。2.3 远程仓库的创建与 SSH 地址获取先去 Gitee 或 GitHub 新建一个空仓库注意几点仓库名要和本地项目名匹配方便记忆可见性选私有还是公开取决于你是否想让别人能看到初始化时建议不要勾选“生成 README 文件”免得本地和远程历史不匹配出现合并问题创建完之后仓库页面会给出两个地址一个 HTTPS一个 SSH。在 VS Code 终端里执行git remote add origin gitgitee.com:你的用户名/仓库名.git这条命令的作用是给远程仓库起一个别名“origin”。添加到 VS Code 保管的远程仓库列表后后续推送就不需要再输完整地址了。如果发现地址写错了可以用git remote set-url origin 新地址或者干脆删除重加git remote remove origin2.4 推送本地分支到远程仓库这是整个流程里年轻人最容易受挫的一步。执行git push -u origin main-u全称是--set-upstream意思是将本地分支与远程分支建立关联。第一次推送时必须带上它之后在本地 main 分支上直接git push即可Git 知道推送到哪里。如果你的默认分支不叫 main而叫 master取决于 Git 初始化时的设置把上面的 main 换成 master 即可。怎么确认当前分支在 VS Code 状态栏左下角会显示当前分支名或者在终端里输入git branch --show-current这一步报错常见的有两种第一种是“fatal: remote origin already exists.”。说明你之前已经添加过远程仓库了用git remote set-url覆盖即可。第二种是“error: failed to push some refs to ...”这是远程仓库和本地仓库历史不一致。远程仓库里有 README而本地仓库没有Git 怕覆盖掉远程的提交历史就拒绝了推送。解决方案是执行git pull origin main --allow-unrelated-histories把远程的历史和本地历史合并起来。不过更本质的解法是创建远程仓库时不生成任何初始化文件从源头避免这个问题。推送成功后在远程仓库页面刷新就能看到你的代码上线了。那一刻的成就感我至今记得。3. 克隆与拉取进入团队协作的节奏单人开发时“创建-推送”这套基本够用但一旦进入团队协作克隆和拉取就成了日常动作。这两件事看起来简单细节还是挺多的。3.1 克隆远程仓库到本地克隆的场景通常是两种新机子上拉取已有项目、加入团队后第一次获取代码。在 VS Code 里最简单的方式是CtrlShiftP打开命令面板输入“Git: Clone”粘贴远程仓库的 SSH 地址选择保存的本地目录弹窗提示是否打开克隆的仓库选择“打开”。用 SSH 地址克隆的前提是电脑上已经配置好了 SSH 密钥。如果你还没配置或者当前机器是第一台新电脑直接在这台机器上重新执行生成密钥、添加公钥的流程即可。克隆完之后默认会处在一个主分支通常叫 main上。不要直接在 main 分支上开发养成新建分支的好习惯git checkout -b feature/login这个命令会从当前分支创建并切换到一个新分支 feature/login。团队协作时每个人在独立分支上开发合到主分支之前先做代码评审。3.2 拉取Pull与获取Fetch到底有什么区别这个算是高频困惑了。打个比方Fetch 是“你去看一下群里有没有新消息”Pull 是“有新消息就顺便把它下载并合并到你本地的工作区”。具体来说git fetch只把远程仓库的最新提交记录拉下来但不会自动合并到你当前分支工作区文件不会有变化。你可以在 VS Code 的源代码管理面板里看到远程分支的最新状态再决定要不要合并。git pull等价于git fetch git merge origin/当前分支直接更新工作区文件。日常开发中如果你长期在分支上工作我建议先git fetch查看远程分支领先了多少再决定是否需要合并或重新基于最新代码变基。如果直接git pull可能出现“文件被自动合并了但我还没准备好”的意外尤其是正在写临时代码时。在 VS Code 里源代码管理面板顶部有一条分支图标点开会看到“拉取”“推送”“同步更改”等选项。点击“拉取”就是执行git pull。你还可以在设置里开启“自动拉取”让 VS Code 在检测到远程更新时自动 fetch能减少手动操作。3.3 分支切换与提交的联动关系很多人刚开始容易犯一个错误在 A 分支写的代码没提交直接切到 B 分支发现自己新写的文件全“消失”了吓出一身冷汗。这是 Git 的一个保护机制未提交的变更会跟着工作区走但切换分支后工作区中的未跟踪文件依然躺在那里已修改但未提交的文件会尝试带到新分支。如果两个分支对同一文件的修改冲突Git 会拒绝切换并提示你先处理变更。所以在分支切换前先看一眼源代码管理面板里有没有未提交的变更。如果有要么先提交到当前分支要么用git stash暂存起来切换之后再git stash pop恢复。git stash是我非常推荐的一个命令git stash git checkout -b feature/xxx git stash pop相当于把散落在桌面上的工具收进抽屉切换完场景再拿出来接着用。3.4 拉取时的 Fast-forward 和 Merge 提示有时候执行git pull会弹出编辑器让你写合并信息原因是远程和本地各自有新的提交Git 需要做一次真正的合并默认会调用你配置的编辑器生成提交信息。VS Code 本身可以作为 Git 编辑器在设置里搜“git.editor”绑定到 VS Code 即可这样弹出的就是一个可视化窗口写个“merge remote-tracking branch”就够。不想每次都经历这种弹窗可以考虑用git pull --rebase。Rebase 能把本地的提交整齐地放到远程提交之后历史是一条直线看起来更清爽。不过涉及到自己正在开发并且还没推送到远程的分支时用 rebase 很安全如果该分支已经推送过且别人也在用就别用 rebase。4. 解决冲突从看到红色提示到理清头绪终于到了避不开的重头戏冲突。我以前看到满屏的“ HEAD”就发怵后来搞明白冲突的本质后处理起来就从容多了。4.1 冲突是怎么产生的冲突说到底就是“两方改了同一个地方Git 不知道听谁的”。典型的场景是分支 A 和分支 B 都从同一条 main 分支分出来两边都修改了login.js里第 50 行。A 分支先合入 mainB 分支提交后再尝试合入 mainGit 在自动合并的时候发现第 50 行同时被改过且改的内容不一致无法自动决定保留哪个版本于是把冲突标记写进文件等待人工决策。在 VS Code 的源代码管理面板里冲突文件会显示字母 “C” 或者“冲突”标记打开文件后可以看到冲突区段 HEAD 当前分支的代码 合并进来的分支的代码 feature/login HEAD到之间的是当前分支正在合入到的分支的代码到 feature/login之间的是被合并分支的代码。4.2 VS Code 里的冲突解决流程可视化总比盲猜好VS Code 的源代码管理面板对冲突文件提供了“接受当前更改”“接受传入更改”“接受两者更改”三个快捷操作还会在你打开冲突文件时于行号附近显示一个蓝色“可编辑冲突区段”的按钮点击后会出现“Resolve”菜单选项。我的实际操作习惯是这样的先看 HEAD和 分支名两版代码各自是什么。通常我不直接点“接受当前更改”或“接受传入更改”而是先理解两端代码的意图因为冲突很可能不是简单的二选一而是需要两段逻辑共存。如果是简单的语法叠加比如两个模块都新增了 import 语句而位置撞了直接“接受两者更改”然后手动清理重复行。如果两段代码实现的是同一功能但思路不同比如一个用循环、一个用 map这时候不能只选一边就完事而是要和同事确认哪边更合理或者把两边的逻辑融合成第三种写法。改完后把 HEAD、、这些标记行全部删掉因为 Git 是靠这些标记识别冲突的任何残留都会被视为错误。处理完之后文件行号旁的红点变成对勾意味着该文件的冲突已解决。4.3 解决冲突后的提交与推送这是另一个容易出错的地方。你以为删掉标记就算解决冲突了但 VS Code 的源代码管理面板中该文件依然显示为冲突状态并且不会出现在暂存区。你需要对它再次“暂存”告诉 Git 这个文件已经处理完成。冲突文件的正确节奏是编辑文件解决代码内容点击文件右侧的加号暂存或者右键选择“标记为已解决”所有冲突文件都处理完后在提交消息框写清合并信息比如“合并 feature/login 到 main”点击“提交”完成合并提交最后推送到远程git push如果没有暂存直接提交Git 会提示“You have unmerged paths.”意思是还有冲突没解决完这时候只需要回头把冲突文件的暂存操作补上即可。4.4 如何尽量避免冲突说实话冲突完全避免不太可能但通过一些习惯可以显著减少。第一小步提交。每次改动范围控制在单一职责内提交越频繁每次合并引入冲突的面就越小。第二分支主干保持新鲜。你自己开发分支时定期从最新的主分支拉取更新fetch merge 或 rebase不要一个分支闷头写两周。你的分支越旧合并时的冲突概率越大。第三和同事明确分工。同一文件同一区域内不要两个人同时大改哪怕技术上能合并语义上也容易打架。第四开发前先创建分支不要大家都挤在 main 上改。在各自分支上开发至少在合入时 Git 还能帮忙自动合并大部分内容全挤在一个分支上每次 push 都要担惊受怕直接冲突。4.5 我在项目里实际遇到过一次的样子有一次和同事同时改同一个 Vue 页面的样式区域我改了按钮组的 flex 布局他改了间距变量。我 push 完之后同事 pull 下来直接爆出冲突。他截图给我看满屏的标记。我当时就用 VS Code 打开点击“接受传入更改”我的改动之后检查了一遍他的间距变量是否受影响发现他的单位换算在另一个区域完全没被我的 flex 改动波及于是保留我的版本并删掉标记然后他提交推送上去了。那次之后我就总结出一个点冲突不可怕可怕的是不看上下文就盲目选一边。只要每次冲突解决时花两分钟读一下两端代码的逻辑基本不会出大乱子。5. 几条让我少走弯路的细节建议这些不算什么高深技巧但都是实打实让我少踩坑的习惯随便挑一两条做起来都会比之前顺畅很多。5.1 提交信息不要乱写我见过不少人提交信息写“update”“修改”“test”等到项目三个月后回溯问题完全不知道某些改动是干嘛的。我自己的习惯是提交信息第一行用祈使句概括动作比如“修复登录时密码为空导致的空指针”如果改动较多加一个简短详情段落说明改动范围。VS Code 的提交框上方其实支持多行输入写完第一行后按CtrlEnter提交。或者用命令面板里的“Git: Commit (Staged)”也能选。5.2 善用“源代码管理”面板的右键菜单VS Code 源代码管理面板的右键菜单藏了不少实用操作“打开文件”快速定位改动位置“查看更改”以 diff 视图方式比较新旧版本“放弃更改”恢复到上次提交的状态“复制提交哈希”省去手动复制哈希值的麻烦“创建标签”给重要版本打 tag我强烈建议你把“放弃更改”这个操作记牢如果发现自己把代码改成了一团乱麻与其手动撤销不如直接放弃该文件的更改回到最近一次提交状态。当然这个操作会丢失你的改动用时需谨慎。5.3 远程仓库名 origin 是可以有多个的很多人以为一个项目只能关联一个远程仓库地址其实可以加多个。比如你同时需要推到 Gitee 和 GitHubgit remote add origin gitgitee.com:你的用户名/仓库名.git git remote add github gitgithub.com:你的用户名/仓库名.git推送时分别git push origin main和git push github main或者一次推到全部远程仓库git remote set-url origin --push 地址1 地址2这个功能在开源项目需要镜像备份或内网外网同步时相当有用。5.4 关于 SSH key 与 HTTPS 凭据的选择如果你在 Windows 上配置了 HTTPS 方式Git 会默认启动“凭据管理器”第一次输入账号密码后缓存下来之后免密。这对只用一台电脑、不换机器的用户来说也够用。但遇到一台机器管理多个平台账号比如一个 Gitee 一个 GitHub时SSH 方式更灵活通过~/.ssh/config配置不同的私钥对应不同平台。我自己的习惯是工作项目用 SSH临时 clone 公开仓库用 HTTPS因为临时 clone 不需要配置账户公钥直接拷贝 HTTPS 地址就能拉下来等需要 push 时才走 SSH。5.5 新机子的第一次部署顺序换电脑之后最快恢复到开发状态的顺序是安装 Git生成 SSH 密钥并在远程平台添加公钥在 VS Code 里CtrlShiftP执行 Git: Clone把项目仓库克隆下来安装对应语言的扩展插件恢复开发环境整个过程不超过十分钟。先配置 SSH 再 Clone能避免克隆时要求输账号密码或报权限错误。写在最后的小体会我一开始学 Git 的时候也犯过不少迷糊最典型的就是把本地仓库和远程仓库之间的关系搞拧结果 push 到一半发现有十万八千里远的合并历史。后来慢慢养成“每次操作前想清楚三个问题当前在哪个分支本地要提交什么远程是什么状态”的习惯之后基本上在 VS Code 里玩 Git 很少出岔子。如果你刚接触这套东西别急着背命令先在 VS Code 的可视化界面里点出几次感觉再用终端跑一遍领会命令和界面按钮的对应关系。等这些东西变成肌肉记忆就可以尝试更进阶的 rebase、cherry-pick、stash 之类了。Git 这东西说到底就是个保存和合并代码的工具多踩几次坑自然就熟了。