MinerU输出图片丢失？资源路径配置错误排查教程
你是不是也遇到过这样的情况：用 MinerU 提取 PDF 时，命令跑得飞快，Markdown 文件生成了，公式也识别出来了，但打开一看——图片全没了？或者只有一堆占位符，点开却提示“文件不存在”？别急，这大概率不是模型能力问题，而是资源路径配置没对上。本文就带你从零开始，手把手排查 MinerU 输出图片丢失的常见原因，重点聚焦在镜像环境下的路径逻辑、配置文件设置和实际操作细节，不讲虚的，只给能立刻验证、马上修复的方案。
1. 问题定位：为什么图片会“消失”？
MinerU 的 PDF 提取流程其实分两步走：先识别内容结构，再按需导出资源。它不会把图片直接嵌进 Markdown，而是生成独立的图片文件（PNG/JPEG），再在 Markdown 中用相对路径引用。所以“图片丢失”，本质是Markdown 里写的路径找不到对应文件。常见原因有三类：
- 路径写错了：
magic-pdf.json里指定的output-dir和你执行命令时用的-o参数不一致； - 目录权限或结构不对：
./output目录没被正确创建，或子目录images/缺失； - 模型输出路径硬编码冲突：某些版本的
magic-pdf会默认把图片存到./output/images/，但如果你手动指定了-o ./output/subdir，它可能不会自动创建subdir/images/。
我们用的是 CSDN 星图预装的MinerU 2.5-1.2B 深度学习 PDF 提取镜像，这个镜像已深度预装 GLM-4V-9B 模型权重及全套依赖环境，真正实现“开箱即用”。你无需繁琐配置，只需通过简单的三步指令即可在本地快速启动视觉多模态推理，极大地降低了模型部署与体验的门槛。但正因为它“太省心”，很多路径细节被封装起来了，反而容易忽略关键配置点。
2. 镜像环境下的路径逻辑详解
要修好图片路径，你得先搞清楚这个镜像里“路”是怎么铺的。我们进入/root/workspace后执行的每一步，其实都在一个精心设计的路径体系里运行。下面这张表，帮你理清所有关键路径及其作用：
| 路径位置 | 默认值 | 作用说明 | 是否可修改 |
|---|---|---|---|
| 工作根目录 | /root/workspace | 镜像启动后默认所在位置，所有操作建议从此处开始 | 否（镜像固定） |
| MinerU 主程序目录 | /root/MinerU2.5 | 包含mineru命令、示例文件test.pdf及核心脚本 | 否（预装固定） |
| 模型权重目录 | /root/MinerU2.5/models | 存放MinerU2.5-2509-1.2B和PDF-Extract-Kit-1.0等全部权重 | 是（通过magic-pdf.json控制） |
| 配置文件路径 | /root/magic-pdf.json | 全局配置中心，决定设备模式、模型路径、输出行为 | 是（必须编辑） |
| 默认输出根目录 | ./output（相对路径） | 执行mineru -o ./output时，实际创建的目录位置 | 是（由-o参数决定） |
注意一个关键细节：mineru命令中的-o参数，指定的是整个输出根目录，而图片、公式、表格等资源，会在这个根目录下自动创建子文件夹。比如：
- 你运行
mineru -p test.pdf -o ./output --task doc - 它会在当前目录（即
/root/MinerU2.5）下创建./output/ - 然后在里面生成：
./output/test.md+./output/images/+./output/formulas/+./output/tables/
所以，如果你在/root/workspace下执行命令，./output就会建在/root/workspace/output；但如果你先进入/root/MinerU2.5，再执行，./output就在/root/MinerU2.5/output—— 这个差别，直接决定你的 Markdown 里./images/xxx.png能不能被正确找到。
3. 三步实操排查与修复
现在，我们来动手验证并修复。整个过程不需要重装、不改代码，只靠检查、微调、重跑三步。
3.1 第一步：确认当前工作路径与输出路径是否匹配
打开终端，先确认你此刻在哪：
pwd你应该看到类似/root/MinerU2.5（推荐）或/root/workspace（也可行，但需注意路径）。接着，检查你准备用的输出目录是否存在且可写：
ls -la ./output如果提示No such file or directory，说明目录还没创建，这是正常的——mineru会在运行时自动创建。但如果它创建失败（比如权限不足），就会静默跳过资源导出。所以，我们手动创建一次，并赋予写权限：
mkdir -p ./output chmod 755 ./output小贴士：
mkdir -p会递归创建目录，即使父目录不存在也不会报错；chmod 755确保所有用户都能读取和执行（进入），组和其他用户也能读取，避免后续写入被拒。
3.2 第二步：检查并修正magic-pdf.json配置
配置文件是路径逻辑的“总开关”。它位于/root/magic-pdf.json，我们用nano直接编辑：
nano /root/magic-pdf.json重点关注以下两个字段：
{ "models-dir": "/root/MinerU2.5/models", "device-mode": "cuda", "output-dir": "./output", "table-config": { "model": "structeqtable", "enable": true } }models-dir：确保指向/root/MinerU2.5/models，这是镜像预装的模型位置，不要改成其他路径。output-dir：这是关键！它必须和你命令中-o后面的路径完全一致。如果你打算用./output，这里就填"./output"；如果你要用绝对路径如/root/output，那这里也得同步改成"/root/output"，并且确保该路径存在、可写。
保存退出（Ctrl+O → Enter → Ctrl+X）。
3.3 第三步：用标准命令重跑，并验证输出结构
回到/root/MinerU2.5目录，执行标准三步：
cd /root/MinerU2.5 mineru -p test.pdf -o ./output --task doc ls -R ./output最后一条ls -R会递归列出./output下所有内容。你期望看到的结构应该是：
./output: test.md images/ formulas/ tables/ ./output/images: test_001.png test_002.png ... ./output/formulas: test_formula_001.png ... ./output/tables: test_table_001.png ...如果images/目录下有 PNG 文件，但test.md里还是显示找不到——那问题很可能出在Markdown 查看方式上。VS Code 或 Typora 等编辑器默认支持相对路径渲染，但如果你用cat test.md或网页直接打开，路径就失效了。正确做法是：用支持本地资源渲染的编辑器打开test.md，或把整个./output目录拖进浏览器（此时路径才真正生效）。
4. 进阶技巧：自定义图片存放位置与路径重写
有时候，你希望图片统一放在./assets/images/，而不是默认的./output/images/。MinerU 本身不支持直接指定图片子目录，但我们可以通过软链接（symbolic link）巧妙解决：
# 先创建你想要的结构 mkdir -p ./assets/images # 把默认的 images 目录链接过去 rm -f ./output/images ln -s ../assets/images ./output/images这样，mineru还是往./output/images/写，但实际文件都落在./assets/images/下，而test.md里的路径./images/xxx.png依然有效。
另一个实用技巧是批量处理时统一路径前缀。比如你要处理 10 个 PDF，希望所有 Markdown 都引用https://cdn.example.com/pdf/开头的图片 URL。这时可以先让 MinerU 正常导出，再用sed批量替换：
sed -i 's!\!\!g' ./output/*.md这条命令会把所有./output/*.md文件里的./images/替换成https://cdn.example.com/pdf/，适合部署到网站或知识库的场景。
5. 常见报错速查表
| 报错现象 | 最可能原因 | 一句话修复方案 |
|---|---|---|
FileNotFoundError: [Errno 2] No such file or directory: './output/images' | ./output目录不可写，或magic-pdf.json中output-dir路径错误 | 手动mkdir -p ./output && chmod 755 ./output，并核对output-dir字段 |
Markdown 中图片路径为./images/xxx.png，但点击打不开 | 在终端用cat或浏览器直接打开.md文件，未启用本地资源渲染 | 用 VS Code、Typora 等编辑器打开，或把整个./output目录拖入浏览器地址栏 |
提取后./output/images/为空，但test.md里仍有图片占位符 | GPU 显存不足导致图片提取阶段被跳过 | 编辑/root/magic-pdf.json，将"device-mode": "cuda"改为"cpu"，重试 |
图片文件存在，但 Markdown 里路径是../images/xxx.png（多了一个..） | 你在/root/workspace下执行了mineru -o ./output，但test.pdf在/root/MinerU2.5/，路径解析错乱 | 统一在/root/MinerU2.5目录下执行所有命令，避免跨目录调用 |
6. 总结
MinerU 输出图片丢失，90% 的情况不是模型不行，而是路径没对齐。本文带你厘清了镜像环境下的四层路径关系（工作路径、模型路径、配置路径、输出路径），并通过三步实操（确认路径→修正配置→验证结构）给出了可立即落地的解决方案。记住三个核心原则：
- 路径一致性：
magic-pdf.json里的output-dir、命令里的-o参数、你实际查看文件的位置，三者必须指向同一物理目录； - 目录可写性：
./output不仅要存在，还要有写权限，否则资源导出会静默失败； - 查看方式匹配：Markdown 里的相对路径，只在支持本地资源渲染的环境中才有效，别用纯文本工具“验货”。
现在，你可以放心地把test.pdf换成你自己的技术文档、论文或产品手册，一键提取，图文并茂。MinerU 的强大，不该被一个小小的路径问题挡住。
--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
