本文详解使用 pymupdf 按页面文本关键词拆分 pdf 的正确方法，指出原脚本中因逻辑冗余与状态管理不当导致的页面重复生成问题，并提供简洁、健壮、无重复的实现方案。
在使用 PyMuPDF（即 fitz）对大量 PDF 批量按关键词拆分时，一个常见误区是：误以为需要手动维护已处理页码集合来防止重复。实际上，原代码中引入 processed_pages = set() 并配合 continue 跳过已处理页，不仅多余，还可能因逻辑干扰（如循环中意外修改状态）引发难以察觉的异常行为——但更关键的是：根本不存在“一页被多次处理”的底层机制。for page_number in range(len(pdf_document)) 是严格的顺序遍历，每页仅访问一次；所谓“文件重复”，实为其他原因所致，例如：
- 输出文件名未去重：若多个 PDF 中存在同名源文件（如均叫 report.pdf），且未将路径信息或唯一标识纳入文件名，会导致后写入覆盖或看似“重复”；
- 关键词跨页匹配误判：keyword in text 对大小写、空格、换行敏感，若 PDF 文本提取不完整（如含图像文字未 OCR），可能漏判或误判；
- page.get_text() 提取不稳定：某些 PDF 的文本流顺序混乱，或含不可见控制字符，导致 in 判断失效。
✅ 正确做法应摒弃手动页码跟踪，转而依赖 page.search_for(keyword) —— 这是 PyMuPDF 官方推荐的高精度关键词定位方法。它基于 PDF 内容流坐标搜索，不依赖文本提取质量，返回匹配区域列表（空列表表示未找到），语义清晰、性能优异且零副作用。
以下是优化后的生产级实现（支持批量处理 + 防冲突命名 + 错误防护）：
import os
import fitz
from pathlib import Path
def split_pdf_by_keyword(pdf_path: str, keyword: str, output_dir: str) -> int:
"""
将单个 PDF 中所有含 keyword 的页面分别保存为独立 PDF。
返回成功拆分的页数。
"""
pdf_path = Path(pdf_path)
if not pdf_path.is_file() or pdf_path.suffix.lower() != ".pdf":
print(f"⚠️ 跳过无效文件: {pdf_path}")
return 0
try:
doc = fitz.open(pdf_path)
except Exception as e:
print(f"❌ 打开失败 {pdf_path}: {e}")
return 0
output_dir = Path(output_dir)
output_dir.mkdir(parents=True, exist_ok=True)
saved_count = 0
base_name = pdf_path.stem
for page in doc:
# ✅ 关键改进：使用 search_for 替代 get_text + in 判断
if page.search_for(keyword): # 返回非空列表即匹配成功
# ? 防重名：加入原始文件哈希/时间戳或使用绝对页码（如 file_001_page_42.pdf）
out_name = f"{base_name}_p{page.number + 1:03d}_{keyword.replace(' ', '_')}.pdf"
out_path = output_dir / out_name
# 创建单页 PDF
new_doc = fitz.open()
new_doc.insert_pdf(doc, from_page=page.number, to_page=page.number)
new_doc.save(out_path)
new_doc.close()
print(f"✅ 已保存: {out_path.name}")
saved_count += 1
doc.close()
return saved_count
# 批量处理入口
def batch_split_pdfs(input_folder: str, keyword: str, output_folder: str):
input_path = Path(input_folder)
pdf_files = list(input_path.rglob("*.pdf"))
print(f"? 开始处理 {len(pdf_files)} 个 PDF 文件...")
total_saved = 0
for pdf_file in pdf_files:
total_saved += split_pdf_by_keyword(pdf_file, keyword, output_folder)
print(f"? 全部完成！共生成 {total_saved} 个关键词匹配页面 PDF。")
# 使用示例
if __name__ == "__main__":
batch_split_pdfs(
input_folder="./input_pdfs",
keyword="CONFIDENTIAL", # 支持大小写敏感匹配（如需忽略大小写，可先统一转换）
output_folder="./split_output"
)? 重要注意事项：
- page.search_for() 默认区分大小写。如需忽略大小写，可改用正则模式：page.search_for(rf"(?i){re.escape(keyword)}")（需 import re）；
- 输出文件名中嵌入 page.number + 1（从1开始计数）和关键词片段，确保全局唯一，彻底规避覆盖风险；
- 不要调用 page.get_text() 做关键词判断——它在扫描型 PDF、加密 PDF 或含复杂字体时极易失败；search_for 直接操作 PDF 原生内容流，鲁棒性高；
- 若需进一步提升效率（如千级 PDF），可结合 concurrent.futures.ProcessPoolExecutor 并行化，但注意 fitz.open() 在多进程下需重新打开文档。
遵循此方案，即可彻底解决“拆分后文件重复”问题，实现稳定、可预测、可维护的 PDF 关键词驱动拆分流程。
