有一次我从客户发来的 PDF 里整理产品图页面上图片清清楚楚右键还能“另存为”可真正批量导出以后导出的图片不是尺寸不对就是数量少了很多。后来换了个思路用 Python 提取 PDF 中的图片几行代码跑通可一放到真实文件上图片少、文件乱、原图变样、程序中途崩溃这些问题又全冒出来了。那时候我就意识到问题通常不出在代码本身而在于很多人没有先把需求想清楚你要的是 PDF 里的“原始图片素材”还是页面上肉眼看到的那张图。这两类需求看着像一回事实际完全对应着不同的技术路线也会得到完全不同的结果质量。这篇文章不是只给你一段能跑的代码而是想把“用 Python 提取 PDF 图片”这件事拆成需求判断、最小实现、批量工程化、兜底渲染和排查链路几个层次来讲。你跟着这套思路走一遍以后再拿到奇怪 PDF就不至于每次都靠试。1. 先想清楚你要的是 PDF 里的“原始素材”还是页面上的那张图1.1 两种需求看起来一样结果逻辑完全不同第一种需求是把 PDF 当作一个容器。你希望把里面嵌入的图片对象完整取出来保留原始编码、原始尺寸、原始色彩信息。比如一个排版文件里包含了高质量的商品图你要把它们还原成独立图片这属于“提取素材”。第二种需求是把 PDF 的页面当作一张画布。你想把页面某一块区域的视觉效果保存成图片比如从一张数据报表里截取一个图表区域或者把扫描件里某个图形块裁出来这属于“提取画面”。这两种需求和最终输出并不完全等价。PDF 里的图片对象不等于阅读器上显示给你看的那张图。一张大图可以被转 90 度引用可以被局部裁剪可以被半透明遮罩叠加也可以被内容流里的矢量图形盖住一部分。如果你直接导出图片对象得到的很可能是原始未旋转、未裁切、未修饰的图片。而如果你用页面渲染工具去截取某个区域得到的又可能是重采样之后的结果不是原图质量。所以第一步不是写代码而是问自己到底要原素材还是要视觉结果。1.2 为什么不能靠“找文件头、文件尾”的方式硬抠图片很多人一上手会想到用 Python 读取二进制文件然后通过 JPG 的文件头FF D8 FF或者 PNG 的文件头去扫描数据。这个思路对某些简单 PDF 也许能跑通但非常脆弱。原因有两个。第一PDF 内部不是一张张图片顺序排列的图片数据可能经过压缩、编码、拆包也可能被对象间接引用文件里的字节顺序和你读到的视觉顺序没有直接关系。第二PDF 既有扫描文本也有翻录还有被压缩进对象流里的小对象。直接通过二进制扫描很难准确判断一个图片数据的起止位置很容易把图片截断或者误识别成乱码。正确的方式是先理解 PDF 的底层结构图片通常是页面内容流里引用的一种 Image XObject。它带有宽度、高度、滤镜、色彩空间等参数图片数据本身按对应编码存放在 PDF 对象中。PyMuPDF 这类库做的事情就是把这些细节封装成高层接口让你不需要手动拼装对象引用关系。1.3 理解一点对象概念比多抄几段代码更有用你不需要成为 PDF 规范专家但至少应该知道几个关键词。PDF 文件的基本单位是“对象”每个对象有编号。页面对象通过资源字典去引用图片对象图片对象在 PDF 里通常以/Subtype /Image的形式存在。真正要导出图片时脚本要做的事可以简化成先找到页面里引用了哪些图片对象再按对象编号去 PDF 顶层对象里把图片数据取出来。PyMuPDF 的page.get_images(fullTrue)就是负责找引用doc.extract_image(xref)就是负责按对象编号取数据。你只要把这两个接口组合起来就能写出一个最小可用版本。先掌握这个对象思维后面遇到问题时排查方向就会清晰很多。你遇到的很多“图片提取不出来”的奇怪现象本质上不是 Python 语法问题而是“图片所在的位置”和“提取工具寻找的位置”不匹配。2. 最小闭环用 PyMuPDF 把嵌入的图片完整导出2.1 环境准备为什么安装 PyMuPDF 之后导入的模块叫 fitz先说安装最简单的命令是python -m pip install PyMuPDF这里有一个很常见的困惑装的是 PyMuPDF代码里写的却是import fitz。这是历史遗留命名不是要故意绕晕你。PyMuPDF 在 Python 环境里对外的导入模块一直使用fitz后续文档也在延续这个习惯。如果你遇到ModuleNotFoundError: No module named fitz不要改成安装一个叫fitz的别的包优先检查当前命令行使用的 Python 环境和 pip 安装环境是不是同一个。在 Windows 上最容易出现这种问题因为系统里可能同时存在多个 Python。最稳妥的方式不是直接执行pip install而是用当前解释器对应的 pip 命令来安装python -m pip install PyMuPDF这样保证包被你当前正在用的 Python 环境接收。如果还要对图片做校验、裁剪、格式转换建议顺手安装 Pillowpython -m pip install Pillow2.2 一个能真正把原图落盘的最小脚本下面这个脚本结构比较保守用 try/finally 保证 PDF 文件最终会被关闭。你不要小看这个细节批量跑几百个 PDF 时文件句柄不释放会带来很隐蔽的资源占用问题。import os import fitz def extract_images_from_pdf(pdf_path, out_dirimages_out): os.makedirs(out_dir, exist_okTrue) doc fitz.open(pdf_path) saved_count 0 used_xrefs set() try: for page_index in range(len(doc)): page doc.load_page(page_index) page_images page.get_images(fullTrue) if not page_images: print(f第 {page_index 1} 页没有找到图片对象) continue for xref in {item[0] for item in page_images}: if xref in used_xrefs: continue try: info doc.extract_image(xref) except Exception as exc: print(f第 {page_index 1} 页提取图片失败xref{xref}原因{exc}) continue image_data info.get(image) image_ext info.get(ext, bin) if not image_data: continue out_path os.path.join(out_dir, fimg_{xref:05d}.{image_ext}) with open(out_path, wb) as f: f.write(image_data) used_xrefs.add(xref) saved_count 1 finally: doc.close() print(f完成共保存 {saved_count} 张图片) return saved_count if __name__ __main__: extract_images_from_pdf(input.pdf)这段代码只做了一件事遍历每一页找到页面引用的图片对象按对象编号去 PDF 里取原始图片数据然后直接写成文件。这里有一个非常关键的选择保存图片数据时直接用extract_image返回的image字段和ext扩展名中间没有经过任何图片解码。这意味着你要保存到磁盘的是 PDF 里嵌入的原始二维码和原始数据而不是重新编码后的数据。对于 PDF 内部的 JPEG 图片直接保存成.jpg通常是安全的。对于 PNG、JPX 等你没见过的扩展名也不要急着改后缀先用文件头校验工具确认格式再用图片浏览器打开看看。2.3 extract_image 返回了什么脚本才能判断怎么处理很多人把get_images的结果直接当成图片内容来写文件结果写出来的东西打不开。实际上get_images(fullTrue)返回的是一批元组第一个元素才是图片对象的编号xref。真正要拿到图片数据需要进一步调用doc.extract_image(xref)。extract_image的返回结果通常是一个字典里面有这些信息需要注意image图片数据本体可能已经是 JPEG 或 PNG 编码后的字节直接用二进制方式写入文件即可。ext推荐使用的扩展名常见可能是jpeg、png、jpx、jb2这类值。width和height图片的原始像素尺寸注意不一定是页面上显示的尺寸。colorspace颜色空间比如 RGB、GRAY、CMYK。不要在extract_image返回的字典里做太强的主观判断因为不同 PDF 结构会有差异。比较稳妥的做法是先获取image和ext保存完用 Pillow 或文件类型工具验证生产级脚本里再考虑用哈希去重。注意如果只执行page.get_images(fullTrue)你拿到的只是图片对象的信息不是图片内容。你必须把xref传给doc.extract_image(xref)之后才能拿到可写入文件的字节流。2.4 第一次跑完以后别急着欢呼单页 PDF 跑通只能说明路径没有断。这时候你应该先做一个校验而不是立刻铺到 1000 个 PDF 上。我建议的校验顺序是用普通图片查看器打开导出文件确认不是乱码。对比 PDF 页面里的图片数量和实际导出数量。检查尺寸特别小、特别大的图片确认是否合理。用 Pillow 打开几张有代表性的图片读取size和mode确认没有在解码层出问题。如果这一步出现“数量对不上”先不要急大概率不是 Python 代码的 bug而是 PDF 本身对同一张图片的引用方式和视觉呈现方式不同。3. 从“跑通一次”到“批量处理”该补脚本能力而不是循环3.1 去重同一个对象出现在多个页面不应该重复保存一份真实的 PDF尤其是那种从办公软件导出的文件经常会出现同一个 Logo、同一个背景素材在多页里反复出现的情况。如果简单按“页码 图片序号”来命名会产生大量重复文件。这里可以通过xref去重因为同一张嵌入图片在 PDF 里往往会共享同一个对象编号。上面的最小脚本里已经加入了used_xrefs集合核心逻辑就是用xref判断这张图是不是已经处理过了。但这里还有一个更隐蔽的情况有时候同一个视觉图片会被保存成两个不同的对象编号比如一个文件被重复嵌入两次。如果你确定要去重到“内容级别”可以用内容哈希来处理。import hashlib def image_key(data: bytes) - str: return hashlib.sha256(data).hexdigest()在保存前先计算image_key(image_data)如果这个 key 已经出现过了就跳过。哈希去重的价格是额外的 CPU 和内存开销。如果 PDF 本身非常大、图片数量很多建议先用xref集合去重把大部分明显重复挡掉再决定是否做内容哈希。3.2 过滤干扰对象不要把所有东西都当作有效图片保存真实 PDF 里的图片对象千奇百怪常见会干扰你判断的对象包括只有几个像素宽的小图标或纹理。用于透明效果的 SMask 遮罩对象。用于页面平铺背景的 pattern。表单字段的外观流。被隐藏图层里的图片。如果你直接把所有图片都导出会得到一堆看起来没用的文件。比较好的过滤策略是先看尺寸和内容类型。一个通用做法是把width或height小于一定阈值的图片标记为低价值。不过阈值不能一刀切有些 PDF 里的商品缩略图可能本来就只有 200 像素宽。建议第一次先用“不删文件只打印统计信息”的方式运行把尺寸分布打出来再决定要不要真正过滤。还可以在 Pillow 层验证如果 Pillow 打开图片后能确认它不是空图、不是纯色马赛克通常说明这张图的二进制流是完整的。注意过滤逻辑宁可保守不要激进。直接把小于 100 像素的图片全删掉容易误伤重要素材。更安全的做法是先加一个“低价值目录”把疑似噪声单独放不污染主输出目录。3.3 日志、写入校验和异常恢复少一个都很难收场批量处理时最常见的失败不是提取逻辑本身而是文件系统问题、PDF 损坏、权限受限和路径冲突。建议给脚本补充几件事每一条失败记录都要打印页码或 xref不要只打印一句“提取失败”。图片写入以后最好校验一次文件大小不是 0。不要因为一张图失败就中断整个 PDF。对多 PDF 批量任务建议给每个 PDF 单独建立输出目录。这样即使跑到第 500 个 PDF 时出了问题你也能快速定位到是哪个输入文件、哪个 xref 出错而不是盯着控制台看只有一行FileNotFoundError。3.4 一个更实用的批量脚本骨架在进入真实项目前我会把脚本组织成三层结构单个 PDF 处理函数、批量遍历逻辑、主入口参数解析。import os import glob import hashlib import fitz def extract_single_pdf(pdf_path, out_dir): os.makedirs(out_dir, exist_okTrue) doc fitz.open(pdf_path) used_xrefs set() stats {total: 0, saved: 0, skipped: 0, failed: 0} try: for page_index in range(len(doc)): page doc.load_page(page_index) images page.get_images(fullTrue) stats[total] len(images) for xref in {item[0] for item in images}: if xref in used_xrefs: stats[skipped] 1 continue try: info doc.extract_image(xref) except Exception as exc: stats[failed] 1 print(fextract failed: {pdf_path} page {page_index 1}, xref {xref}, {exc}) continue data info.get(image) ext info.get(ext, bin) if not data: stats[failed] 1 continue digest hashlib.sha256(data).hexdigest()[:16] out_path os.path.join(out_dir, f{digest}.{ext}) if os.path.exists(out_path): stats[skipped] 1 continue with open(out_path, wb) as f: f.write(data) stats[saved] 1 used_xrefs.add(xref) print(f{pdf_path}: saved{stats[saved]}, skipped{stats[skipped]}, failed{stats[failed]}) return stats finally: doc.close() def process_many(pdf_dir, out_root): for pdf_path in glob.glob(os.path.join(pdf_dir, *.pdf)): basename os.path.splitext(os.path.basename(pdf_path))[0] target_dir os.path.join(out_root, basename) extract_single_pdf(pdf_path, target_dir)这个骨架并不是最精简的但它能覆盖大多数批量场景去重、容错、独立目录、统计信息都齐了。如果你只需要临时处理一份 PDF可以去掉批量遍历层。4. 页面里明明看得到图对象列表里却拿不到怎么办4.1 你看到的不一定是嵌入图片对象有几种情况会让get_images返回空列表但页面仍然有图形内容。第一种图片是矢量图。页面里看到的是一个用路径、曲线和颜色填充组成的矢量图形而不是嵌入的位图对象。此时不存在“图片 XObject”自然也没有原图可提取。你要么接受矢量结果要么把页面渲染成图片。第二种图片被嵌在复杂的表单 XObject 或内容流里。PyMuPDF 虽然已经会递归搜索页面资源但遇到非常规的 PDF 结构时你仍然可能拿不到想要的对象编号。第三种页面显示的是图片但整个图被放在一个容器或裁剪区域里。你从对象层面拿出来的图片是完整的视觉上却被裁剪了。遇到这种情况不要反复折腾get_images。你应该把策略切换成“渲染页面区域”直接按视觉看到的内容来生成图片。4.2 兜底策略按位置渲染页面局部区域PyMuPDF 的页面对象渲染能力此时更有用。你可以先通过page.get_image_info(xrefsTrue)获取图片在页面上的位置信息再用渲染功能把对应区域画成一张新的 PNG。import fitz def render_region(pdf_path, page_index, bbox, output_path, zoom2): doc fitz.open(pdf_path) try: page doc.load_page(page_index) clip fitz.Rect(bbox) matrix fitz.Matrix(zoom, zoom) pix page.get_pixmap(matrixmatrix, clipclip) pix.save(output_path) finally: doc.close()这里的bbox一般是一个四元组或 Rect表示页面坐标系里的左上角 x、左上角 y、右下角 x、右下角 y。直接打印image_info[bbox]把它作为clip传入即可。zoom参数影响导出的清晰度。90 是常见的 PDF 页面基础分辨率zoom2意味着按 2 倍去渲染。如果你需要放大原区域的清晰度可以继续提高 zoom但渲染耗时和内存占用也会增加。4.3 “原图”和“视觉图”的差异在导出素材场景下不能混用做素材导出时我用一个很朴素的判断标准如果对方要的是“可以直接放进设计稿的高清原图”优先用extract_image拿原对象数据。如果图片在 PDF 里已经被裁剪过对方要的是“页面里那个可见区域”那么原对象反而不能直接交付因为裁剪、旋转、缩放都没有体现在导出对象上。这两种结果没有绝对的好坏只是适用场景不同。最稳妥的方式是同一个 PDF 可以同时生成两个文件夹originals存extract_image拿到的原始素材rendered存按页面视觉裁剪出的区域。先让使用者自己看哪个符合需求再根据结果固定代码逻辑。注意如果要处理的是加密 PDF 或设置了使用权限的文档请先确认自己有权访问和提取内容并且使用合法获取的密码进行解密后再操作。不要尝试绕过文档访问控制。5. 别急着选库先了解边界再决定用哪条路线5.1 几个常见 Python 库的大致定位不同库处理 PDF 图片的侧重点不同下面是一个粗粒度的对照库名适合任务主要限制PyMuPDF遍历页面图片对象、提取原图、渲染页面区域不是纯 Python依赖底层二进制库pypdf / PyPDF2处理页面结构、合并拆分、基础图片文件对象提取对图片滤镜、复杂 XObject 的覆盖力不如 PyMuPDFpdfplumber解析文本、表格、页面坐标信息不是为了提取图片而设计图片处理不是最佳选择PyPdfium2页面渲染场景主要用于把 PDF 画成图像不是素材提取首选pdfimages命令行工具用于对照结果不是 Python 库但在批量验证时很好用我的建议是优先用 PyMuPDF 跑通最小流程因为它在“找图片对象”和“渲染页面”两方面都覆盖得比较完整。pypdf 在纯粹做 PDF 元数据操作时也非常方便但用它提取复杂 PDF 里的图片你需要处理更多底层细节。5.2 一个通用排查链路当你发现提取结果不对时按下面这个顺序排查会比乱猜高效很多先看现象是根本没有输出还是图片数量不匹配还是输出文件打不开还是程序直接崩溃。再看输入PDF 是否加密是否损坏文件扩展名是否只是前缀内容是否为空。再确认图片类型页面上到底是不是位图是矢量绘图还是嵌入的图片对象。检查 xref用get_images是否有返回返回的xref是否能被extract_image正常解析。检查格式输出文件的扩展名是否正确文件大小是否为 0。最后用渲染兜底如果对象层拿不到就用get_pixmap渲染页面区域。这套链路看起来简单却能覆盖绝大多数“图片为什么提取不出来”的疑问。5.3 工程化建议把脚本当成可以被下班后重新跑的东西来写一旦处理量到了几十份 PDF 以上脚本就要往“可重复、可审计、可恢复”的方向设计。我会把输出的每一步都记录下来。不是让你上一套复杂日志框架而是在关键节点打印文件名 页码 结果。最少要能回答三个问题哪一份文件跑过了成功多少张失败在哪里。如果同一个任务需要反复修改参数建议使用命令行参数而不是改代码python extract_pdf_images.py --pdf_dir ./input --out_dir ./output --min_width 50同时把输出目录按输入文件名分开避免多份 PDF 的图片互相覆盖。注意如果只是临时跑一次默认配置通常够用。如果要长期维护还需要考虑磁盘空间、重复文件清理、任务断点续跑和关键路径是否存在这些工程问题。最后说一个实际经验我见过很多同学照着一篇教程复制代码把图片提取出来以后存到自己都分不清的地方。下一次遇到新 PDF又把代码翻出来改两行再次碰运气。真正高效的做法其实是在动手前先明确两个定义第一输出物是“原始素材”还是“视觉区域”第二脚本需要满足“单次可用”还是“批量反复使用”。只要这两个问题回答清楚了技术路线基本就定了需要原始素材就去页面资源里找图片对象需要视觉区域就做页面渲染要反复使用就补上日志、去重、异常处理、目录规划和结果校验。PDF 格式本身并不复杂但它隐藏的边界情况非常多。图片提取这件事真正难的不是不会写 Python而是没有意识到 PDF 里“图片数据和图片显示”是两套逻辑。理解了这个你提取图片的准确率和稳定性都会比那些只会复制代码的人高一个档次。
