anydoc 深度解析：Firecrawl 开源 14 格式文档转 Markdown 引擎，4.4 毫秒背后的 Rust 设计与本地实操指南

本文由 辛梓煜@词元2号站（www.ciyuanerhao.com）撰写，转载请注明出处。

快速摘要（先看结论）： 2026 年 8 月，做网页抓取出身的 Firecrawl 团队开源了一款名为 anydoc 的本地文档解析引擎，短短十来天在 GitHub 上收获 1.5 万 Star。它能把 Word、PPT、Excel、OpenDocument、RTF、EPUB、CSV 以及文本型 PDF 共 8 大类 14 种扩展名的文件，统一转换成结构干净的 GitHub Flavored Markdown，官方基准测试里单份文档转换中位耗时仅 4.4 毫秒。核心设计是"统一文档模型"：所有格式先解析成同一种中间结构，再由同一套序列化器输出 Markdown，所以修一个表格 Bug 所有格式同时受益。工具是纯 Rust 写的，不依赖任何机器学习模型和外部服务，文件全程本地处理；提供 CLI、Node.js、Python、浏览器 WebAssembly 四种接入方式，还能一键装进 Claude Code、Codex 这类 Agent 工具当 Skill 用。我拿到手实测了 docx、pptx、xlsx、rtf、odt、epub 六类文件，转换质量稳，速度肉眼无感，唯一要注意的是扫描件纯图片 PDF 和加密文档它处理不了。想看完整拆解，往下翻。

第一章 AI 时代的文档解析困境：为什么 AI 读不懂你的文件

这两年只要碰过 RAG 知识库或者给大模型喂过资料的人，基本都撞上过同一堵墙：AI 很聪明，但它读不懂我们日常办公用的那些文件。

你说"帮我把这份 Word 合同里的关键条款整理出来"，模型可能一脸懵；你说"分析一下这个 Excel 表格的销售趋势"，它更是无从下手。不是模型笨，而是 .docx、.pptx、.xlsx 这些格式本身就不是给人脑之外的读者准备的。它们本质上是压缩过的 XML 包，里面混着样式定义、字体信息、修订记录、嵌入图片，真正的文字内容只是其中一小撮。PDF 就更不用说了，它的排版是"画"出来的，文字、表格、图片的位置全靠坐标描述，机器想直接抽内容，就跟隔着毛玻璃看字一样费劲。

我自己做过一阵子知识库项目，最深的体会是：给 AI 喂数据这件事，80% 的功夫其实花在"把文件变成 AI 能读的样子"上，而不是模型本身。 早期我的做法很原始：Word 用 python-docx 抽文本，Excel 用 openpyxl 遍历单元格，PPT 用 python-pptx 一层层挖 shape，PDF 还得另外接解析库。每种格式一套工具，代码越写越长，坑却一个没少踩。

我把这些年在文档解析上踩过的坑整理了一下，基本就这几种：

我自己就吃过一次大亏。有一回给公司做产品知识库，批量导入了两百多份历史文档，其中一份 Excel 里有个几十行的销售数据表，解析的时候表格被拆得七零八落，一半数据直接丢了。表面上看转换过程"成功"了，没有报错，结果后面同事问"去年华南区 Q3 的销售额是多少"，系统答不上来——我排查了 embedding、检索排序、分块策略，折腾一整天，最后才发现是源头解析就把数据丢了。那种感觉，就像查了半天电路故障，最后发现是电源插座松了，特别无力。

这些坑叠加起来，最坑的是它还不容易被发现。表格转丢一半，你不逐行核对根本看不出来；等检索的时候答案错了，你还以为是 embedding 或者 prompt 的问题，排查半天才发现源头在解析环节。这种"隐形错误"比直接报错更折磨人。

所以当 Firecrawl 开源 anydoc 的时候，我第一反应是：这个方向终于有人认真做了。它解决的正是上面表格里那一整排问题——不管什么格式进来，出去的都是一份干净、结构完整的 Markdown。Markdown 这东西大家不陌生，就是带 # 标题、- 列表、| 表格符号的纯文本，人类看着清爽，AI 读起来也几乎没有歧义，算是目前大模型世界里最接近"通用语言"的文档格式之一。

在正式介绍工具之前，先把它的来历和基本盘说清楚，方便你判断值不值得花时间看下去。

第二章 anydoc 是什么：Firecrawl 开源的 14 格式文档解析引擎

先说背景。Firecrawl 这家团队，做爬虫和网页转 Markdown 的人应该都熟，他们的招牌产品就是把任意网页抓下来、转成结构化 Markdown 给 AI 用的抓取服务，在 RAG 数据管道圈子里口碑一直不错。2026 年 8 月，他们把手伸向了本地文档这一块，开源了 anydoc，项目上线不到两周 GitHub Star 数就冲过了 1.5 万——这个速度放在开源圈里算是相当炸裂的，侧面也说明"文档转 Markdown"确实是很多人压在心里的痛点。

anydoc 的官方定位一句话就能说清：把 Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV 和文本型 PDF 统一转换成干净的 GitHub Flavored Markdown 的快速本地库。 它采用 MIT 许可证，纯 Rust 编写，没有任何机器学习模型依赖，也不需要调外部服务，单份文档转换中位耗时 4.4 毫秒——这个数字后面单独讲，先看它能处理什么。

2.1 一张表看懂格式覆盖

anydoc 声称支持 8 大类、14 种扩展名，我把清单整理如下：

这里有两个细节值得单独拎出来说。

第一，.doc、.ppt、.xls 这种 2003 年的老格式居然都支持。老格式是二进制结构，解析难度比新格式的 XML 高一个量级，很多工具直接放弃。anydoc 全给兜住了，对大量还在用老 Office 文件的企业资料库来说，这是实打实的刚需。

第二，PDF 是"附带支持"，内部走的是他们同门开源的 pdf-inspector 库，只处理带文本层的 PDF。扫描件那种纯图片的 PDF 它读不出来，官方方案是接他们托管的 OCR 接口，这个边界必须提前知道，别等文件转换失败才反应。

2.2 它在 Firecrawl 产品体系里的位置

anydoc 不是孤立的玩具项目，它其实是 Firecrawl 自家生产环境里跑着的核心组件，被包装成开源库放了出来。Firecrawl 的 Parse 接口（专门做文档解析的商业服务）底层就是 anydoc，扫描件场景再接 Fire-PDF 的 OCR。换句话说，你用的是和官方线上服务同款的解析引擎，不是实验室里的半成品。项目主页在 GitHub 上（github.com/firecrawl/anydoc），Star 数、Issues 讨论、版本记录都能直接看到，感兴趣可以直接去围观。

这个"自己吃自己狗粮"的定位很关键。开源项目最怕的就是作者写完就不管了，而 anydoc 的维护动力直接绑在 Firecrawl 的商业服务上，解析质量出问题他们自己线上先炸，所以迭代通常不会停。我写这篇文章的时候（2026 年 8 月），项目还处于早期快速更新阶段，Issues 里已经能看到不少社区反馈在推动功能补全。

2.3 一个值得注意的信号

Firecrawl 之前做网页转 Markdown，现在补上本地文档转 Markdown，再把 PDF 解析单独拆成 pdf-inspector 开源，这一套组合拳打下来，意图其实很明显：AI 数据管道里"喂数据"的两个最大入口——网页和本地文件——他们想全占上。 往大了说，他们瞄的是"AI 时代的 ffmpeg"这个生态位，音视频领域 ffmpeg 是事实上的格式转换底座，文档解析领域目前还没有这么个绝对王者，谁先把格式覆盖、速度、质量三项都做到位，谁就有机会。这个话题放到后面专门聊，这一章先把工具本身认识清楚。

接下来进入正题：它凭什么这么快。

第三章 为什么能快到 4.4 毫秒：纯 Rust 与零外部依赖

先把这个数字的准确含义说清楚：4.4 毫秒是官方基准测试里转换耗时的中位数，不是最低值也不是所有场景的平均值。测试对象是 100 份真实文档，涵盖各种格式，跑下来中位耗时 4.4 毫秒，p95 大概在两位数毫秒级别。什么概念？你眨一次眼大约 300 毫秒，anydoc 在你眨眼的时间里能转完几十份文档。批量处理几百份文件，也就是"啊"的一声的工夫。

这个速度是怎么做到的？拆开看就三条：

3.1 纯 Rust，没有 GC 的运行时开销

Rust 是编译型语言，直接编译成机器码运行，没有垃圾回收器在后台时不时停顿扫内存，也没有解释器逐行翻译的开销。文档解析这种 CPU 密集、内存操作频繁的活儿，正好是 Rust 的舒适区。对比之下，很多同类工具是 Python 写的，解释执行 + GIL（全局解释器锁，同一时刻只有一个线程跑 Python 代码）天然吃亏，光这一项就有几十倍到上百倍的差距。

3.2 不依赖 ML 模型，不需要外部服务

这一点最容易被忽略。市面上不少"智能文档解析"工具其实内部挂着一个大模型或者视觉模型，靠 AI 去"看"文档内容。模型推理一次少说几百毫秒，遇到复杂版面要好几秒，而且每次都要付 API 费用。anydoc 的做法是纯规则解析——把格式规范吃透，用代码直接拆文件结构。没有模型推理，就没有那几百毫秒的固定开销，速度自然就上来了。

代价是它只能处理"机器可读"的文档：文本型 PDF、标准 XML 结构的 Office 文件。扫描件、手写体、复杂版式这些需要"看"的场景，它明确不做，留给 OCR 和视觉模型。这个取舍在第三章末尾对比工具时能看得更清楚：快，是有代价的快。

3.3 绑定层不拖后腿：Node 不阻塞、Python 不锁

很多人担心：我用 Python/Node 调它，是不是又慢回去了？官方在这块做得很讲究：

• Node.js 绑定：转换任务丢到 libuv 的线程池里执行，不占用主线程，事件循环照常跑，不会因为转一个文件把整个服务卡住。
• Python 绑定：转换过程中主动释放 GIL，多线程环境下其他线程能继续干活，不会互相排队。

也就是说，在语言绑定层它尽量做到了"无感"，你可以在自己的项目里把它当一个普通依赖用，不用担心性能被拖垮。

3.4 和其他工具的耗时直观对比

官方 benchmark 把几个主流工具的中位耗时放在一起，我摘出来做个表（数字来自官方公开数据，语料是 100 份真实文档）：

看到没有，差距是数量级的：anydoc 比第二快的 pandoc 还快 20 多倍，比 libreoffice 快了 250 倍以上。当然这个对比有前提——它测的是"能成功转换的文档"，不同工具覆盖的格式不同，语料也不完全一样，数字只能当参考，不能当圣旨。但方向是明确的：在"普通办公文档转 Markdown"这件事上，anydoc 的速度确实断层领先。

3.5 为什么偏偏是 Rust，而不是 C++ 或 Go

聊到速度，肯定有人问：那为什么不用 C++ 或者 Go？我的理解是，Rust 在这个场景有几个其他语言给不了的特性：

• 内存安全且零开销：Rust 的所有权系统在编译期就把内存问题挡在门外，不需要像 C++ 那样靠程序员自觉，也不像 Go 那样带垃圾回收器。解析器要频繁创建、释放中间对象，Rust 能把这部分开销压到理论最低。
• 出色的跨平台编译：一份代码能编译出 Windows、macOS、Linux 的原生库，还能交叉编译成 WASM 跑浏览器，一套逻辑到处用——这正是 anydoc 能同时提供 CLI、Node、Python、浏览器四种形态的技术前提。
• 绑定友好：Rust 通过 FFI（外部函数接口）给 Python、Node.js 提供绑定是社区成熟套路，生态工具链（PyO3、napi-rs）非常完善，所以官方能轻松维护多语言版本。

换句话说，选 Rust 不是炫技，是这个项目的形态决定的：既要极致速度，又要跨平台，还要多语言绑定——Rust 是目前唯一能把这三件事同时做好的选择。

3.6 一个容易被忽略的细节：转换是"纯 CPU"操作

还有一点值得提：anydoc 的转换过程不碰 GPU、不需要 CUDA 环境，纯 CPU 就能跑。这意味着什么？它能跑在最小配置的服务器上，甚至是树莓派、NAS 这类低功耗设备上。 对自托管爱好者来说，这意味着你可以把文档解析能力部署在任何一台老机器上，完全不依赖云端算力。这也是"本地优先"理念在硬件层面的体现——好工具不挑环境。

速度只是结果，真正让它既快又稳的是内部架构。下一章拆原理。

第四章 核心原理拆解：统一文档模型这个设计有多聪明

anydoc 快是一方面，但我觉得它最值得学习的不是速度，而是架构设计。市面上绝大多数文档解析工具是"一格式一管道"：docx 走 docx 的解析器，xlsx 走 xlsx 的解析器，pptx 又单独一套，最后各自输出——输出格式还不统一，有的给 HTML，有的给纯文本，有的给你一段 JSON。格式越多，代码越臃肿，Bug 越难修。

anydoc 换了个思路：不管什么文件进来，先解析成同一种"中间语言"，再由唯一的出口转成 Markdown。 这个中间语言他们叫统一文档模型（unified document model），我下面画个图帮你看清整个流程：

flowchart LR
    A[docx / doc / docm] --> P[格式解析器<br/>按格式规范拆解文件]
    B[pptx / ppt] --> P
    C[xlsx / xls] --> P
    D[odt / ods / odp] --> P
    E[rtf / epub / csv] --> P
    F[pdf 文本型] --> G[pdf-inspector] --> P
    P --> M[统一文档模型<br/>只存内容与结构：标题/表格/列表/脚注]
    M --> S[唯一序列化器<br/>GFM Markdown 输出]
    S --> OUT[干净的 Markdown 文件]

4.1 三步走：解析 → 中间模型 → 序列化

整个转换拆成三个阶段，各干各的活：

1. 解析阶段：每种格式一个解析器，按各自的格式规范（比如 docx 就是解 ZIP 读 XML）把文件拆开，提取出标题、段落、表格、列表、图片引用等内容元素。
2. 建模阶段：所有解析器产出的内容，统一塞进同一个数据结构——统一文档模型。这个模型只关心"文档里有什么、结构长什么样"，不关心"文件原来是啥格式"。哪里是标题、哪里是表格、哪里是列表、合并单元格怎么排，全部在这个模型里用标准化的方式标记清楚。
3. 序列化阶段：模型里的内容由唯一一套序列化器转成 GitHub Flavored Markdown。表格转义、标题层级、列表缩进这些输出规则只写一遍。

用大白话打个比方：这就像一家翻译社，来了英语、日语、法语三种稿件，每种语言一个专门的翻译官（解析器），但他们翻译完都交到同一个中文编辑手里（统一模型 + 序列化器）统一排版出稿。不管来稿是哪种语言，出去的稿子格式永远是同一套标准——不会出现"英文稿排版好看、日文稿排版稀烂"的怪事。

4.2 这个设计好在哪：修一个 Bug，所有格式同时受益

这是统一模型最大的红利。传统多管道架构里，你在 docx 输出里发现表格转义有 Bug，得去 docx 那套代码里修，修完发现 rtf 的输出也有同样问题，又得去 rtf 那边修一遍，没准 odt 还有第三处——同一类 Bug 修三次，还可能修出分歧。

anydoc 因为所有格式共用同一个模型和同一个序列化器，表格转义修一次，docx、rtf、odt、pptx 全部同时修好。官方在 README 里原话就是这个意思：一次修复，处处生效。这意味着它的输出一致性有天然保证——你永远不会遇到"同一种表格，docx 转出来正常、rtf 转出来乱掉"这种鬼问题。

4.3 格式识别不看扩展名：靠"指纹"说话

还有一个细节很见功力：anydoc 判断文件格式不信任扩展名，而是读取文件内容开头的字节特征（俗称文件签名或魔数）。比如 PDF 文件开头固定是 %PDF，ZIP 开头是 PK，docx/pptx/xlsx/epub 本质都是 ZIP 包，再靠包内结构进一步区分。

这意味着什么？你把一个 docx 文件改名成 .txt 甚至 .pdf，它照样能认出来该按 Word 解析；反过来，一个实际是 PDF 的文件硬改成 .docx，它也不会傻乎乎地按 Word 拆。对批量处理、文件来源混乱的场景来说，这个能力很救命。

唯一的例外是 CSV：纯文本没有固定的二进制签名，所以 CSV 需要靠扩展名或者显式传入格式参数才能识别。这是没办法的事，文件本身就不带"我是 CSV"的标记。

4.4 一个模型带来的维护收益

最后从工程角度看一眼这个设计的长期价值。文档格式规范是不断演进的：Office 出了新版本、ODF 更新了规范，解析器要跟着改；但不管解析器怎么改，只要模型和序列化器稳定，输出格式就不会漂移。解析层和输出层解耦，改一边不动另一边，这是典型的好架构该有的样子。anydoc 能保持"输出干净稳定"的口碑，一半功劳在这个模型上。

原理讲完了，下一章看它转换时到底能保住哪些细节——这决定了转换结果能不能直接用。

第五章 细节还原能力：表格、脚注、备注、代码块都不丢

解析工具最怕什么？不是慢，是**"转出来看着差不多，细看全不对"**。普通文本谁都能抽出来，真正的分水岭在细节：合并单元格、脚注、交叉引用、PPT 备注、嵌套列表、代码块……这些结构元素一旦丢失，Markdown 表面上还挺干净，但内容信息量已经大打折扣。

anydoc 在这块的处理，官方给的说法是"保留复杂文档结构"，我实测下来确实有几项做得比较到位：

5.1 能保住的细节清单

5.2 一个直观的转换示例

空口说不如看效果。假设你有一个 docx 文件，内容长这样（这是我自己做的测试样例，不是官方素材）：

# 2026 Q2 渠道复盘

| 渠道 | 新增用户 | 转化率 | 备注 |
|------|---------|--------|------|
| 官网 | 12,480 | 3.2%  | 主站改版后提升明显 |
| 内容平台 | 8,915 | 1.8% | 图文 + 视频两条线 |
| 合作渠道 | 3,206 | 4.7% | 需人工跟进，见脚注[1] |

> [1] 合作渠道 7 月起更换对接人，数据口径可能有微调。

## 核心结论

1. 官网转化率环比提升 **0.6 个百分点**
2. 内容平台是当前最大的增量来源
3. 合作渠道波动大，需要按月复核

转换之后，anydoc 输出的 Markdown 结构基本和上面一致：表格转义正确（管道符 | 不会被内容里的竖线搞乱）、列表层级清楚、脚注以引用块的形式保留、加粗标记原样保留。你拿这份 Markdown 去喂 RAG 或者直接丢给 Agent 分析，标题层级、数据表格、结论要点都能被准确识别。

5.3 图片的处理逻辑要单独说

文档里的图片，anydoc 不会直接嵌进 Markdown（Markdown 本来也不适合存二进制），而是以引用文本的形式呈现——输出里会有一个类似 ![图片](asset://xxx) 的占位引用，原始图片文件保留在缓存目录里。需要图片的人可以去缓存目录取，不需要的人（比如只想抽文本做检索）完全不受影响。

这个设计的妙处在于：文本检索和资源提取解耦了。RAG 场景通常只关心文本，图片引用不影响 embedding 和检索；而需要图片的报告类场景，也能通过缓存目录按引用关系把图找回来。两种需求都不耽误。

5.4 输出的统一性：GitHub Flavored Markdown

最后提一嘴输出标准。anydoc 输出的是 GFM（GitHub Flavored Markdown），这是目前生态兼容性最好的 Markdown 方言：支持表格、任务列表、删除线、代码块语言标记等扩展语法。你用 GFM 输出，不管是进向量库、喂给模型、还是渲染成网页，兼容性都几乎没有坑。输出标准的统一，是它作为"基础设施"类工具的基本素养——工具链最怕的就是每个环节各说各话。

5.5 一份可以直接抄的转换质量验收清单

不管用哪个解析工具，转换完都不能直接信任，尤其是要进知识库的文档。我给自己定了一份验收清单，每次批量转换后按它抽检，你也可以直接拿去用：

• 标题层级是否完整（# 到 #### 的层次是否与原文档一致）
• 表格行数列数是否对得上，合并单元格内容有没有丢失
• 关键数字是否原样保留（金额、日期、百分比，逐项核对）
• 列表嵌套层级是否正确，无序/有序列表有没有混掉
• 脚注、交叉引用是否还在，引用目标有没有断链
• 代码块有没有被误判成普通段落，语言标记是否保留
• 图片引用是否生成，缓存目录里能否找到对应原图
• 特殊字符（中文引号、全角标点、公式符号）有没有变成乱码

这八项过一遍，解析质量基本就有底了。我实测 anydoc 的通过率很高，但"很高"不等于"100%"，抽查这个动作建议保留——尤其是金融、法律、学术类的关键资料，宁可多花五分钟核对，也别让错误数据悄悄溜进知识库。

细节保得住，接下来就看怎么把它用起来。下一章给五种接入方式，每种都配好现成的代码。

第六章 五种上手方式：CLI / Node / Python / WASM / Agent Skill

工具再好，装不上、不会用也是白搭。anydoc 在这块的诚意很足，一口气给了五种接入方式，从命令行到浏览器到 Agent 插件全覆盖。我把每种方式的用法和适用场景都过一遍，代码可以直接抄。

6.1 方式一：CLI 命令行（最快上手）

想马上试效果，命令行是最省事的。anydoc 提供了编译好的 CLI 二进制，一条命令转换一个文件：

# 安装（不同平台包管理器略有差异，以官方文档为准）
cargo install anydoc-cli

# 转换单个文件
anydoc convert 年度报告.docx

# 转换并指定输出文件名
anydoc convert 会议纪要.pptx -o 会议纪要.md

# 批量转换整个目录
anydoc convert ./docs/ --output ./markdown/

CLI 适合什么场景？一次性转换、脚本里批量处理、服务器上定时任务。我用它处理过一批历史遗留的 .doc 老文件，几百份几分钟跑完，中途没报错，这在以前想都不敢想。

6.2 方式二：Python（嵌入现有项目）

Python 用户是文档处理的主力军，anydoc 提供了官方 Python 包，带类型标注（.pyi 文件），IDE 里写代码有提示：

from anydoc import to_markdown, to_document

# 最简用法：文件路径转 Markdown
md = to_markdown("销售数据.xlsx")
print(md[:500])  # 打印前 500 字符看看效果

# 进阶用法：拿到结构化文档对象
doc = to_document("项目方案.pptx")
for block in doc.blocks:
    print(block.kind, block.content)

to_document 返回的是统一文档模型的对象，你可以自己遍历里面的块（标题、段落、表格等）做二次加工，比如只抽取表格、只保留标题层级。灵活性比单纯拿 Markdown 字符串高不少。

6.3 方式三：Node.js（服务端集成）

Node 绑定走 libuv 线程池，不阻塞事件循环，适合做 API 服务：

const { toMarkdown } = require("@firecrawl/anydoc");
const fs = require("fs");

const buffer = fs.readFileSync("需求文档.docx");
const md = toMarkdown(buffer);
console.log(md);

// 服务端批量处理示例
const files = ["a.docx", "b.pptx", "c.xlsx"];
const results = await Promise.all(
  files.map(f => toMarkdown(fs.readFileSync(f)))
);

6.4 方式四：浏览器 WASM（文件不出本机）

这是隐私敏感场景的答案。anydoc 编译成了 WebAssembly，官方网页 demo 就是纯浏览器端运行——文件在本地转换，不上传任何服务器：

import init, { toMarkdownBytes } from "@firecrawl/anydoc-wasm";

await init();

// 从字节数组转换，格式自动识别
const markdown = toMarkdownBytes(fileBytes);

// CSV 没有格式签名，需要显式指定
const fromCsv = toMarkdownBytes(csvBytes, "csv");

我自己的用法是：涉及合同、人事资料这类敏感文件，绝不往在线工具上传，直接拖进浏览器版 anydoc 转完本地拿走，心里踏实。

6.5 方式五：Agent Skill（装进 Claude Code / Codex）

这个是最新潮的用法，也是我觉得最有想象力的。anydoc 官方提供了 Agent Skill 安装包，一条命令装进 Claude Code、Codex 这类 AI 编程助手：

npx skills add firecrawl/anydoc

装完之后，你让 Agent"读取这份 pptx 并总结要点"，它就能自动调用 anydoc 把 PPT 转成 Markdown，再基于转换结果做分析。相当于给 AI 助手装了一双能读懂办公文件的眼睛。 对整天和文档打交道的开发者来说，这个体验提升是立竿见影的——以前让 Agent 处理 Office 文件基本是鸡同鸭讲，现在它真能"看"了。

6.6 五种方式怎么选

最后给个简单的选择参考：

工具用起来不难，真正值得分享的是实际跑一遍会遇到什么。下一章讲我的实测记录和踩坑经历。

第七章 实测体验：我从安装到跑通踩过的坑

理论讲了一堆，还是得动手验证。我这几天把 anydoc 拉下来在本地跑了一轮，覆盖了六类文件，从安装到踩坑的完整过程记录在这里，给想上手的你当个参照。

7.1 测试环境与方法

我用的环境是 Ubuntu 22.04 + Python 3.11，通过 pip 安装的官方包，测试文件都是我自己造的和公开渠道拿的样例：一份带合并单元格的 docx 财务报表、一份带演讲者备注的 pptx、一份多 sheet 的 xlsx、一份老式 .rtf 富文本、一份 LibreOffice 生成的 odt、一份电子书 epub。每份文件转换 10 次取平均耗时，同时人工核对输出质量。

7.2 实测结果一览

整体结论先说：对日常办公文档，anydoc 的输出质量完全够用，速度更是体感不到延迟。文档越大耗时越长是正常的，但即便 2MB 的 PPT 也就十几毫秒，批量处理完全没压力。

7.3 我踩过的三个坑

坑总是要踩的，提前告诉你省得你重蹈覆辙。

坑一：加密文档直接报错。 我一开始没注意，拿了一份带打开密码的 xlsx 去转，直接抛异常。后来查文档确认：anydoc 不支持加密和带密码保护的文档，遇到就报错。这个我倒觉得合理——解密涉及密钥管理和安全策略，工具本身不做也说得过去，加密文档你先自己解了再喂给它就行。

坑二：扫描件 PDF 转出来是空的。 这是最容易"翻车"的场景。我拿一份扫描版合同（纯图片 PDF）去转，输出几乎为空，只有零星几行能识别出的文本。原因前面讲过：anydoc 的 PDF 支持走的是 pdf-inspector，只认文本层。扫描件必须走 OCR 路线——官方托管 API 带 OCR，或者你自己接本地 OCR 工具先识别成文本 PDF 再喂给它。如果你的资料库里有大量扫描件，anydoc 解决不了你的问题，别抱幻想。

坑三：CSV 文件必须带正确扩展名。 我手贱把一个 CSV 改名成 .txt 去转，结果它把内容当成普通文本处理，表格结构没了。因为 CSV 没有二进制签名，anydoc