同事甩给你一个 .ofd 文件——发票、合同、电子证照,现在越来越多是这种格式。你双击,打不开;想转成 PDF 发给客户,搜到的工具要么让你先注册账号,要么让你上传到它的服务器再下载。
发票里有税号、金额、开票方,合同里有公章和签署信息。这些东西你敢往陌生网站上贴吗?
装个桌面软件?平台、安装和升级都要考虑,而且有的工具只做“转 PDF”一件事。想校验一下文件结构、看看到底有哪些资源、批量把几十张发票的金额汇总出来,还需要更多工具配合。
今天聊的这个开源项目就是冲这些痛点来的:zc310/ofd-toolbox——一个用 Go 编译成 WebAssembly 的纯前端 OFD 工具箱。文件不上传,没有处理文档的服务端,也没有账号,打开网页就能用。
在线使用:OFD 工具箱。
本文按原稿所述功能与体积整理,工具数量、模块大小和可选功能可能随版本变化,以项目文档与线上界面为准。只想快速了解功能,可先看工具箱简要介绍。
一、它到底是什么 #
一句话概括:
把一整套 OFD 文档处理能力,编译成一个 WebAssembly 模块,放进浏览器里跑。所有文件的理解与改写都在你这台机器上完成。
底层能力来自 zc310/ofd 这个 Go 工具包,ofd-toolbox 负责把它包成浏览器能用的形态:WASM 构建、Worker 调度、流式产物传输、Service Worker 缓存和界面。
原稿介绍的界面一共 7 个工具 Tab:
| Tab | 做什么 |
|---|---|
| 转换 | OFD 转 PDF、图片、SVG、EPS、TeX、HTML、Markdown、Word、纯文本;PDF、图片、Markdown 转 OFD |
| 校验 | 校验 ZIP、XML、引用关系与 XSD,报告可导出 JSON / Markdown / 纯文本 |
| 分析 | 页面对象、文字、资源、附件、注解、签名与引用关系概览 |
| 发票 | 批量读取增值税电子发票 OFD,汇总金额、按销售方/票种/月份分组,导出 JSON / CSV / XLSX |
| 水印 | 在指定页添加、替换或删除文字/图片水印,支持布局、旋转、透明度、字体 |
| 合并 | ZIP 级合并产出多文档包,或模型级拼页产出单文档 |
| 长期保存 | 按 GB/T 42133 第 6 章预检与执行,含删除无人引用条目 |
输入格式(浏览器里能直接用的):OFD、PDF、PNG、JPG、TIFF、Markdown。
二、最有价值的点:文件不上传 #
许多在线转换工具采用“上传 → 服务器处理 → 下载”的流程。OFD 常常是发票、合同、证照,文档能否外传,需要先考虑清楚。
ofd-toolbox 采用另一种架构:
- 能力来自 Go 工具包,编译成一个
.wasm模块。 - 模块在浏览器 Worker 里运行,计算全在本机。
- 没有处理文档的后端接口,没有文件上传这一步。
- 首次加载后由 Service Worker 缓存,后续可在所需资源已缓存的情况下离线使用。
你可以在开发者工具的 Network 面板里检查:网页会加载静态资源,但文档处理不需要把所选文件上传到服务器。浏览器扩展、操作系统与设备本身的安全仍需另外考虑,不能把“本地处理”理解为完整的安全认证。
三、工程上几个“不显眼但很关键”的决定 #
一个纯前端工具最难的不是“能跑”,而是大文件处理、错误隔离和行为边界。这个项目在这几件事上做了不少取舍。
1. WASM 跑在 Worker 里,主线程负责交互 #
模块有 50 MB 量级。如果装载和计算都在主线程,页面可能长时间不可交互——进度条卡住、取消按钮点不动、滚动条卡死。
所以整个引擎跑在 Web Worker 里,主线程只负责界面。进度、取消、产物分块全部走消息传递。
2. 产物分块下发,Worker 内部确认(ACK) #
WASM 回调给出一块产物,写进接收端后立刻确认,下一块才生成。
少了确认,中间产物可能在 WASM 内存里累积。模块、文档与尚未写出的产物叠加,会增加浏览器内存压力,严重时可能导致标签页被终止。
ACK 特意不经过主线程,避免多一次消息投递延迟。
3. 命令边界统一兜 panic #
第三方库里可能崩溃的地方之一是“找不到系统字体”,例如 font.FindSystemFonts 在无字体目录环境中的空指针问题。这类错误不是返回 error,而是直接 panic,调用方写不了 if err != nil。
不在边界上兜住的话,一次未恢复的 panic 就可能终止整个 WASM 实例:已打开的文档、缓存的报告和正在跑的任务一起丢失,只能整页刷新。
所以在每个导出的 JS 命令外面套了一层 safe(),把 panic 转成错误结果。
4. Service Worker 缓存名由内容哈希算出 #
页面的 HTML、JS 与 WASM 通过同一套资源版本管理,减少“新 JS 调旧 WASM”的问题。换版时需要刷新页面以完成接管,因此界面上有一条“已有新版本”的提示。
5. 字体只取本机或用户上传的文件,不联网取字体 #
浏览器里没有可随意读取的系统字体目录。OFD 没内嵌字体时,中文可能变成方块。工具允许你选本机字体或上传字体文件兜底,候选列表还会标出哪些能补齐文档缺字、哪些已注册。
6. 界面由能力清单驱动 #
转换 Tab 的格式卡片、参数面板显隐,校验 Tab 的可选项,全部由 WASM 侧的 capabilities 清单驱动。库侧增删格式时界面自动跟随,不需要两处同步。
四、几个值得留意的细节 #
真正影响使用体验的,往往是错误信息和小开关的设计。
发票金额用十进制字符串传递。 1130.00 一旦变成数字 1130 再转回文本,就可能少了小数位。金额通过 Decimal 类型处理,序列化成字符串,避免这类表示差异。
合并默认保留签名条目,但保留不等于有效。 加水印会改动页面内容,可能使已有签名摘要验证失败。工具保留签名相关条目并把警告透传给界面,不能据此认定修改后的文件仍具备有效签名;输出文件应另行验证,原件也应保留。
长期保存拆成两步走。 预检(Plan)只读,算出计划改动;执行(Apply)才写文件。其中一类动作是不可逆的删除,让用户先看到“会发生什么”再决定。
生成汇总页需要一个中文字体,没有就不让生成。 而不是让它生成一页空白——空白页比报错难发现得多,用户会以为汇总就是空的。
内存诊断区分“堆”和“线性内存”。 WASM 线性内存增长后通常不会随 Go 堆回收而立即缩小,不能仅凭它没有下降就判断泄漏。诊断时还需要结合 Go 存活堆、任务状态和浏览器整体内存观察。
五、自己跑一遍 #
在仓库根目录执行:
make build-wasm
python3 -m http.server 8080 --directory cmd/toolbox-wasm/web然后打开 http://localhost:8080。注意浏览器不能直接通过 file:// 加载此应用的 WASM,需要使用 HTTP 服务。
make build-wasm 会编译 toolbox.wasm、按需用 wasm-opt 优化、从 GOROOT 复制 wasm_exec.js,最后按各资源的内容哈希重算 service-worker.js 里的缓存名。找不到 wasm-opt 时会告警并改用未优化版本,不让构建直接失败。
原稿对应的主要目录结构:
cmd/toolbox-wasm/
├── *.go WASM 侧命令,每个文件带 //go:build js && wasm
└── web/ 页面资源(无框架、无构建步骤,直接就是浏览器要的东西)
├── index.html 单页,7 个工具 Tab
├── app.js 主线程:界面、状态、Worker 消息
├── worker.js Worker:WASM 装载、命令分发、流式产物接收
└── toolbox.wasm 构建产物,50MB 量级,不入库没有前端框架,没有前端打包步骤——页面资源就是浏览器最终要加载的东西,少了一层工具链的复杂度;WASM 本身仍需按上述命令构建。
六、已知边界 #
- Office 与 HTML 输入不可用。 docx/odt/rtf/wps/pptx/xlsx 和 html/mhtml 依赖 LibreOffice 或 Chrome 命令行,浏览器里没有。界面会说明缺少的能力。
- 校验与分析报告不提供 XLSX 与 PDF。 原稿所述版本中,两者可导出 JSON / Markdown / 纯文本。发票报表不受此限。
- 原稿记录的 WASM 体积为 63 MB。 发票 XLSX 导出要引入 excelize,单独贡献约 12.6 MB。首次加载需要下载模块,之后由 Service Worker 缓存;具体体积随构建版本变化。
- OFD 支持范围以 zc310/ofd 的文档为准。 不同厂商的 OFD 存在扩展差异。
七、适合谁? #
适合 #
- 手里有 OFD,需要在不上传文件的前提下转成 PDF、图片、Word 或 Markdown。
- 需要校验 OFD 包结构、排查引用关系与签名问题。
- 财务、审计要把成批的增值税电子发票金额汇总出来,导出成 Excel。
- 要给合同、文档批量加水印,或把多份 OFD 合并。
- 做数字档案,需要按 GB/T 42133 做长期保存预检与处理。
- 想使用一个在本机浏览器内处理文档、不需要注册账号的工具。
不适合 #
- 需要处理 Office / HTML → OFD:浏览器环境里缺少 LibreOffice / Chrome 命令行。
- 需要 OCR:图片转 OFD 不会因此自动获得文字层。
- 对电子签名的法律有效性做最终认定:工具不保证合规结论,签章有效性需要另行核验。
八、最后说点判断 #
OFD 是国标版式文档格式,在电子发票、电子证照、政务档案等场景里经常能遇到。除了桌面软件和服务器转换,ofd-toolbox 提供了另一种处理方式:
用 WebAssembly 把处理能力搬到本机浏览器里,支持转换、校验、发票汇总、水印、合并与长期保存处理,不需要上传文档、不需要安装桌面软件、不需要账号。
Worker 隔离、分块 ACK 背压、panic 边界、内容哈希缓存、capabilities 驱动的界面、两步式不可逆操作,以及金额的小数位处理,都是实际使用中值得关注的工程细节。
同样重要的是看清边界:不能处理的输入、首次加载体积、字体和签名问题,都需要在正式使用前确认。技术选型里最怕的不是能力有限,而是踩坑后才知道边界在哪。
如果你经常和 OFD 打交道,可以用自己的代表性文件试一遍,再决定是否加入日常工作流程。