pdfl compare 和 pdfl pixelcompare 有什么区别

两个命令都接收两份 PDF，告诉你哪里变了。看上去像是重复，直到它们第一次给出不同的 答案——那时你才发现，它们从来就不是在回答同一个问题。

pdfl compare 问的是：这份文档说了什么。 pdfl pixelcompare 问的是：这份文档看上去是什么样。

一个文件可以通过其中一个而没通过另一个，两个方向都可能。

pdfl compare：文档说了什么

它读取文字、结构和元数据：

pdfl compare approved_v1.pdf new_v2.pdf

值得了解的是它如何对齐页面：按内容对齐，而不是按页码。在一份合同中间插入一页， 简单粗暴的比对会把之后每一页都报成“变了”；而这个比对会察觉到这次插入，继续拿对应 的内容互相比较。文档超过一千页也撑得住。

每一对对齐的页面会得到一个相似度，以及变动行的样例，- 表示删除，+ 表示新增：

page 4 → 4: similarity 97.8% | -original title | +revised title

元数据变化算警告。文字变化在低于你设定的阈值时算错误，高于阈值时算警告。

# 忽略大小写、空格和日期——当签发日期每次导出都会重新生成，
# 而它并不是本次审阅的对象时很有用
pdfl compare approved_v1.pdf new_v2.pdf --normalize --ignore-dates

# 允许最多 1% 的差异，并产出一份人能读的东西
pdfl compare v1.pdf v2.pdf --similarity-threshold 99 \
  --output html --output-file diff.html

pdfl pixelcompare：文档看上去是什么样

它把两个文件渲染出来，把页面当作图像来比对：

pdfl pixelcompare approved.pdf reprint.pdf

每个变化的页面报告一条，附上有多少比例不同、分散在多少处：

page 7: 0.51% of the pixels differ, in 29 area(s)

它会先补偿整体位移，因为从同一个源重新导出的文件常常会偏移一两个像素，不补偿的话 每一个字的边缘都会被算成差异：

page 3: 2.10% of the pixels differ, in 44 area(s) (aligned by 2, -1 px)

它还能写出一个可以亲眼看的地方：

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

那个文件夹里有页面、差异和一个 index.html——不需要服务器，不需要安装任何东西。 红色是消失的墨，绿色是新增的墨，蓝色是墨色相同但颜色不同。

它们在哪里不一致

文字完全相同，文件却是错的。 挪了两毫米的标志。消失的细线。被 CMYK 叠印替换 掉的专色。这三种情况 compare 都会报告完全匹配，因为没有一个字符移动过。 pixelcompare 三种都能抓到。

看上去完全相同，文字却是错的。 元数据里的标题被换掉了，或者作者字段被改写了。 页面上没有一个像素移动，所以 pixelcompare 看到的是两份相同的文档。compare 会 报告这个变化。

两者互不包含。 这正是关键。

四种场景，以及该跑什么

合同从法务那边回来了。 你需要知道现在的措辞和之前说的有什么不同。版面必然会 重新回流，而你并不在意这个。

pdfl compare contract_v3.pdf contract_v4.pdf --ignore-dates \
  --output html --output-file review.html

供应商送来了重印件。 它不能有任何地方看起来和已批准的打样不一样。文字是不是 逐字节相同并不重要——问题是印到纸上的东西。

pdfl pixelcompare approved.pdf reprint.pdf --viewer diff/

同一份文档，换了工具导出。 供应商换了软件。文字必须原封不动地保住，而外观很 可能会有些偏移。这需要两个命令，它们检查的是不同的承诺：

pdfl compare old_export.pdf new_export.pdf --normalize
pdfl pixelcompare old_export.pdf new_export.pdf --max-diff 0.1 --viewer diff/

受监管的标签或说明书。 警示文字是法律要求的，版面是有人签字批准的。两者都有 约束力，所以两者都要检查——而查看器那个文件夹，就是你附在批准记录上的东西。

pdfl compare approved.pdf press_file.pdf
pdfl pixelcompare approved.pdf press_file.pdf --viewer evidence/

两个一起，作为关卡

两个命令都会返回退出码，所以脚本无需读取任何内容就能决定。pixelcompare 用 0 表示没有页面超出容差，2 表示有，10 表示文件读不了；compare 遵循所有校验类 命令共同的约定——0 通过，1 警告，2 错误，10 读不了。

#!/bin/sh
# 两个承诺，一道关卡：文字，以及外观。
set -e

pdfl compare approved.pdf candidate.pdf --output-file text-diff.json || {
  echo "措辞变了——请看 text-diff.json"
  exit 1
}

pdfl pixelcompare approved.pdf candidate.pdf --max-diff 0.05 --viewer diff/ || {
  echo "看起来不一样——请打开 diff/index.html"
  exit 1
}

echo "文字相同，外观相同"

用哪一个，一行说清

你在问的问题	命令
措辞变了吗？	pdfl compare
元数据变了吗？	pdfl compare
有没有插入或删除页面？	pdfl compare
有东西移动、消失或变色了吗？	pdfl pixelcompare
印出来还一样吗？	pdfl pixelcompare
这是被批准的那份文件吗？	两个都用

接下来看哪里

CLI 这一章记录了两者的每一个选项，实用范例 把它们放进完整的流程里。这里还有一篇关于逐像素比对 的文章，讲错的文件一旦上机要付出什么。