PDF Smaller

一个本地运行的 PDF 压缩工具，适合压缩扫描版论文、课件、合同、报告等体积较大的 PDF。文件不会上传到第三方服务器，隐私和处理过程都留在本机。

特性

• 本地处理：不上传文件，适合敏感文档。
• 三种压缩模式：无损、均衡、强力压缩。
• 自动生成输出文件：默认输出为 <原文件名>.smaller.pdf。
• 输出保护：默认不覆盖已有文件，需要覆盖时显式添加 --overwrite。
• 失败更安全：先写入临时文件，成功后再替换目标文件，减少半成品 PDF 残留。
• 支持打包为 Windows 单文件命令行程序。

压缩模式

模式	是否有损	依赖	适用场景
lossless	无损	Python + pikepdf	PDF 结构优化，不降低图片质量，压缩幅度通常较小
balanced	有损	Python + Ghostscript	默认推荐，兼顾体积和清晰度
strong	有损	Python + Ghostscript	极限压缩，文件很大且只要求可读时使用

提示：扫描版 PDF 通常压缩效果明显；已经优化过的电子版 PDF 可能不会变小，甚至会略微变大。

环境要求

• Python 3.9 或更高版本
• Python 依赖：pikepdf
• 可选打包依赖：pyinstaller
• 使用 balanced 或 strong 模式时需要安装 Ghostscript

安装 Ghostscript

Windows 用户建议安装 64 位 Ghostscript，并确认 gswin64c 可以在命令行中运行：

gswin64c --version

macOS / Linux 用户通常可以通过包管理器安装，并确认 gs 可以运行：

gs --version

安装

git clone https://github.com/your-username/pdf_smaller.git
cd pdf_smaller
python -m pip install -r requirements.txt

如果只是使用 lossless 模式，不需要安装 Ghostscript。

使用方法

默认使用 balanced 模式，并在输入文件同目录生成 .smaller.pdf：

python pdf_smaller.py .\input.pdf

指定输出路径：

python pdf_smaller.py .\input.pdf -o .\output.pdf

覆盖已有输出文件：

python pdf_smaller.py .\input.pdf -o .\output.pdf --overwrite

切换压缩模式：

python pdf_smaller.py .\input.pdf --mode lossless
python pdf_smaller.py .\input.pdf --mode balanced
python pdf_smaller.py .\input.pdf --mode strong

设置 Ghostscript 超时时间，单位为秒：

python pdf_smaller.py .\input.pdf --timeout 600

关闭进度提示：

python pdf_smaller.py .\input.pdf --no-progress

查看完整参数：

python pdf_smaller.py --help

打包为 exe

项目提供了 build.bat，会安装依赖并使用 PyInstaller 生成单文件命令行程序。

.\build.bat

生成结果位于 dist\pdf_compressor.exe。打包后的程序仍然需要系统中安装 Ghostscript，才能使用 balanced 和 strong 模式。

也可以直接使用 spec 文件打包：

pyinstaller pdf_compressor.spec

常见问题

为什么提示找不到 Ghostscript？

balanced 和 strong 模式会调用系统中的 Ghostscript。请安装 Ghostscript，并确认 gswin64c、gswin32c 或 gs 能在命令行中直接运行。

为什么压缩后文件变大了？

有些 PDF 已经被高度优化，重新编码后可能不会继续变小。可以尝试 lossless 模式，或者保留原文件。

会不会覆盖原文件？

不会。程序禁止输入路径和输出路径相同，即使添加 --overwrite 也不会覆盖原始 PDF。

输出文件已存在怎么办？

默认会报错，避免误覆盖。确认要替换时添加 --overwrite。

项目结构

pdf_smaller/
├── pdf_smaller.py          # 主程序
├── requirements.txt        # Python 依赖
├── build.bat               # Windows 打包脚本
├── pdf_compressor.spec     # PyInstaller 配置
├── README.md               # 项目说明
└── LICENSE                 # MIT 许可证

开发建议

• 提交代码前运行 python pdf_smaller.py --help，确认 CLI 正常。
• 使用真实 PDF 测试时，不要把测试文件提交到仓库，.gitignore 已默认忽略 *.pdf。
• 如果要发布 Release，请把 README 中的 GitHub 地址替换成你的真实仓库地址。

License

MIT License. See LICENSE for details.