在 Visual Studio Code 中解决 Git 合并冲突:从冲突标记到三向合并编辑器
在 Visual Studio Code 中解决 Git 合并冲突:从冲突标记到三向合并编辑器
当 Git 无法自动合并双方改动而停下时,Visual Studio Code(简称 VS Code,即 vscode-docs 仓库所服务的官方文档项目)内置的源代码管理(Source Control)能力可以帮你识别冲突文件、逐处解决冲突、审查结果并完成或取消操作。读完本文,你将掌握冲突标记的含义、Current/Incoming 两侧的判定方法、内联 CodeLens 操作、三向合并编辑器(3-way merge editor)、合并/变基/拣选/恢复暂存等场景的收尾命令,以及把 VS Code 配置为终端默认合并工具和可选的人工智能(AI)辅助解决实验功能。
理解合并冲突
合并冲突(merge conflict)发生在 Git 遇到无法自动解决的竞争性改动时。常见场景包括:
- 两个分支修改了同一文件的相同行。
- 一个分支删除了文件,而另一个分支修改了该文件。
- 两个分支在同一位置添加了不同内容。
冲突可能出现在 merge、pull、rebase、cherry-pick 或 stash 恢复(stash restore)过程中。各场景下的文件解决工具是相似的,但两侧(side)的含义和完成操作(finish)的步骤取决于具体操作。有关如何创建和管理分支以减少冲突,可参阅分支与工作树指南。
在 VS Code 中识别冲突
当发生合并冲突时,VS Code 提供多种可视化指示来帮助识别和解决。存在冲突的文件会出现在 Source Control 视图的 Merge Changes(合并更改)分区下。
编辑器冲突标记
打开含冲突的文件时,VS Code 会用以下标记高亮冲突区段:
<<<<<<< HEAD(或其他标签):标记 current(当前)一侧的开始。=======:分隔两个冲突版本。>>>>>>> branch-name(或提交标识):标记 incoming(传入)一侧的结束。
理解 Current 与 Incoming 改动
在接受任一侧之前,请阅读标签并比较内容——"Current"并不总意味着你原来的功能分支。不同操作下 Current 与 Incoming 的对应关系如下:
| 操作 | Current | Incoming |
|---|---|---|
| Merge,包括合并式 pull | 检出的目标分支 | 正被合入的分支 |
| Rebase,包括 Pull (Rebase) | 新的基线加上已重放的提交 | 你分支中 Git 当前正在重放的提交 |
| Cherry-pick | 检出的分支 | 正在应用的提交 |
| 恢复 stash | 正在恢复到的当前工作状态 | 暂存的更改(stashed changes) |
[!IMPORTANT] 在 rebase 过程中,Git 的 'ours' 与 'theirs' 角色与预期相反:'ours' 是新的基线,'theirs' 是你被重放的工作。请检查改动内容,而不是凭名称选择一侧。
CodeLens 操作
在每个冲突上方,VS Code 显示 CodeLens 操作,帮助你快速解决冲突:
- Accept Current Change(接受当前更改):只保留该冲突的 current 一侧。
- Accept Incoming Change(接受传入更改):只保留 incoming 一侧。
- Accept Both Changes(接受两者更改):依次保留两个版本。
- Compare Changes(比较更改):打开 diff 视图比较两个版本。
注意:同时接受两者并不能保证代码有效,你仍可能需要手动删除重复内容或合并逻辑。
使用内联操作解决冲突
对于简单冲突,可以直接在编辑器中通过 CodeLens 操作解决:
- 在 Source Control 视图(
kb(workbench.view.scm))的 Merge Changes 下打开文件。 - 审阅冲突区段,确认每一侧代表什么。
- 在冲突上方选择一个 CodeLens 操作:
- Accept Current Change 保留 current 一侧。
- Accept Incoming Change 保留 incoming 一侧。
- Accept Both Changes 保留两侧版本。
- 对每个冲突重复操作,然后整体检查文件是否缺失或重复代码。
- 保存文件,并在 Source Control 视图中用 +(Stage Changes,暂存更改)暂存它。
文件会从 Merge Changes 移动到 Staged Changes。解决所有文件后,完成操作。
[!TIP] 对于需要组合两侧部分改动的复杂冲突,可以手动编辑文件:删除冲突标记(
<<<<<<<、=======、>>>>>>>)并编辑内容得到预期结果。这也是 staging-commits.md 所描述的暂存工作流的自然延续——冲突文件只有在暂存后才会进入提交范围。
使用三向合并编辑器
对于更复杂的冲突,或希望并排查看所有改动时,可以使用三向合并编辑器。它提供包含三个面板的综合视图:
- Incoming(左):冲突的 incoming 一侧。
- Current(右):current 一侧。
- Result(下):将被保存的已解决文件。
侧面标签取决于进行中的操作。
打开合并编辑器
打开三向合并编辑器的方法:
- 右键单击 Source Control 视图中 Merge Changes 下的文件。
- 选择 Open in Merge Editor(在合并编辑器中打开)。或者,打开文件后在显示按钮时选择 Resolve in Merge Editor(在合并编辑器中解决)。
在合并编辑器中接受更改
使用每个冲突旁的控件选择要包含到 Result 中的改动:
- 审阅 Incoming 和 Current 面板中的改动。
- 从任一侧接受更改,或组合两侧。如果两个选择都不符合预期代码,请手动编辑结果。
- 每次选择后检查 Result 面板,利用未解决冲突计数找出仍需处理的冲突。
- 所有冲突解决后,审阅结果文件,然后选择 Complete Merge(完成合并)。
Complete Merge 会暂存该文件并关闭合并编辑器,但不会完成整个仓库操作。解决剩余文件后,再完成操作。
在合并编辑器中手动编辑
有时你需要组合两侧的部分内容,或创建一个全新的解决方案。可以直接编辑 Result 面板:
- 在 Result 面板任意位置单击放置光标。
- 按需编辑内容,组合两侧元素或编写新代码。
即使未解决冲突计数为零,也应审查最终代码——解决文本冲突并不能证明代码可运行。
备用布局
在合并编辑器中选择 More Actions(...)可切换布局或显示 base 视图。base 是 Git 比较两侧时所依据的共同版本。
Incoming、Current、Result 旁的菜单为各视图提供选项,例如与 base 比较或重置结果。
完成合并操作
首先,解决并保存每个冲突文件,然后暂存解决方案。在继续前检查暂存的 diff,并运行相关测试。
随后使用对应操作的收尾动作:
| 操作 | 如何完成 |
|---|---|
| Merge,包括合并式 pull | 在 Source Control 视图输入合并提交信息并选择 Commit。 |
| Rebase,包括 Pull (Rebase) | 在仓库的集成终端中运行 git rebase --continue。Git 可能停在另一个冲突提交处,解决后继续,直到 rebase 完成。 |
| Cherry-pick | 在仓库的集成终端中运行 git cherry-pick --continue。若提交序列遇到更多冲突则重复执行。 |
| 恢复 stash | 审阅恢复的文件并在就绪后提交。stash 冲突不要求合并提交。 |
VS Code 的提交动作也会在暂存解决方案后继续进行中的 rebase。如果不确定哪个操作处于活动状态,请在仓库终端中运行 git status,查看 Git 的当前状态和下一步动作。
合并、变基或拣选完成后,检查 git status 不再报告该操作正在进行。完成后可在 Source Control Graph 中审阅历史,再考虑推送提交与团队共享。这一流程在 overview.md 的通用工作流中也有对应描述:拉取被拒绝或 sync 未完成时,往往需要先完成冲突解决再继续推送。
取消操作
若想放弃操作而不解决冲突,打开命令面板(kb(workbench.action.showCommands))并选择对应命令:
- Git: Abort Merge(中止合并):用于 merge。
- Git: Abort Rebase(中止变基):用于 rebase。
- Git: Abort Cherry Pick(中止拣选):用于 cherry-pick。
[!CAUTION] 中止会移除该操作的冲突解决成果。请先复制你想保留的任何编辑。Git 会尝试恢复操作前的状态,但可能无法重建操作前已存在的未提交更改。
这些 abort 命令不会撤销 stash 恢复。对于暂存的更改,请在使用撤销或丢弃操作前检查工作文件和 stash 列表。
使用 AI 解决冲突(实验性)
[!NOTE] AI 辅助冲突解决是实验性功能,需要 Copilot 访问权限。使用前请先设置 Copilot。
VS Code 可以使用 AI 自动帮助解决合并冲突。该功能分析冲突两侧的版本并提出解决方案:
- 在编辑器中打开含冲突的文件。
- 选择编辑器顶部的 Resolve Merge Conflict with AI(使用 AI 解决合并冲突)按钮。
- 在聊天视图(Chat view)和编辑器中审阅 AI 的分析与建议编辑。
- 接受解决方案或手动调整,然后测试结果。
- 暂存已解决的文件并完成操作。
AI 会考虑合并基线(两个分支的共同祖先)以及各分支的改动,生成试图保留双方改动意图的解决方案。
将 VS Code 配置为默认合并工具
要从终端工作流解决冲突,可将 Git 配置为使用 VS Code 三向合并编辑器。首先确保 code 命令可用。
在 Bash 兼容终端中运行以下命令:
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait --merge "$REMOTE" "$LOCAL" "$BASE" "$MERGED"'
Git 操作报告冲突后,运行 git mergetool 启动编辑器。注意 Git 不会在冲突发生时自动启动它。
在同一终端配置 diff 工具:
git config --global diff.tool vscode
git config --global difftool.vscode.cmd 'code --wait --diff "$LOCAL" "$REMOTE"'
运行 git difftool 用该工具比较更改。这里 $REMOTE 对应传入侧、$LOCAL 对应当前侧、$BASE 是共同基线、$MERGED 是要写入的结果文件——与三向合并编辑器的 Incoming / Current / base / Result 面板一一对应,便于理解终端参数的含义。
解决冲突后的检查清单
无论采用哪种解决方式,建议完成以下收尾检查(与 staging-commits.md 的提交工作流衔接):
- 每个冲突文件都已保存并暂存(文件移出 Merge Changes 分区)。
- 在 diff 编辑器中审阅暂存内容,确认无重复或遗漏代码。
- 运行相关测试,确认冲突解决没有破坏功能。
- 使用对应收尾动作完成操作,或在不需保留工作时取消操作。
- 用
git status确认没有遗留的进行中操作;若操作反复失败,可参考源代码管理故障排查,尤其是 Git Output 窗口中的错误信息。


