使用pdf2image的convert_from_bytes转换PDF时返回空列表如何解决

问题排查解答 #

1. 联网依赖确认 #

pdf2image完全不需要联网即可运行，其本质是对本地Poppler组件（pdftoppm、pdftocairo命令行工具）的Python封装，所有转换操作均在本地完成，服务器2的网络受限不会导致该问题。

2. 空列表问题排查步骤 #

• 先验证Poppler可用性：不要仅确认安装状态，直接在服务器2命令行执行测试命令pdftoppm <你的测试pdf文件路径> test_output -png，看是否能正常生成图片。常见问题包括Poppler路径未加入运行应用的用户的PATH环境变量、Poppler依赖缺失（如libjpeg、libpng等底层依赖包未安装）、安装的Poppler版本与pdf2image 1.13.1不兼容。
• 校验输入PDF字节流完整性：在服务器2调用convert_from_bytes前，打印输入的字节流长度，和服务器1上正常运行时的字节流长度对比，确认服务器2拿到的PDF字节流没有被截断、损坏或者为空。pdf2image处理无效PDF时默认不会抛出异常，只会返回空列表。
• 开启严格模式捕获错误：调用convert_from_bytes时增加strict=True参数，该参数开启后转换出错会直接抛出具体异常信息，而非静默返回空列表，可直接定位具体错误原因。
• 检查权限配置：确认运行应用的用户对Poppler执行文件有执行权限，对系统临时目录有读写权限。pdf2image转换过程中会在临时目录生成中转文件，权限不足会导致转换失败且无报错。

内容的提问来源于stack exchange，提问作者Annabelle79