简介：面向Java开发者的PDF转OFD国产化示例工程，适用于政务、企事业单位电子文档系统建设与信创适配场景。资源围绕PDF解析、OFD结构构建与内容转换展开，涵盖读取PDF、解析页面布局、创建OFD目录与资源库、编码排版文字图像，以及处理字体兼容性、图片压缩与数字签名等关键环节，能够帮助读者快速跑通从PDF到OFD的完整转换流程。压缩包共198个文件，以33个Java源码文件、151个XML配置与OFD结构文件为主，并包含少量class编译产物、模块配置iml、Kotlin模块信息，包体仅120KB，目录清晰便于定位核心示例。已有1289人学习下载；借助测试合并单元格、限制编辑等示例类，可了解Java工程中集成OFD SDK的调用方式，为自有国产化文档处理项目提供直接参考。 这两年做Java后端的人，多多少少都绕不开“OFD”这个词。尤其在电子政务、电子发票、档案存储这一类系统里，PDF转OFD已经从“加分项”变成了“必做需求”。我手上正好有个项目要把存量PDF批量转成OFD，再对接阅读、归档、打印的整套链路，中间踩了不少坑，也把方案完整跑通了。这篇文章就把整个过程梳理出来，从选型到落地、从坐标换算到字体踩坑，都给讲清楚。
这篇内容适合所有正在做国产化适配的Java开发，也适合准备Java面试时想搞懂PDF与OFD转换原理的同学，以及产品经理想了解“为什么这个功能这么麻烦”的可以参考。看完你会清楚：OFD和PDF到底什么关系、Java做转换有几条路、每一步具体怎么写代码、会遇到哪些想都想不到的坑。我尽量说人话，代码也可以直接拿去改。
1. OFD到底是个什么东西，为什么Java项目绕不开它
1.1 别把OFD简单理解成“国产PDF”
OFD全称是Open Fixed-layout Document，开放版式文档，国家标准编号GB/T 33190-2016。它本质上是一个ZIP压缩包，里面用XML描述页面内容，用独立的资源目录存放字体、图片、矢量路径。所以你打开一个OFD文件，能看到类似这样的结构：
OFD.xml Doc_0/ Document.xml Pages/ Page_0/ Content.xml Resources/ Fonts/ Images/这个“ZIP包 + XML描述”的设计很有意思，它让OFD有了两个明显好处：一是文件结构透明，就算没有专用SDK，自己按规范解压也能读出内容；二是和特定厂商绑定很弱，格式本身开放、免费使用。
但OFD和PDF不是一模一样的东西。PDF是Adobe制定的标准，发展了几十年，生态最成熟，几乎所有平台都有阅读器。OFD则是面向电子文档的版式规范，更强调中文排版支持、电子印章、长久归档这些国内实际场景。对Java开发来说，最直接的感触就是：同样的页面描述，PDF以point为单位、坐标原点通常在左下角；OFD的页面坐标在常用实现中是毫米单位、原点通常在左上角。就这一个差异，转换逻辑里就要做不少功夫，后面会细说。
1.2 哪些项目和场景真的需要PDF转OFD
我自己遇到的场景大概是这几类：
第一类是电子发票和电子票据。很多系统里存量发票是PDF格式，但业务侧要求统一以OFD归档，这就要把历史PDF批量转换。第二类是电子证照、电子公文、档案系统，这类系统对格式的标准化要求极高，OFD作为自主版式格式，在归档过程中有天然优势，存量PDF需要转成OFD做长期保存。第三类是招投标系统、司法文书系统，这些地方往往要求最终交付文档同时保留PDF和OFD两个版本，也就是常说的“双套归档”。
还有一个容易被忽略的场景是打印和分发。OFD对中文排版的处理比传统PDF更贴合国内办公需求，有些单位内部办公系统默认阅读器对OFD支持很好，PDF反而需要额外装插件。所以你会发现，真正需要做转换的，不是某个边缘模块，而是涉及全部存量文档的“地基”功能。这也决定了它天生适合用Java后端来做批量任务，而不是靠人工一个个手工另存。
你可能会问，为什么不直接让业务系统改成生成OFD，还要转存量？实际做过就知道，存量数据根本不可能回到生产源头重新生成，转换是性价比最高的方案。所以“Java将PDF转OFD”这套能力，在未来很长一段时间里都是刚需。
2. 动手前先选技术路线，Java实现PDF转OFD有这么几条路
2.1 三条路线横向对比：开源、商业SDK、在线API
我第一次接到需求的时候，第一反应是搜索有没有“一键转换”的开源库。搜了一圈发现，真正能用的方案大概分三条路线。
| 技术路线 | 代表性方案 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|---|
| 纯开源组合 | Apache PDFBox + OFD R&W | 免费、可二次开发、内网可部署 | 需要理解两种格式规范，工作量大 | 有Java开发资源、需要深度定制 |
| 商业SDK | 各版式软件厂商提供的转换组件 | 精度高、售后好、省事 | 收费、闭源、可能绑定厂商 | 预算充足、对转换质量要求高 |
| 在线API | 各种文档转换平台 | 接入快、不占本地资源 | 有数据外发风险、不可控 | 一次性转换、非敏感数据 |
如果你只是临时转几个文件，在线API确实快，但生产环境我真的不建议。文档内容进了第三方平台，本身就是很大的安全隐患，更别说有些平台的文档会被留存。商业SDK精度是真好，我也见过有同事用过，中文排版还原度极佳，但价格不便宜，而且在国产化适配的大环境下，项目组会更倾向可控性强的开源方案。
2.2 我为什么选“PDFBox + OFD R&W”这个组合
最终我选了开源组合：Apache PDFBox负责解析PDF，OFD R&W负责构建OFD，这个搭配在Github一搜就能找到，在Maven仓库也能直接拉到对应依赖。
PDFBox是老牌PDF解析库，可以读文字、坐标、图片，还能处理加密PDF，几乎是Java领域解析PDF的事实标准。OFD R&W是Java生态里比较活跃的OFD操作库，支持生成、解析、转换，还自带了PDF转OFD的converter模块。选择它还有个重要原因：项目代码完全开源，可以读到底层实现，一旦遇到问题可以自己改，而不是干等商业支持。
这里要提醒一下，如果只想快速交差，OFD R&W的converter模块确实几行代码就能跑通；但如果你要精调版式、处理特殊字体、控制转换性能，那还是要自己基于PDFBox做解析，再基于OFD R&W做重建。这两条路不冲突，我后面给的代码骨架也是基于第二种思路，因为更可控。
3. 核心实现：从PDF解析到OFD重建的完整流程
3.1 转换流程的总体设计
PDF转OFD不是简单的格式搬家，而是“先把PDF的内容拆出来，再按OFD的规则重新画一遍”。整个流程可以拆成六步：
- 用PDFBox加载PDF文件，逐页读取。
- 提取页面尺寸、文字块、图片对象、矢量路径。
- 把PDF的point坐标换算成OFD的毫米坐标，并完成Y轴翻转。
- 用OFD R&W创建OFD页面，把文字、图片、路径按位置填入。
- 把字体文件嵌入OFD资源目录，防止换机器乱码。
- 保存OFD文件，生成后做校验，比如检查页数、抽查文字内容。
这六步里，最容易让人翻车的是第三步坐标换算。很多文章直接复制代码能转出文件，但打开一看内容全在页面外面，原因就是坐标没有处理好。
3.2 坐标换算：最容易翻车的一步
PDF使用的单位是point，1 point等于1/72英寸，1英寸等于25.4毫米，所以1 point约等于0.3528毫米。OFD在常用实现里以毫米为坐标单位，这就有个简单的乘除关系：
double mmPerPt = 25.4 / 72.0; double xMm = xPt * mmPerPt; double yMm = yPt * mmPerPt;但更关键的是原点方向。PDF页面坐标原点一般在左下角，Y轴向上；而OFD在实际项目里常用的是左上角原点、Y轴向下的坐标系。这就意味着Y方向必须要翻过来，否则转换出的文字会上下颠倒或者整体偏离页面。
我给出一个简化后的换算逻辑：
// 假设pdfPageHeight是PDF页面的总高度，单位pt double xOfd = text.getXDirAdj() * mmPerPt; double yOfd = (pdfPageHeightPt - text.getYDirAdj() - text.getHeightDir()) * mmPerPt;这里为什么要减去text.getHeightDir()？因为PDF里提取文字位置时，Y坐标通常是基线（baseline）位置，而OFD的文本框定位一般按顶部或者边界来算，如果不减去字高，整段文字会明显偏下几个像素。当然真正生产级转换还要考虑字体ascent、descent这些细节，但先把这个简化版本跑通，你就能避免90%的“文字跑到页面外面”问题。
3.3 可直接参考的Java代码骨架
下面这个代码骨架是我在项目里实际用过的思路，主要展示如何用PDFBox解析PDF并重建OFD。依赖方面，你需要引入Apache PDFBox和OFD R&W，版本以Maven仓库最新稳定版为准。
import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.pdmodel.PDPage; import org.apache.pdfbox.pdmodel.common.PDRectangle; import org.apache.pdfbox.text.PDFTextStripper; import org.apache.pdfbox.text.TextPosition; import java.io.File; import java.util.ArrayList; import java.util.List; public class PdfToOfdConverter { static class TextWithPosition { double xPt; double yPt; double widthPt; double heightPt; String content; } public void convert(String pdfPath, String ofdPath) throws Exception { try (PDDocument pdf = PDDocument.load(new File(pdfPath))) { int pageCount = pdf.getNumberOfPages(); for (int i = 0; i < pageCount; i++) { PDPage pdPage = pdf.getPage(i); PDRectangle box = pdPage.getMediaBox(); double pageWidthPt = box.getWidth(); double pageHeightPt = box.getHeight(); // 用PDFBox提取带坐标的文本 List<TextWithPosition> textList = extractTextWithPosition(pdf, i + 1); // 这里把pt坐标转成mm坐标，并构建OFD页面 // 核心换算逻辑见3.2节，实际写入需要按OFD R&W的API来 double mmPerPt = 25.4 / 72.0; for (TextWithPosition twp : textList) { double xMm = twp.xPt * mmPerPt; double yMm = (pageHeightPt - twp.yPt - twp.heightPt) * mmPerPt; // 调用OFD R&W创建TextObject并写入该页面 } } } } private List<TextWithPosition> extractTextWithPosition(PDDocument pdf, int pageNum) throws Exception { List<TextWithPosition> result = new ArrayList<>(); PDFTextStripper stripper = new PDFTextStripper() { @Override protected void processTextPosition(TextPosition text) { TextWithPosition twp = new TextWithPosition(); twp.xPt = text.getXDirAdj(); twp.yPt = text.getYDirAdj(); twp.widthPt = text.getWidthDirAdj(); twp.heightPt = text.getHeightDir(); twp.content = text.getUnicode(); result.add(twp); } }; stripper.setStartPage(pageNum); stripper.setEndPage(pageNum); stripper.getText(pdf); return result; } }这段代码的重点是processTextPosition这个回调，PDFBox每遇到一个文本位置都会调用它，我们就能拿到每个字符的坐标和内容。有了这个基础，后面接OFD写入只是“翻译”的问题。
如果你不想从零开始写，可以直接用OFD R&W自带的转换模块，思路和上面类似，但它帮你把页面、坐标、资源都处理好了。核心调用非常简单：
// 以OFD R&W的converter模块为例 PDFConverter converter = new PDFConverter(new File("input.pdf")); converter.convert("output.ofd", new ConvertConfig());当然，自带的转换模块也不是万能，特殊字体或者复杂页面排版仍然可能出问题，这时候就需要回到自己解析重建这条路。
3.4 字体、图片、矢量元素的处理要点
文字只是PDF转OFD的一部分，还有图片和矢量图形。
图片处理相对简单。PDFBox可以从页面提取PDImageXObject，拿到图片字节流后，按OFD的资源格式写入Images目录，并在Content.xml里通过ImageObject引用。要注意的是PDF里的图片可能用了DCTDecode（JPEG）、FlateDecode（PNG/bmp）等不同编码，提取时要保留原始编码格式，不要无脑转成BMP，否则文件体积会暴涨。
矢量图形是另一道坎。PDF里的线条、表格、图形，是由一系列路径操作组成的，比如moveTo、lineTo、curveTo、fill、stroke。OFD也有对应的PathObject，理论上可以一一映射。但实际做的时候，复杂的矢量路径转换很容易出错，尤其是曲线和填充规则组合在一起时。我的处理策略是：能解析的路径尽量解析成OFD的路径对象；解析不了或者异常复杂的部分，退而求其次把对应区域栅格化成图片再写入OFD。这虽然会让文件变大、放大时有点糊，但至少保证内容不丢。
字体处理最容易踩雷。PDF文档可以嵌入字体的子集，也可以依赖本地字体。转换到OFD时，最好把实际用到的字体提取出来，嵌入到OFD的资源目录里。中文字体文件动辄十几兆，如果页面字体五花八门，OFD文件体积会变得很大。我后来统一了字体策略：业务文档只使用思源黑体、思源宋体这类开源字体，转换时统一映射，既减少体积又避免版权问题。
4. 实测踩坑记录：这些问题我基本都遇到过
4.1 转换结果速查表：现象、原因、解法
我在项目里实际跑了几千份PDF，把高频问题整理成一个速查表，后面对着查就行。
| 症状 | 可能原因 | 排查与解决 |
|---|---|---|
| 中文全部变成方块或乱码 | 目标环境没有对应中文字体 | 安装字体或转换时把字体嵌入OFD资源目录 |
| 文字位置整体偏移或跑到页面外 | 坐标没做Y轴翻转，或没减去基线高度 | 按3.2节公式检查转换逻辑 |
| 图片部分丢失 | PDF图片编码格式复杂，提取失败 | 打印日志定位丢失页面，改用原编码方式输出 |
| 表格线变粗或错位 | 矢量路径映射不精确 | 降低对路径的期望，必要时对表格区域做栅格化兜底 |
| 转换后文件体积巨大 | 嵌入整套字体或图片被转成高保真BMP | 只嵌入页面实际用到的子集字体，图片保留JPEG/PNG |
| Linux服务器上跑出乱码 | 服务器缺少中文字体，headless环境字体问题 | 安装fontconfig并放入开源中文字体，或在代码中指定字体目录 |
| 大文件转换时内存溢出 | PDFBox把整份文档加载到内存 | 使用临时文件模式加载PDF，按页流式处理 |
| 页面文字提取为空 | 这份PDF是扫描件，没有文本层 | 先OCR识别文字，再生成带文本层的OFD |
4.2 生产环境的几个实践建议
第一，转换逻辑不要塞在Web接口里同步执行。一份一百页的PDF，单页50到200毫秒，整份文件可能要十几秒甚至更久。一旦并发上来，接口直接超时。我最终做成了独立转换任务，用线程池排队处理，异步回调通知结果，这样可靠性高很多。
第二，一定要在部署前把字体问题解决干净。开发环境Windows本机中文字体很全，代码跑得好好的，一部署到精简版Linux服务器，直接乱码。后来我在服务器上装了fontconfig，放入了思源黑体，并在Java启动参数里指定了字体路径，才算稳定。
第三，生成完OFD不是终点，要做自动化验证。我写过一个校验脚本，用OFD R&W把生成的OFD解析出来，检查页数是否与PDF一致、每页文字数量是否合理、图片数量是否匹配。再配合随机抽几页人工打开比对，基本能把问题卡在上线前。
还有一个细节值得说：遇到扫描版PDF时，不要幻想直接转。它的每一页只是一张图片，PDFBox提不出任何文字。这种情况必须先接入OCR识别，生成文本层，然后才能转成OFD。OCR识别出来的文字坐标精度一般，转换后的版式只能达到“可检索、可复制”的程度，和原始PDF版式会有细微差异，这个要提前跟业务方对齐预期。
最后再分享一点我个人的体会：这类转换功能看着简单，真正耗时间的往往不是写代码，而是处理各种“不标准”的PDF。每个厂商导出的PDF，坐标精度、字体嵌入方式、图片编码都不一样，永远有奇怪的边界情况。所以从一开始就要把日志打全，记录每份转换失败的源文件和失败原因，这样出了问题才能快速定位，而不是面对一堆乱码文件无从下手。这套“解析、转换、校验、日志”的闭环，比转换算法本身更重要。
本文还有配套的精品资源，点击获取
