文本差异对比

概述

文本差异对比工具提供了一个专业且直观的文件对比环境，基于 Monaco Editor 的差异对比引擎，让你能够快速发现两个文件或两段文本之间的细微差异。无论是代码审查、配置文件比对，还是文档版本对比，它都能胜任。

核心功能

• 可视化差异引擎：基于 Monaco Diff Editor，支持逐行对比与字符级差异高亮，差异点清晰标注增删改
• 智能文件拖放：拖入一个文件自动填充空侧，拖入两个文件自动分配到左右两侧，减少操作步骤
• 并排/内联双模式：支持并排对比和内联统一视图两种布局，适应不同的审阅习惯
• 差异导航与计数：自动统计差异总数，支持上一处/下一处快速跳转，大型文件也不迷路
• Unified Diff 补丁导出：一键生成标准统一 Diff 格式（.patch）补丁文件，与 Git 等版本控制工具无缝对接

快速上手

首次使用 4 步走

第一步：打开工具

在左侧工具列表中找到 文本差异对比，点击进入。你将看到一个左右分区界面，顶部是功能丰富的工具栏，中间是一个空白对比编辑器。

TODO: 截图 - 工具整体界面，标注工具栏、左右编辑器区域和文件名显示区域

第二步：准备对比内容

有四种方式向编辑器填入内容：

方式	操作说明
直接键入	在左右编辑器中直接输入或粘贴文本
拖拽文件	将一个文件拖到编辑器区域自动分配到空侧，或同时拖入两个文件自动分配
从文件打开	点击工具栏的 文件 → 打开左侧 / 打开右侧 选择本地文件
从剪贴板粘贴	点击工具栏的 剪贴板 → 粘贴到左侧 / 粘贴到右侧

💡 最快捷的方式：同时选中两个文件，一起拖入编辑器区域，工具会自动将它们分配到左右两侧，并自动识别语言类型提供语法高亮。

TODO: 截图 - 拖拽两个文件到编辑器区域的效果，标注文件名显示区域显示的左右文件名

第三步：查看差异

内容填入后，Monaco Diff Editor 会自动开始比对。差异点会以不同颜色高亮显示：

• 红色背景：表示左侧独有（删除的内容）
• 绿色背景：表示右侧独有（新增的内容）
• 左侧行号区域的红色/绿色标记：快速定位差异行

右上角的差异导航区域会显示 1 / 5 这样的计数，表明共有 5 处差异，当前在第 1 处。

TODO: 截图 - 对比结果，标注红色（删除）、绿色（新增）和差异导航计数器

第四步：导航与导出

使用工具栏的 上一处 / 下一处 按钮在各个差异点之间跳转，快速审阅每一处变更。审阅完成后：

• 复制补丁：点击 剪贴板 → 复制补丁，将标准 Unified Diff 格式复制到剪贴板
• 导出 .patch：点击 文件 → 导出 .patch，保存为补丁文件供版本控制使用

TODO: 截图 - 工具栏的差异导航按钮和文件导出菜单

功能详解

工具栏

工具栏分为多个功能区，从上到下依次是语言选择、布局切换、比对选项、差异导航和操作按钮。

语言选择

工具栏左侧是一个 语言选择下拉框（默认自动检测）。当通过文件打开或拖拽加载文件时，系统会根据文件后缀自动推断语言类型（如 .ts 对应 TypeScript、.py 对应 Python），你也可以手动切换以改变语法高亮。

支持的语言包括：纯文本、JavaScript、TypeScript、JSON、HTML、CSS、Python、Java、C++、Markdown。

TODO: 截图 - 语言选择下拉框展开状态

布局切换：并排 vs 内联

工具栏提供两个布局模式的切换按钮：

模式	按钮	说明
并排（默认）	并排 按钮	左侧显示原文本，右侧显示修改后文本，差异点高亮对应显示
内联	内联 按钮	所有内容显示在同一区域，差异点以行内标记形式呈现

内联模式更适合读不太长的内容，可以纵向滚动查看整体变更脉络而不需要左右对照。

TODO: 截图 - 同一份内容分别在并排和内联模式下的效果对比

比对选项

选项	说明
忽略行尾空白	默认开启。忽略每行末尾的空白字符差异（空格、制表符），专注于代码逻辑的变更
只看变更	开启后，差异化区域高亮着色消失，右侧的变更概览条隐藏，适合关注无差异状态的终版结果
自动换行	开启后长行自动折行显示，无需水平滚动
忽略大小写	⚠️ 实验性功能。开启后差异计数会忽略大小写差异，但不改变可视高亮的差异区域

TODO: 截图 - 工具栏的四个比对选项复选框

差异导航

工具栏中间区域提供差异导航控件：

控件	说明
上一处 按钮	跳转到上一处差异，编辑器自动滚动到对应位置
下一处 按钮	跳转到下一处差异
差异计数	显示 当前索引 / 总数（如 3 / 12），无差异时显示 无差异

当差异总数为 0 时，导航按钮会自动禁用（灰色不可点击）。

TODO: 截图 - 差异导航按钮组和计数器

文件操作菜单

点击 文件 按钮展开下拉菜单：

操作	说明
打开左侧	系统文件对话框中选择文件，加载到左侧编辑器
打开右侧	同上，加载到右侧编辑器
保存左侧	将左侧编辑器中修改后的内容保存到文件
保存右侧	将右侧编辑器中修改后的内容保存到文件
保存两侧	同时保存左右两侧
导出 .patch	生成 Unified Diff 补丁并保存为 .patch 文件（默认文件名：文件名A_vs_文件名B.patch）

TODO: 截图 - 文件下拉菜单展开

剪贴板操作菜单

点击 剪贴板 按钮展开下拉菜单：

操作	说明
复制左侧	将左侧编辑器内容复制到系统剪贴板
复制右侧	将右侧编辑器内容复制到系统剪贴板
复制补丁	将生成的 Unified Diff 补丁复制到剪贴板（格式与导出相同但不保存文件）
粘贴到左侧	将系统剪贴板中的文本粘贴到左侧编辑器
粘贴到右侧	将系统剪贴板中的文本粘贴到右侧编辑器

TODO: 截图 - 剪贴板下拉菜单展开

清空与交换

操作	说明
清空 下拉	可选择清空左侧、右侧或两侧全部内容
交换 按钮	一键交换左右两侧的内容和文件名，快速切换对比方向（如交换原文本和修改后文本的位置）

TODO: 截图 - 清空下拉菜单和交换按钮

文件名显示区域

编辑器上方有一个文件名显示栏，左右各占一半。当通过文件加载时，会显示对应的文件名和文件图标；未加载文件时显示占位文字（左侧：未命名 / 右侧：未命名）。

在编辑过程中直接修改编辑器内容不会影响文件名显示，保存文件后会更新文件名。

TODO: 截图 - 文件名显示区域，左侧显示 "app.ts"，右侧显示 "app_v2.ts"

差异编辑器

编辑器区域是整个工具的核心，它使用 RichCodeEditor 组件的 Monaco Editor Diff 模式。关键特性：

• 左侧编辑器可编辑：你可以直接在左侧（原文本）编辑器中修改内容，对比结果会实时更新。这在快速尝试不同修改方案时非常有用。
• 自动语言识别：通过文件后缀自动推断语法高亮语言（如 .ts → TypeScript）
• 大文件警告：加载超过 10MB 的文件时会提示"文件较大，可能影响性能"
• 二进制文件检测：如果拖入或打开的是一个二进制文件，工具会自动检测并拒绝加载，提示"不支持二进制文件"

左侧拖放区域 / 右侧拖放区域

编辑器区域左右两侧各有一个透明的文件拖放感应区。当你拖拽文件到对应位置时，感应区会浮现蓝色虚线边框和提示文字，松开后文件自动加载到对应侧的编辑器。

💡 智能分配逻辑：

• 拖入 两个文件：自动分配到左右两侧
• 拖入 一个文件：如果有一侧为空，自动填充到空侧；如果两侧都有内容，覆盖鼠标指向的那一侧

TODO: 截图 - 拖拽文件到左侧区域时出现的蓝色虚线边框和"拖放文件到左侧"提示

高级用法

代码审查工作流

场景：你在 Code Review 时需要对两个版本的代码进行逐行对比。

1. 同时选中 main.ts 和 feature.ts 拖入编辑器
2. 使用 下一处 按钮逐项审查差异
3. 如果发现某处修改不合理，直接在左侧编辑器中修改回原样
4. 审查完成后，点击 文件 → 保存左侧 将修正后的文件保存
5. 如需记录变更历史，点击 文件 → 导出 .patch 保存补丁文件

合并冲突手动解析

场景：合并分支时出现冲突，可以用文本差异对比辅助理解冲突内容。

1. 在 Git 中查看冲突文件后，将"我们"的版本和"他们"的版本分别复制到左右编辑器
2. 开启 忽略行尾空白 避免无关差异干扰
3. 逐处审查差异点，确定哪些变更需要保留
4. 在左侧或右侧编辑器中直接编辑合并结果
5. 存入合并后的文件

使用补丁文件与 Git 集成

生成的 .patch 文件是标准 Unified Diff 格式，可以与 Git 搭配使用：

# 应用补丁（在 Git 仓库中）
git apply your-diff.patch

# 查看补丁预览
git apply --stat your-diff.patch

这在以下场景特别有用：

• 你想对比两个文件后，将差异以补丁形式分享给团队
• 需要在不直接提交代码的情况下，将变更应用到其他分支

快捷键（Monaco Editor 内置）

由于编辑器基于 Monaco Editor，你可以使用许多熟悉的快捷键：

快捷键	功能
Ctrl+F	在当前编辑器中搜索
Ctrl+H	替换文本
Ctrl+Z	撤销修改
Ctrl+Shift+Z	重做修改
Alt+↑/↓	上下移动行

常见问题

Q：为什么拖拽文件后没有自动对比？

检查一下文件是否成功加载——观察文件名显示区域是否出现了文件名，以及编辑器中是否显示了文件内容。如果文件名区域显示"未命名"，说明文件没有成功加载。可能的原因：

• 文件是二进制类型（如图片、压缩包），工具会自动拒绝并提示"不支持二进制文件"
• 文件路径包含特殊字符或权限不足，请尝试使用 文件 → 打开左侧/右侧 通过系统对话框加载

Q：为何差异计数和实际看到的差异颜色数量不一致？

差异计数依赖于 Monaco Editor 的 getLineChanges() 接口，它按连续的差异行块计数。一个"差异"可能包含多行增删改。另外，忽略大小写选项（实验性功能）会影响计数但不影响可视高亮的差异区域，所以计数可能低于实际可视的差异块。

Q：左侧编辑器修改了内容，差异会实时更新吗？

会的。originalEditable: true 配置使左侧（原文本）编辑器可直接编辑，每次输入后 Monaco Editor 会重新计算差异，差异导航计数也会同步更新。这让你可以在看到差异后直接在原文本上修改，快速尝试不同方案。

Q：导出的 .patch 文件怎么用？

导出的补丁是标准 Unified Diff 格式，包含文件名、上下文行和差异标记。你可以：

• 用文本编辑器打开查看内容
• 通过 git apply 命令应用到 Git 仓库
• 发送给同事供 Code Review

工具默认的上下文行数为 3 行（标准 Git Diff 默认值），补丁头部包含原文件名和新文件名信息。

Q：对比大文件（超过 10MB）时卡顿怎么办？

加载超过 10MB 的文件时，工具会提示"文件较大，可能影响性能"。此时建议：

• 关闭 只看变更 和 自动换行 选项，减少渲染开销
• 使用 内联模式 替代并排模式，节省编辑器的渲染资源
• 如果文件大小超过 100MB，建议使用专业的文件对比工具（如 Beyond Compare）
• 只对比文件中有意义的部分，而非整个文件

Q：两侧内容完全相同但导航显示有差异？

检查 忽略行尾空白 选项是否关闭。如果关闭，行尾多余的空白字符（空格、制表符）会被视为差异。建议大多数情况下保持此选项开启。另外，Windows 换行符（CRLF）和 Unix 换行符（LF）的差异也可能导致显示差异——工具目前不会自动忽略换行符差异。