用 Python 做一个简单的文本对比工具

在日常工作里，经常会遇到这样的需求：有一份标准文本，还有一份需要检查的文本，希望快速找出哪里写错了、哪里多了、哪里少了。

这个小工具就是为这个场景准备的。它使用 Python 读取两份 .txt 文本文件，逐行对比内容，并把差异标注到一个新的结果文件中。

工具文件说明

这个工具文件夹里主要有 4 个文件：

文本对比样本.txt
需要对比的文本.txt
标注出来的错误文本.txt
对比文档脚本.py

各文件作用如下：

文件名	作用
文本对比样本.txt	放标准文本，也就是正确版本
需要对比的文本.txt	放需要检查的文本
标注出来的错误文本.txt	保存脚本生成的对比结果
对比文档脚本.py	Python 脚本，负责读取、比较、输出

日常使用时，只需要修改前两个 .txt 文件，然后运行 Python 脚本即可。

使用方法

先把标准内容粘贴到：

文本对比样本.txt

再把需要检查的内容粘贴到：

需要对比的文本.txt

保存文件后，在终端进入工具所在文件夹，执行：

python3 对比文档脚本.py

如果是 Windows 电脑，可能需要使用：

py -3 对比文档脚本.py

或者：

python 对比文档脚本.py

运行完成后，打开：

标注出来的错误文本.txt

就能看到生成的对比结果。

输出结果示例

如果某一处文字写错了，结果中会出现：

【错误:错字｜应为:正确字】

如果多写了内容，会出现：

【多余:某些文字】

如果少写了内容，会出现：

【缺少:某些文字】

如果两份文本完全一致，则会显示：

未发现差异。

脚本整体思路

这个 Python 脚本的处理流程可以分成 5 步：

1. 确定默认文件路径
2. 读取标准文本和待检查文本
3. 按行拆分两份文本
4. 逐行比较差异
5. 把标注结果写入输出文件

核心逻辑并不复杂，但它用到了几个很实用的 Python 标准库。

Python 知识点 1：pathlib 处理文件路径

脚本中使用了：

from pathlib import Path

Path 是 Python 里处理文件路径的现代写法，比直接拼接字符串更清晰。

例如：

BASE_DIR = Path(__file__).resolve().parent
DEFAULT_SAMPLE_FILE = BASE_DIR / "文本对比样本.txt"

这里的意思是：

• __file__ 表示当前脚本文件
• resolve() 获取脚本的完整路径
• parent 获取脚本所在文件夹
• / 可以用来拼接路径

这样写的好处是：无论用户从哪里运行脚本，它都能找到脚本同目录下的文本文件。

Python 知识点 2：读取和写入文本文件

读取文件使用：

path.read_text(encoding="utf-8-sig")

写入文件使用：

output_file.write_text(report, encoding="utf-8")

这里指定了编码：

• utf-8 是常见的通用文本编码
• utf-8-sig 可以兼容带 BOM 的 UTF-8 文件

这对中文文本很重要。如果编码处理不好，中文可能会乱码。

Python 知识点 3：异常检查

脚本中有一个读取文本的函数：

def read_text(path: Path) -> str:
    if not path.exists():
        raise FileNotFoundError(f"找不到文件：{path}")
    return path.read_text(encoding="utf-8-sig")

这里先判断文件是否存在：

if not path.exists():

如果文件不存在，就主动抛出错误：

raise FileNotFoundError(...)

这样比静默失败更好，因为用户可以马上知道是哪个文件缺失。

Python 知识点 4：函数拆分

脚本没有把所有代码都写在一起，而是拆成了多个函数：

read_text()
split_lines()
mark_line_diff()
compare_texts()
build_report()
parse_args()
main()

这种写法的好处是：

• 每个函数只负责一件事
• 代码更容易阅读
• 后续修改更方便
• 出问题时更容易定位

比如 compare_texts() 只负责比较文本，build_report() 只负责生成报告内容。

Python 知识点 5：dataclass 保存结构化数据

脚本中定义了一个数据类：

@dataclass
class LineDiff:
    line_no: int
    sample_line: str
    target_line: str
    marked_target: str
    notes: list[str]

dataclass 适合用来保存一组相关数据。

这里每一处差异都包含：

• 第几行
• 标准文本内容
• 待检查文本内容
• 标注后的内容
• 差异说明

相比用普通字典，dataclass 的字段更清楚，代码也更容易维护。

Python 知识点 6：difflib 比较字符串差异

脚本中最关键的比较功能来自 Python 标准库：

import difflib

核心代码是：

matcher = difflib.SequenceMatcher(a=sample_line, b=target_line)

SequenceMatcher 可以比较两个字符串，并告诉我们哪些部分相同、哪些部分不同。

它返回的差异类型主要有：

类型	含义
equal	两边内容相同
replace	内容被替换了
delete	目标文本里缺少内容
insert	目标文本里多出内容

脚本根据这些类型生成不同的标注。

例如：

elif tag == "replace":
    marked_parts.append(f"【错误:{actual}｜应为:{expected}】")

这表示如果发现替换错误，就把错误内容和正确内容一起写进结果文件。

Python 知识点 7：命令行参数

脚本使用了：

import argparse

argparse 可以让脚本支持命令行参数。

比如默认运行：

python3 对比文档脚本.py

会覆盖旧结果。

如果想保留历史结果，可以运行：

python3 对比文档脚本.py --append

这个 --append 参数就是通过 argparse 实现的。

脚本中对应代码是：

parser.add_argument(
    "--append",
    action="store_true",
    help="追加到输出文件末尾；默认覆盖输出文件，便于每次粘贴后得到最新结果",
)

action="store_true" 的意思是：只要用户写了 --append，这个值就变成 True。

Python 知识点 8：程序入口

脚本最后有这样一段：

if __name__ == "__main__":
    main()

这是 Python 脚本里非常常见的写法。

它的意思是：当这个文件被直接运行时，执行 main() 函数。

这样做的好处是，如果以后这个文件被其他 Python 文件导入，里面的函数可以被复用，但不会自动执行完整流程。

为什么这个脚本不需要安装额外依赖

这个工具用到的库包括：

argparse
difflib
dataclasses
datetime
pathlib

这些都是 Python 自带的标准库。

也就是说，只要电脑上安装了 Python 3，一般就可以运行，不需要再安装第三方库。

Windows 用户需要注意，安装 Python 时建议勾选：

Add python.exe to PATH

否则可能会出现终端找不到 python 命令的问题。

常见问题

1. 为什么运行后看起来没反应？

这个脚本不会弹出窗口，它只会在终端输出提示，并把结果写入：

标注出来的错误文本.txt

所以运行后需要打开这个文件查看结果。

2. 为什么 Windows 上 python3 不能用？

Windows 上常见命令是：

python 对比文档脚本.py

或者：

py -3 对比文档脚本.py

python3 在 macOS 和 Linux 上更常见，Windows 上不一定默认支持。

3. 为什么提示找不到文件？

通常是因为几个 .txt 文件没有和脚本放在同一个文件夹里。

请确认这些文件都在一起：

文本对比样本.txt
需要对比的文本.txt
标注出来的错误文本.txt
对比文档脚本.py

4. 为什么结果看起来对不上？

这个工具是按行比较的。

如果两份文本的换行位置差很多，结果可能不够直观。

建议把两份文本按相同段落、相同行粘贴，这样对比结果会更清楚。

总结

这个文本对比工具是一个很适合入门学习的 Python 小项目。

它覆盖了文件读写、路径处理、字符串比较、命令行参数、函数拆分、数据类等常见知识点，同时也能解决实际工作中的文本校对问题。

从这个脚本可以看到，Python 不一定要写得很复杂，使用标准库就能快速做出实用的小工具。