做 JavaScript/TypeScript 开发的，一旦碰上 PDF 解析、文档结构提取这种需求，第一反应基本都是把它丢给后端或第三方服务去处理。但如果你维护的是一个纯 Node 或者偏前端的工具链，往往还是希望自己能把整条解析链路掌控住。MinerU JS/TS SDK 就是在这种场景下冒出来的，它把 PDF、扫描件、Word 类文档转成干净的 Markdown、JSON 和带布局信息的结果，TypeScript 类型支持也做得够意思，装完就能在 Node 和浏览器两端用起来。这篇文章不是官方文档复读机，而是我实际把 MinerU JS/TS SDK 接进模拟项目后，从安装、初始化、核心 API、OCR 扫描件到踩坑调优的完整过程记录，正在调研文档解析方案的 JS/TS 开发者应该能少走不少弯路。
1. 为什么需要 MinerU 这类工具，以及 SDK 的定位
1.1 传统 PDF 解析为什么总差点意思
我最早做文档解析，用的是 PDF 解析库里最常见的两个方案：一个是 PDF.js，一个是 pdf-lib。它们能干的事其实很基础，就是把 PDF 里每一页的文本抠出来，或者把页面渲染成图片。遇到那种排版规整、文字可选的电子版 PDF，简单场景下凑合能用，但一旦碰上双栏论文、带边框表格、图文混排的合同，抽出来的文本顺序完全乱套，正则都没法救。
更头疼的是扫描版 PDF。很多历史合同、纸质书扫描件，本质上是图片，根本没有文本层，传统解析库只能给你一堆空白。这时候要么接 OCR，要么接云端识别接口，链路一长，维护成本就上去了。当时的感受是：PDF 解析这件事，看起来是个小功能，真正往深了做，其实是版面分析、OCR、表格结构还原、公式识别好几个方向的综合体，单靠前端几个文本抽取库远远不够。
1.2 MinerU 到底解决什么问题
MinerU 本身是一套文档解析引擎，它跟 PDF.js 这种纯文本工具不是一个量级的。简单说，它把扫描件识别、版面检测、文字抽取、标题层级还原、表格转 Markdown、公式识别这些都揉到了一起。你给它一个 PDF，它给你的不是一堆碎片化文本，而是一份有结构的 Markdown 文档，附带每个内容块的位置坐标和类型标注。
我举个例子，之前拿一份双栏的学术论文试，传统方案抽出来的文本经常是左边一栏读半句，右边一栏接半句，段落之间完全是乱的。交给 MinerU 解析后，它会先把版面切成块，识别出标题、段落、图表、公式，再按阅读顺序重排输出。这个能力对做知识库、RAG 检索、文档中台的人来说，几乎是刚需——因为下游不管接向量化还是接人工审阅，都需要一个干净且结构化的输入，而不是原始 PDF 的文本残骸。
1.3 SDK 的价值：不是简单 HTTP 封装
MinerU 最初主要面向 Python 生态，后来有了 JS/TS SDK，我觉得它不只是帮你把 HTTP 请求封装了一下，更大的价值在三个层面。
第一是类型安全。解析结果是个层次很深的嵌套结构，要是直接拿 HTTP 接口拼 JSON，写起来又累又容易错。SDK 把markdown、pages、blocks、bbox这些结果字段都定义成了 TypeScript 类型，编辑器里能直接看到返回结构，写代码踏实很多。第二是生命周期管理。解析一个几十页的 PDF 可能要几十秒甚至几分钟，SDK 内部做了任务状态轮询和结果获取，你不用自己写定时器去查状态。第三是环境适配。它分别处理了 Node 端和浏览器端的输入输出差异，Node 里传文件路径，浏览器里传 ArrayBuffer 或者 Blob，SDK 内部会转换。所以它确实是一个面向 JS/TS 开发者的完整接入层，而不是把 Python 文档里的 curl 示例翻译成 fetch 就完事。
2. 从零开始：环境准备与 SDK 接入
2.1 安装依赖和初始化
先把最基本的跑通。SDK 的安装方式跟其他 npm 包一样，项目根目录执行：
npm install mineru-sdk装完之后初始化客户端。我当时按 SDK 文档里的常规写法，初始化时主要传服务地址和超时时间：
import { MinerU } from 'mineru-sdk'; const client = new MinerU({ endpoint: 'http://127.0.0.1:8000', timeout: 120_000, onError: (err) => { console.error('[mineru] 解析服务异常', err); }, });这里有个很关键的认知：SDK 只是客户端，真正干活的解析引擎跑在服务端。也就是说，你本地或者服务器上必须有一个可供调用的 MinerU 服务，SDK 才能正常工作。第一次用的时候我就踩了这个坑，只装了 SDK，没起服务，结果连初始化都成功了，但一解析就报连接失败。所以先别急着写业务代码，先把服务端弄起来。
2.2 解析服务端的两种部署方式
我实际试下来，服务端有两种比较顺手的部署方式，看你的项目环境选。
第一种是本地 Python 环境直接启动。因为 MinerU 解析引擎有比较多的模型依赖，建议用虚拟环境隔离。启动服务前要做模型权重初始化，这一步耗时比较久，我第一次跑的时候等了好几分钟，之后会缓存到本地，后续启动就快很多。启动起来的服务默认监听127.0.0.1:8000，SDK 里的endpoint指的就是这个地址。
第二种是用容器方式部署。如果你有容器化环境，用官方镜像起服务会更干净。容器启动后同样暴露 8000 端口：
docker run -d -p 8000:8000 --name mineru-service mineru/server容器方案的好处是环境隔离彻底，不会污染宿主机器，模型依赖都在镜像里。缺点是镜像体积比较大，第一次拉取要看网速。如果只是本地开发调试，直接用 Python 虚拟环境方案就够了，调试起来也方便，能直接看服务端日志。我当时是本地 Python 起服务，业务代码在 Node 服务里跑，两边配合着调试，效率还行。
2.3 浏览器端与 Node 端的使用差异
MinerU JS/TS SDK 比较大的一个设计点是区分了运行环境，因为浏览器和 Node 的输入输出能力差别很大。
在 Node 端，你可以直接传文件路径，SDK 内部会读文件转成请求所需的格式；也可以传 Buffer。比如你从某个存储服务下载了 PDF，拿到的是 Buffer，直接丢给 parse 接口就行。在浏览器端，拿不到文件路径，常见做法是把 File 对象转成 ArrayBuffer，或者传一个可访问的 URL 地址，SDK 会去拉取文件。
我在一个实际场景里验证过：前端页面用户上传一个 PDF，前端直接调用parse(file)，SDK 里会自动读成二进制数据去请求服务；如果是在 Node 脚本里做批处理，直接传绝对路径反而更方便。有一个细节要注意：浏览器端上传超大文件时，如果服务端没有做请求体大小限制调整，容易遇到413 Payload Too Large这种错误，这时候需要去服务端调整入站请求大小的配置。Node 端往往没有这个问题，因为文件流在服务端内部走的是本地路径读盘。
3. 核心 API 实操：从传入文档到拿到结构化结果
3.1 三种输入方式：文件路径、Buffer、URL
MinerU JS/TS SDK 的parse接口支持多种输入，这是它比直接调用 HTTP 舒服的地方。我整理了一份符合常见实践的示例：
// 方式一：Node 端传文件路径 const result = await client.parse('/data/input/sample.pdf', { enableOCRFallback: true, }); // 方式二：Node 端传 Buffer const buf = await fs.promises.readFile('/data/input/sample.pdf'); const result2 = await client.parse(buf, { dpi: 120, }); // 方式三：浏览器端传 URL const result3 = await client.parse('https://example.com/files/demo.pdf', { enableTable: true, });SDK 内部拿到文件路径会做读取，拿到 URL 会做请求拉取，拿到二进制数据则会按字节流直接提交。对开发者来说，这意味着无论你手上是磁盘文件、内存数据，还是一个远程链接，都能用同一套 API 去处理，不用自己写各种格式转换。
初次调用时，服务端需要加载模型，响应会比较慢，相当于一个“热身”过程。我在实际使用中遇到过一个现象：同一个服务，第一次解析一份小 PDF 花了 30 秒，后面再解析同样的文件就快很多。这是模型缓存的正常表现，不是 SDK 出了问题，所以做压测或者批量跑之前，最好先预热一次。
3.2 参数应该怎么调：dpi、OCR、表格识别
parse的第二个参数是解析选项，我建议重点关注下面几个，别的参数保持默认就行。
dpi控制渲染分辨率，默认通常不需要动，但扫描版 PDF 如果你觉得识别效果不佳，可以提高到 144 或更高。分辨率越高识别越准，代价是更慢、更吃内存。enableOCR或者传enableOCRFallback，代表当 PDF 没有文本层时自动走 OCR。我的建议是：文本型 PDF 就关掉 OCR，扫描型就打开，但不要全开，全开会增加不必要的计算量。enableTable打开表格识别，它会把表格还原成 Markdown 表格语法，而不是把表格区域当成普通文本抽取，这个对做文档结构化特别重要。
还有语言参数，识别中文文本时指定语言模型会明显改善准确率。我用的是lang: 'zh'这种写法，你可以根据 SDK 版本查一下具体枚举。
3.2 节最后给个实操心得：参数不是越高越好。我试过把 dpi 和 OCR 全部开到最大处理一个网页导出的 PDF，结果速度和内存都爆了，最后一查发现那个文件本身是文本型，根本不需要 OCR。调参前先判断文件的“类型画像”，能省下大量无谓计算。
3.3 读懂拿到手的解析结果
解析完的结果不是一段字符串就完了，而是一个嵌套结构。我按常规返回结构整理出一个简化版类型：
interface MinerUResult { markdown: string; // 完整 Markdown 内容 pages: MinerUPage[]; // 分页信息 metadata: { modelName: string; durationMs: number; inputType: string; }; } interface MinerUPage { pageNo: number; width: number; height: number; blocks: MinerUBlock[]; } type MinerUBlock = | { type: 'text'; bbox: [number, number, number, number]; content: string } | { type: 'table'; bbox: [number, number, number, number]; content: string } | { type: 'image'; bbox: [number, number, number, number]; path: string } | { type: 'formula'; bbox: [number, number, number, number]; latex: string };如果你只需要在页面上展示，markdown字段拿来渲染可以直接覆盖大多数场景。pages里的坐标和类型，适合做更细粒度的二次加工，比如你想定位某一页的某个表格，或者想把图片单独抽出来，这时候bbox就是关键。metadata里的durationMs可以用来统计耗时，做监控上报也很好用。
有一点特别提醒：markdown字段有时会很大，如果一个 100 页的 PDF，产物可能到几 MB 的量级。如果你的下游不支持这么大的单字段，可以考虑分页处理，用pages数组按照页号切分后再逐段输出，既能控制单次传输体积，也方便对单页做缓存。
4. 实战：扫描版 PDF 必须走 OCR，完整流程可参考
4.1 什么情况必须开 OCR
扫描版 PDF 和原生 PDF 本质上不是一回事。原生 PDF 里有文本指令，是可以直接抽取的；扫描版 PDF 每一页都是一张图片，没有任何文本信息。如果你解析完发现markdown字段几乎为空，先别怀疑 SDK 坏了，大概率就是碰到了扫描版，而你没开 OCR。
判断是不是扫描版的方法也简单，把 PDF 用 PDF.js 渲染一次，或者直接用文本抽取库读一下，如果文本长度为 0，基本可以断定是扫描件。还有一种是“半扫描”状态，文件里有些页是文本层，有些页是图片，常见于那种扫描后又用 OCR 软件处理了一半的文档。这种情况我的经验是直接开 OCR fallback，让文本页走文本抽取，图片页走 OCR，两边都不耽误。
4.2 实操：识别中文扫描件的关键配置
我实际处理过一份中文扫描合同，三十多页，当时是这么调参的：
const result = await client.parse('/data/input/contract.pdf', { dpi: 144, lang: 'zh', enableOCRFallback: true, enableTable: true, });这里有几个需要注意的地方。dpi我提到了 144，因为扫描件原图分辨率如果偏低，文字边缘会有锯齿，OCR 容易认错字；但不要盲目拉到 300，我曾经试过，单页耗时直接翻倍，而且对识别率的提升并不明显。lang: 'zh'必须指定，不指定的话中文识别效果会明显打折。enableOCRFallback让 SDK 在缺文本层时自动切换 OCR，比手动判断再二次调用省事很多。
扫描件解析的耗时会比文本 PDF 高一个数量级。我实际测下来，一份三十页的中文扫描合同，走 OCR 大概需要一分半到两分钟。这里有个心态问题：如果你把它塞进请求里同步等待，浏览器端体验会非常差。所以扫描件场景更合适的方式是异步任务化：提交后返回任务 ID，前端轮询或者用 WebSocket 推送完成状态，而不是让用户干等。
4.3 并发与批量解析策略
批量解析是另一个必须提前考虑的工程问题。也许你会忍不住一次性并发提交几十个文件，我劝你别这么干。文档解析是 CPU 密集和内存密集的任务，并发量上去后，服务端会出现两种典型故障：一是 CUDA 显存不够挂掉（如果你用的是 GPU 推理环境），二是普通 CPU 环境下直接内存溢出。我踩过一次并发 20 个任务把服务打死的坑，服务重启后任务全部丢了，差点把整个批处理管道搞崩。
建议用一个简单的并发池来限制任务数，我当时的做法是：
const pool = new ConcurrencyPool({ limit: 2 }); for (const file of fileList) { pool.add(() => client.parse(file, parseOptions)); }把并发控制在 2 到 3 个比较稳，性能和数据安全之间有个平衡点。如果你用的是容器服务，还要注意容器内存 limit，别只看 CPU 占用。
5. 常见问题与排查技巧实录
5.1 中文乱码、表格错乱
中文乱码是文档解析里最容易碰到的问题，但原因往往不在解析环节。很多 PDF 的中文字体没有正确嵌入，或者使用了自定义编码子集，导致文本层缺失。这时候光靠文本抽取只能得到乱码或用类似uniXXXX的占位符，必须把该页视作图片页走 OCR，才能拿到真实字符。
表格错乱则和后续处理有关。MinerU 输出的表格已经是 Markdown 表格结构，但如果源 PDF 里的表格有合并单元格，解析出来的 Markdown 表格可能简化成普通行列。如果你要还原合并结构，需要去blocks里找type: 'table'的块，结合bbox坐标核对单元格顶点，这是比直接渲染更可控的方案。我当时的做法是把表格块单独抽出来，再按坐标和内容自己拼一次结构，虽然工作量多了一点，但准确率明显上去。
5.2 大文件内存占用过高
大文件是内存杀手。一份几百页的高分辨率扫描 PDF，如果一次性全部丢进去解析，服务端内存会像坐火箭一样往上飙。我自己遇到过 Node 进程内存占用超过 80% 的情况，最后排查下来不是 SDK 的锅，而是把整个 PDF 的渲染缓存全堆在内存里了。
个人处理的思路是：先看页数，超过某个阈值就分页或分片解析。MinerU 本身支持从 PDF 里抽页签成子文件，SDK 侧可以先只解析前面几十页，或者用工具把 PDF 按需切分后再提交。注意切分 PDF 的时候要保证页面渲染参数一致，否则不同批次的结果坐标体系可能有偏差。另外降低dpi也能显著减少内存占用，对扫描件来说，144 到 200 之间相对安全，再往上就要谨慎了。
5.3 调用超时与重试策略
解析一个超大 PDF 耗时很长，默认的 HTTP 超时时间很容易触发。我建议初始化客户端时就把超时时间设置得宽裕一点，像前面示例里那样设置为 120 秒甚至更高。但这个超时时间也不是越高越好，太高了，客户端挂着等不仅占连接，出了问题也不容易暴露。更好的做法是在协议层面轮询或拿到任务 ID 后异步查询。
重试策略要慎重。文档解析不是幂等操作，同样的文件重复解析，既浪费算力又可能产生不一致的结果。我发现超时往往发生在模型推理阶段，这时候服务端可能已经在干活了，只是客户端等不及断开了。所以如果超时了，先查服务端状态，再决定要不要重试，而不是无脑打重试循环。我自己的策略是：重试最多一次，且间隔至少几秒，给服务端留出缓一口气的时间。
5.4 结果为空或者解析中断
有一种很容易忽略的情况：文件本身是加密 PDF，或者带有打开密码。解析引擎没有密码是连文本层都读不出来的，结果自然为空。这种情况要先确认文件是否允许访问。另外也有些 PDF 文件结构本身损坏，看起来能打开，但页面对象缺失，结果解析到某一页直接中断。
排查这类问题的常规做法是：先拿一个小文件测试你的调用链路，排除 SDK 和服务端配置问题；如果小文件正常而特定文件失败，基本可以锁到文件本身。日志是这里最关键的信息来源，服务端的警告日志里如果出现与页面解析相关的具体异常，基本就能定位是哪一页出了岔子。我会建议在实际生产环境里，把失败文件的原始路径和解析错误码一起记录下来，方便复现。
6. 性能调优与落地建议
6.1 解析结果的缓存设计
文档解析的算力成本不低，同一个文件反复解析完全没必要。缓存这一步建议从接入第一天就做，不然后面补会很痛苦。当时我做的方案是用文件内容的哈希作为 Key，解析完成后把markdown和pages结果序列化存起来，下次请求相同文件直接走缓存。
哈希计算在 Node 端很快，用crypto.createHash('sha1')对文件 Buffer 算一下就行。要注意的是，仅仅用文件名做 Key 不可靠，因为不同路径下可能是同一个文件，甚至同一个路径下的文件内容可能被更新过。我用的是 文件大小 + 文件哈希 的双重判断，先比大小，再比对哈希，虽然多一点点计算，但能避免误命中。
6.2 按文件类型分流的解析策略
上面的经验里我反复提到一个词：判断文件类型画像。这里单独展开说。文本型 PDF 走基础解析，扫描型 PDF 走 OCR，本身就带有图片的 PPT 或 Word 导出的 PDF，则建议开启表格识别和图片抽取，才能得到完整的结构化结果。也就是你可以在进入解析前先做一次便宜的预检，比如只抽前两三页看看有没有文本层，有就关 OCR，没有就开 OCR。
这听起来像多了一步操作，但在批量场景下，省下的算力非常可观。我实测过一个三百份混合 PDF 的批量任务，预检之后再分流，总耗时比全量开 OCR 减少了大概百分之四十。所以这个“画像”步骤很值得投入。
6.3 几条实操层面的个人建议
最后聊几条不太好写进官方文档、但实战中很有用的经验。
第一，起步阶段不要追求全功能调参。先把最朴素的解析跑通，拿到一份“能看”的 Markdown 输出，再逐步打开 OCR、表格识别这些开关，每开一个就对比一次输出差异，不然参数一多，出了问题你连是哪个环节的锅都分不清。第二，一定要看坐标而不是只看文字流。很多文档解析需求，最终卡在“文字对了但顺序不对”，这个时候bbox是唯一可信的参照，文字流可能是经过模型重排的，但坐标不会说谎。第三，服务端日志是排查问题的第一抓手。SDK 报错信息往往比较外层，真正的根因藏在服务端的模型推理日志里，遇到诡异问题先翻服务端日志，能帮你省下大量猜测时间。
从我自己把 MinerU JS/TS SDK 接入真实项目的体验看，这套工具链的最大价值不只是帮你从 PDF 里抠出文字，而是真正把文档解析这件苦力活变成了一个数据类型清晰、结果可预测的工程接口。刚上手时，你会觉得流程有点长、第一次调用有点慢，这都很正常。但等你把服务部署、参数分流、缓存和并发都理顺之后，再回头看那些当初堆了一堆正则脚本的“老路子”，大概率就不想回去了。
