PyMuPDF PDF清理功能在保存时出现内容丢失问题分析

近期在PyMuPDF项目中发现了一个关于PDF文档清理功能的严重问题：当用户使用clean参数保存某些特定扫描生成的PDF文件时，文档内容会意外变为空白。这个问题从1.24.0版本开始出现，而1.23.26版本则表现正常。

问题现象

该问题主要出现在由Lexmark扫描设备生成的PDF文档上。当用户使用以下代码处理这类文档时：

with pymupdf.open('input.pdf') as doc:
    doc.save('output.pdf', clean=True)

保存后的output.pdf文件会变成空白页，而原始文档内容完全丢失。

技术背景

PyMuPDF的clean参数实际上会为文档中的每个页面执行page.clean_contents()操作。这个功能原本设计用于：

1. 清理PDF页面中的冗余内容
2. 修复某些文档结构问题
3. 优化文档内部结构

然而，对于普通PDF文档而言，单独使用clean参数通常不会带来明显的正面效果。它只有在与垃圾回收(garbage collection)和压缩(compression)功能配合使用时，才可能有效减小文件体积。

问题根源

经过开发团队调查，发现问题出在底层MuPDF库的PDF内容清理逻辑中。在某些特定扫描生成的PDF文档中，清理过程会错误地移除所有有效内容而非仅清理冗余数据。这属于一个上游bug，已在MuPDF项目中提交了对应的错误报告。

解决方案

PyMuPDF开发团队已在1.25.1版本中修复了这个问题。建议遇到此问题的用户：

1. 立即升级到PyMuPDF 1.25.1或更高版本
2. 如果暂时无法升级，可以暂时避免单独使用clean参数
3. 对于必须使用clean功能的场景，建议配合garbage和deflate参数一起使用

最佳实践建议

对于需要处理混合来源PDF文档的用户，建议：

1. 谨慎使用clean参数，特别是在处理扫描文档时
2. 结合garbage=3和deflate=True参数一起使用
3. 在处理重要文档前，先在测试文件上验证效果
4. 考虑实现自动化测试流程，确保处理后的文档内容完整性

这个问题提醒我们，即使是看似简单的文档处理操作，也可能因为文档来源的多样性而产生意外结果。在实际应用中，对关键文档处理流程进行充分测试是非常必要的。