pdf-inspector

简体中文

English

简体中文

English

外观

pdf-inspector GitHub 仓库 - 源码、构建与贡献指南

pdf-inspector 的官方源码托管在 github.com/firecrawl/pdf-inspector，由 Firecrawl 维护，MIT 协议完全开源。不想装包、想看源码、想报 bug 或者直接参与贡献，都从这个仓库开始。本页帮你把仓库的关键入口和本地构建方法一次理清。

仓库关键入口

内容地址
源码仓库github.com/firecrawl/pdf-inspector
问题反馈（Issues）github.com/firecrawl/pdf-inspector/issues
发布版本（Releases）github.com/firecrawl/pdf-inspector/releases
OCR 运行时配置指南docs/ocr-runtime.md
README（英文）github.com/firecrawl/pdf-inspector#readme

引用或收藏时认准 firecrawl/pdf-inspector 这个仓库；npm 上的 @firecrawl/pdf-inspector、PyPI 上的 pdf-inspector、crates.io 上的 pdf-inspector 都是它的官方发布渠道。

克隆仓库

git clone https://github.com/firecrawl/pdf-inspector.git
cd pdf-inspector

仓库里有什么

pdf-inspector 是一个以 Rust 为核心的多语言工作区：

  • Rust 核心——检测（detector）、提取（extractor）、排版（layout）、表格（tables）、Markdown 渲染（markdown/）五大模块，唯一的 PDF 解析依赖是 lopdf；
  • Node.js 绑定（napi）——npm 包 @firecrawl/pdf-inspector，预构建二进制覆盖 Linux / macOS / Windows，附带 TypeScript 定义与 CLI；
  • 浏览器绑定（wasm）——npm 包 @firecrawl/pdf-inspector-wasm，单线程构建、CMap 内嵌，本站首页的在线 Demo就是用它实现的；
  • Python 绑定——PyPI 包 pdf-inspector，基于 maturin 构建；
  • CLI——pdf2md 与 detect-pdf 两个二进制，随 Rust crate 分发；
  • 测试资产——快照测试、变异测试与 cargo-fuzz 模糊测试目标。

架构细节见项目介绍，各模块职责在首页也有图解。

从源码构建

Rust（核心 + CLI）

cargo build --release          # 构建核心库与 CLI
cargo install pdf-inspector    # 或直接安装 pdf2md / detect-pdf 到 PATH
cargo test                     # 运行测试套件

Node.js 绑定

npm install @firecrawl/pdf-inspector   # 使用预构建二进制，无需 Rust 工具链

要在本地改绑定代码再构建，需要 Rust 工具链与 napi CLI，详见仓库 README 的开发章节。

Python 绑定

pip install pdf-inspector      # 预构建 wheel，无需 Rust 工具链

仓库内开发可用：

maturin develop --release

浏览器 WASM

npm install @firecrawl/pdf-inspector-wasm

WASM 构建已内嵌 CMap 数据，浏览器里不需要额外的字体映射文件。

不想自己编译？

大多数场景用不上源码构建——各平台的预构建包才是日常路径，见安装下载页。只想在线试试？打开首页 Demo拖一份 PDF 即可。

报 Issue 的正确姿势

提 issue 前先做三件事，能大幅加快定位：

  1. 先判定类型：detect-pdf 文件.pdf --analyze --json 把输出贴上——很多"转换乱码"问题其实是扫描件或编码损坏页；
  2. 给最小复现：能触发问题的最小 PDF（注意脱敏）或构造步骤；
  3. 说清环境：平台、包名与版本（@firecrawl/pdf-inspector / pdf-inspector / pdf-inspector crate）、调用方式。

贡献代码

  1. Fork 仓库并从 main 拉分支；
  2. 改动请带上测试——解析类的改动尤其欢迎补充快照用例（真实世界的脏 PDF 样本最有价值）；
  3. 跑通 cargo test 与格式检查后提交 PR；
  4. 大改动（新依赖、新 API、新格式）建议先开 issue 讨论。

注意

pdf-inspector 使用 MIT License。提交即表示你同意以同样协议授权你的贡献。

姊妹仓库：AnyDoc

同一时期 Firecrawl 还开源了 anydoc（官网 anydoc.wiki）：把 Word、PPT、Excel、OpenDocument、RTF、EPUB、CSV 等 14 种办公格式统一转成 Markdown，其中 PDF 路径正是由 pdf-inspector 驱动。只处理 PDF 用本站的主角；混合格式一把梭用 AnyDoc，详见 AnyDoc 介绍页。