如何用 gscan2pdf 的日志功能排查扫描或运行故障

更新时间

当 gscan2pdf 扫描失败、导入异常或启动报错时，最直接的排查方式是从命令行带日志参数启动：gscan2pdf --log=file.log，然后查看生成的 file.log。这条命令适用于 Linux 桌面环境（Debian/Ubuntu 等），前提是程序已安装且能在终端中调用。指定日志文件后，日志级别默认是 --debug，会记录最详细的信息；不指定日志文件时默认只输出 --error 及以上级别。

操作步骤

  1. 打开终端，确认程序可调用：
gscan2pdf --version

预期结果是输出版本号（如 2.13.3）并退出。如果提示找不到命令，说明程序未安装或不在 PATH 中，需要先解决安装问题。

  1. 带日志文件启动：
gscan2pdf --log=file.log

程序正常启动后，复现你遇到的问题（例如执行 File/Scan 扫描、用 File/Save 保存 PDF、或用 --import 导入文件）。日志会持续写入 file.log。

  1. 关闭程序后查看日志：
less file.log

重点看报错前后的上下文，尤其是与 SANE、scanimage、PDF::Builder、libtiff 相关的行，这些是扫描、PDF 转换和 TIFF 导出的实际处理组件。

调整日志级别

日志级别通过独立选项控制，可与 --log 组合使用：

选项 作用
--debug 最详细，指定日志文件时的默认级别
--info 常规信息
--warn 仅警告及以上
--error 仅错误，未指定日志文件时的默认级别
--fatal 仅致命错误

例如只想看警告和错误、避免日志过大：

gscan2pdf --log=file.log --warn

需要排查扫描设备识别问题时，保持默认 --debug 更合适。

常见卡点

  • 日志文件为空或不存在：确认启动命令中 --log= 后确实跟了文件名，且当前目录可写；也可写绝对路径如 --log=/tmp/gscan2pdf.log。
  • 扫描仪未被发现：如果扫描仪在远程电脑上且不广播自身，可用 --device=device 直接指定设备，绕过 SANE API 的设备列表。日志中会反映设备连接情况。
  • 导入 PDF 出错：官方说明导入 PDF 主要用于让 gscan2pdf 自己生成的文件往返编辑，导入其他来源的 PDF 可能出问题，这类情况在日志中通常能看到解析错误。
  • 配置相关异常：程序会在 ~/.config/gscan2pdfrc 创建文本资源文件，目录可用 $XDG_CONFIG_HOME 改变。日常偏好应通过 Edit/Preferences 修改，而不是手改该文件；若怀疑配置损坏，可结合日志判断。

拿到日志后，先定位第一条错误出现的位置，再对照当时执行的操作（扫描、保存、导入），通常就能判断问题出在设备连接、文件格式还是导出环节。