为什么用MinerU提取图片失败？路径配置避坑指南
你是不是也遇到过这样的情况：明明PDF里清清楚楚放着一张图，运行mineru -p test.pdf -o ./output --task doc后，输出的Markdown里却只有文字、表格和公式，唯独不见那张图？更奇怪的是，./output文件夹里连个图片子目录都没有，images/目录压根没生成——不是说好“支持图片提取”吗？
别急，这大概率不是模型能力问题，而是路径配置踩了隐形坑。MinerU 2.5-1.2B 这个镜像本身非常强大，预装了GLM-4V-9B视觉模型和全套依赖，开箱即用体验极佳。但它的图片提取逻辑对路径极其敏感——一个斜杠写错、一个目录权限没设对、甚至当前工作目录没切准，都会让图片“凭空消失”。
本文不讲高深原理，只聚焦一个最常被忽略的实操细节：为什么图片提不出来？哪里配错了？怎么三步快速验证并修复？全程基于CSDN星图上已验证可用的「MinerU 2.5-1.2B 深度学习 PDF 提取镜像」，所有操作均可直接复现。
1. 图片提取失败的真相：不是模型不行，是路径没走通
很多人以为MinerU提取图片失败是因为模型不够强，或者PDF质量差。其实，在这个预装镜像中，90%以上的图片提取失败，根源都在路径链路上断开了。
MinerU的图片提取不是“顺手一存”，而是一套严格分工的流程：
- 第一步（识别定位）：模型在PDF中检测出图片区域，记录坐标和原始流数据；
- 第二步（解码保存）：调用
magic-pdf底层库，将图片数据解码为PNG/JPEG，并按规则写入磁盘； - 第三步（路径映射）：在生成的Markdown中，把本地图片路径自动转为相对链接，比如
。
而问题就出在第二步和第三步之间：如果magic-pdf找不到合法的、可写的图片输出目录，它会静默跳过保存，既不报错，也不生成images/文件夹——你看到的只是“图片不见了”。
这不是Bug，是设计使然：它默认信任你已按规范准备好输出环境。而镜像里预设的路径规则，恰恰和很多人的直觉操作不一致。
2. 镜像默认路径结构与三个关键陷阱
先看镜像启动后的标准路径布局（进入容器后执行ls -l /root/即可确认）：
/root/ ├── MinerU2.5/ ← 主程序目录（含mineru命令） ├── workspace/ ← 默认工作区（但非MinerU默认读取点） ├── magic-pdf.json ← 全局配置文件（核心！） └── test.pdf ← 示例PDF（放在/root/下才保险）这里埋着三个新手必踩的坑：
2.1 陷阱一：误用workspace作为工作目录
镜像默认登录路径是/root/workspace，很多人习惯性在这里放PDF、跑命令：
cd /root/workspace mineru -p test.pdf -o ./output --task doc # ❌ 错！问题在哪？
MinerU 2.5 的--task doc模式会优先读取当前目录同级的magic-pdf.json。而/root/workspace下没有这个文件，它会退回到/root/去找。但此时-o ./output的./output是相对于/root/workspace的，而图片保存逻辑却在/root/上下文中执行——路径错位，图片写入失败。
正确做法：所有操作必须在/root/根目录下进行
cd /root mineru -p test.pdf -o ./output --task doc # 对！2.2 陷阱二：-o参数用了绝对路径却权限不足
有人想省事，直接指定绝对路径：
mineru -p test.pdf -o /home/user/output --task doc # ❌ 危险！镜像中/home/user/目录默认不存在，且mineru进程以root用户运行，但magic-pdf底层库在创建嵌套目录时，若父目录不可写或不存在，会直接放弃创建images/子目录。
安全做法：永远使用相对路径，且确保当前目录可写
cd /root mkdir -p output # 显式创建，避免静默失败 mineru -p test.pdf -o ./output --task doc # 输出到当前目录下的output/2.3 陷阱三：magic-pdf.json中models-dir路径错误导致OCR降级
虽然图片提取主要靠视觉模型，但复杂PDF中的图表、扫描件需要OCR辅助定位。配置文件里这一行很关键：
"models-dir": "/root/MinerU2.5/models"注意：镜像中真实模型路径是/root/MinerU2.5/，而models子目录需要手动创建并放入权重。如果你没运行过初始化脚本，/root/MinerU2.5/models可能为空——此时OCR模块失效，图片区域识别不准，自然无法提取。
验证方法：进容器后执行
ls -l /root/MinerU2.5/models/ # 应看到类似：pdf-extract-kit-1.0/ mineru-2509-1.2b/若为空，请先运行镜像自带的初始化命令（已在/root/MinerU2.5/下）：
cd /root/MinerU2.5 bash setup_models.sh # 自动下载并解压所需模型3. 三步快速验证：你的图片路径是否真的通了
别猜，动手验证。以下三步，5分钟内确认路径链路是否完整：
3.1 第一步：检查配置文件是否生效
执行命令查看MinerU实际加载的配置路径：
cd /root mineru --help | grep "config" # 输出应包含：--config CONFIG, -c CONFIG config file path (default: /root/magic-pdf.json)再确认文件内容是否被正确读取：
cat /root/magic-pdf.json | grep "models-dir" # 必须输出： "models-dir": "/root/MinerU2.5/models"如果显示其他路径（如./models），说明你之前在别的目录下执行过命令，残留了临时配置。删掉它：
rm -f ./magic-pdf.json3.2 第二步：强制触发一次最小化图片提取
不用处理大PDF，用镜像自带的test.pdf做最小验证：
cd /root # 清空旧输出 rm -rf ./output # 关键：加--debug参数，看详细日志 mineru -p test.pdf -o ./output --task doc --debug 2>&1 | grep -i "image\|img\|save"正常日志应包含类似行：
INFO Saving image to: ./output/images/fig1.png INFO Markdown link generated: ❌ 若无Saving image to字样，说明图片保存环节被跳过——立即回头检查2.1和2.2步。
3.3 第三步：手动创建测试图片目录，验证写入权限
即使日志显示保存成功，也要验证磁盘是否真能写入：
cd /root mkdir -p ./output/images echo "test" > ./output/images/test.txt ls -l ./output/images/ # 应看到test.txt如果报Permission denied，说明容器挂载卷有写权限限制。此时需在启动容器时加参数：
docker run -v $(pwd):/root/output:rw ... # 确保挂载时带rw（读写）4. 终极解决方案：一份可直接粘贴的健壮执行脚本
把上面所有要点封装成一个防错脚本，每次提取前运行它，一劳永逸：
#!/bin/bash # save as /root/run_mineru.sh set -e # 任一命令失败即退出 echo " 步骤1：切换到安全根目录" cd /root echo "🔧 步骤2：确保输出目录存在且可写" mkdir -p ./output ./output/images touch ./output/images/.write_test && rm ./output/images/.write_test echo "⚙ 步骤3：验证配置文件路径" if [ ! -f "/root/magic-pdf.json" ]; then echo "❌ 错误：/root/magic-pdf.json 不存在！请检查镜像是否完整" exit 1 fi echo "📄 步骤4：执行提取（自动启用debug日志）" if [ -z "$1" ]; then echo " 未指定PDF文件，使用默认 test.pdf" PDF_PATH="test.pdf" else PDF_PATH="$1" fi echo " 开始提取：$PDF_PATH" mineru -p "$PDF_PATH" -o ./output --task doc --debug 2>&1 | tee ./output/extract.log echo " 提取完成！结果在 ./output/ 目录" echo " - Markdown: ./output/test.md" echo " - 图片目录: ./output/images/" echo " - 详细日志: ./output/extract.log"赋予执行权限并运行：
chmod +x /root/run_mineru.sh /root/run_mineru.sh # 使用默认test.pdf # 或指定文件 /root/run_mineru.sh my_doc.pdf这个脚本会：
- 自动检测并修复路径问题；
- 强制创建
images/目录，避免静默失败； - 保存完整日志供回溯；
- 所有错误立即中断，不让你在黑盒中瞎猜。
5. 常见问题速查表：对号入座，秒级定位
| 现象 | 最可能原因 | 一句话修复 |
|---|---|---|
./output里只有.md文件，没有images/文件夹 | 当前工作目录不是/root/，或-o用了非法绝对路径 | cd /root && mineru -p test.pdf -o ./output --task doc |
日志报OSError: [Errno 2] No such file or directory: './output/images' | output目录存在，但images子目录未被自动创建 | 手动mkdir -p ./output/images后再运行 |
提取的Markdown里图片链接是，但点开404 | images/目录存在，但PDF中图片实际被存到了./output/xxx.png（平铺） | 检查magic-pdf.json中是否误删了"images-dir": "images"字段 |
| 处理扫描版PDF时图片全是乱码或空白 | OCR模型未加载，models-dir指向空目录 | 运行/root/MinerU2.5/setup_models.sh补全模型 |
| GPU显存爆满，提取中途崩溃 | magic-pdf.json中device-mode仍为cuda，但显存不足 | 改为"device-mode": "cpu"，重试 |
记住：MinerU 2.5-1.2B 是一个为生产环境打磨过的工具，它的“静默失败”不是缺陷，而是对工程鲁棒性的要求——它假设你已准备好干净的路径环境。而这份指南，就是帮你把那个“准备好的环境”真正落地。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
