本文介绍一种基于sha-256哈希校验的可靠方法，遍历指定目录及其所有子目录，对每个pdf文件计算内容级唯一指纹，自动识别内容相同但文件名不同的重复项，并保留首次出现的文件路径作为唯一代表。
本文介绍一种基于sha-256哈希校验的可靠方法，遍历指定目录及其所有子目录，对每个pdf文件计算内容级唯一指纹，自动识别内容相同但文件名不同的重复项，并保留首次出现的文件路径作为唯一代表。
在处理大量文档（尤其是PDF）时，仅靠文件名或大小判断重复性极易出错——两个同名文件可能内容不同，而内容完全一致的文件却可能命名为 report_v2_final.pdf 和 annual_summary_2024.pdf。真正可靠的去重逻辑必须基于文件内容本身。本文推荐使用加密哈希（如 sha256）作为“数字指纹”：只要文件二进制内容一致，其哈希值必然完全相同；反之，哪怕仅一个字节差异，哈希也会显著不同。该方法远比逐字提取PDF文本（如原代码中用 fitz 解析再比对）更高效、稳定且不依赖PDF解析库的兼容性与鲁棒性。
以下是完整可运行的教程代码：
import os
import hashlib
from collections import defaultdict
def file_hash(filepath):
"""计算文件的SHA-256哈希值（流式读取，内存友好）"""
hasher = hashlib.sha256()
try:
with open(filepath, "rb") as f:
for chunk in iter(lambda: f.read(4096), b""):
hasher.update(chunk)
return hasher.hexdigest()
except (OSError, IOError) as e:
print(f"⚠️ 跳过无法读取的文件: {filepath} — {e}")
return None
def find_unique_pdf_files(directory):
"""
遍历 directory 及其所有子目录，返回内容唯一的PDF文件路径列表（保留首次出现者）
返回: list[str] — 按首次发现顺序排列的唯一PDF路径
"""
seen_hashes = {} # hash → 第一次出现的完整路径
unique_paths = []
for root, _, files in os.walk(directory):
for file in files:
if not file.lower().endswith(".pdf"):
continue
file_path = os.path.join(root, file)
file_checksum = file_hash(file_path)
if file_checksum is None:
continue
# 若该哈希未见过，记录并加入结果；否则跳过（即保留第一个）
if file_checksum not in seen_hashes:
seen_hashes[file_checksum] = file_path
unique_paths.append(file_path)
return unique_paths
# ✅ 使用示例（请替换为你的实际路径）
directory = r"E:/username/Desktop/xx" # 注意：Windows路径建议用原始字符串（r""）或双反斜杠
unique_pdfs = find_unique_pdf_files(directory)
print(f"✅ 扫描完成！共找到 {len(unique_pdfs)} 个内容唯一的PDF文件：")
for i, path in enumerate(unique_pdfs, 1):
print(f"{i:2d}. {path}")关键优势说明：
- 准确性强：哈希基于完整二进制流，不受PDF元数据、注释、嵌入字体等无关差异干扰；
- 性能优异：无需解析PDF结构或提取文本，避免 fitz（PyMuPDF）可能出现的崩溃、乱码或OCR依赖；
- 内存安全：分块读取（4KB/chunk），轻松处理GB级大文件；
- 健壮容错：自动跳过权限不足、损坏或被占用的文件，并输出警告提示；
- 语义清晰：find_unique_pdf_files() 直接返回所需格式——按遍历顺序排列的唯一路径列表，与问题期望输出完全一致。
注意事项：
- 确保安装必要依赖：pip install PyMuPDF（本方案不需要，仅作对比说明）；本方案纯标准库，零额外依赖；
- 若需支持其他格式（如 .docx, .xlsx），只需修改 endswith() 判断条件；
- 对于超大规模文件集（>10万），可考虑使用 concurrent.futures.ThreadPoolExecutor 并行加速哈希计算（注意I/O瓶颈）；
- 哈希本身不提供文件内容验证——若需防篡改审计，应结合数字签名机制。
该方案从根本上规避了原代码中多重嵌套循环+重复解析+逻辑分支混乱导致的错误（如 compare_multiple_pdfs 中 return 位置错误、未初始化 unique_files、重复调用 compare_pdfs 引发性能灾难等）。用哈希做“内容身份证”，是文件去重领域公认的最佳实践。
