1. 为什么选 docx4jHTML 转 Word 的方案对比与选型逻辑先交代一下我遇到的实际场景。业务线每天会生成几十份 HTML 报表页面里带完整的目录、表格、页眉页脚样式领导要求能一键导出 Word 用于盖章和归档。这个需求听起来不复杂但真正落地的时候会发现“HTML 转 Word” 从来都不是用一个第三方库调一个方法就能完美收工的事。HTML 的标签语义和 Word 的 OOXML 文档模型完全是两套体系中间要过的坎包括样式映射、表格栅格、图片资源、字体回退甚至还有编码问题。我当时的第一反应是 Apache POI。POI 是 Java 操作 Office 的老牌库社区大、资料多。但真正开始写就发现不对劲XWPF 的设计思路是让你从零开始构建 Word 文档一个段落要手动创建 XWPFRun一个表格要手动创建 XWPFTable然后挨个设置单元格的 tcPr、borders 这些底层属性。如果你的内容来源是后台富文本编辑器输出的 HTML你需要先把 HTML 解析成结构体再把这些结构体翻译成 XWPF 的各个对象这个翻译层的工程量非常大。更别说 HTML 里那些内联样式、嵌套列表、表格合并单元格用 POI 手工映射很容易写出几百行逻辑只为了处理一个表格。后来也评估过 Aspose.Words。转换效果确实好但商业授权费用对一个内部工具来说有点肉疼而且我这边需要高度可控的服务端批处理能力不希望把核心逻辑绑死在商业黑盒里。兜了一圈最后选定了 docx4j docx4j-ImportXHTML 这条路线。docx4j 的核心模型是基于 JAXB 的 OOXML 映射WordprocessingMLPackage 直接对应 docx 包的根MainDocumentPart 对应 document.xml。它的优势不在于提供一个“HTML 转 Word”的魔法方法而在于它把 Word 文档变成了一个你可以直接操作和检查的 Java 对象树。配合 docx4j-ImportXHTML 模块它会在服务端把 XHTML 解析成真正的 w:p、w:r、w:tbl 这些 OOXML 元素而不是把 HTML 塞进文档等 Word 自己解析。这是我很看重的一点。有人可能觉得Word 自己也能打开 HTML 文件但那种方式依赖客户端行为格式还原程度不可控而且 Word 处理非标 HTML 时很容易弹出“文件格式与扩展名不匹配”的提示。docx4j 的做法是从源头上把 HTML 翻译成原生 Word 内容生成的结果就是一个标准的、干净的 docx。从维护角度看docx4j 还有个好处它可以作为模板引擎使用。先用 Word 设计一个带占位符的模板然后用 docx4j 打开模板、在指定位置插入转换后的内容。这个能力对报表系统来说太重要了因为业务场景里通常不是从零生成 Word而是套用固定封面、固定页眉页脚、固定签章位置再把动态内容填充进去。下表是我当时整理的几个方案对比分享给同样在做选型的朋友参考。方案优势需要警惕的坑POI XWPF库轻量API 成熟可精细控制所有内容都得手工构建HTML 到 Word 的翻译层等于自己写一遍Aspose.Words转换质量高支持格式多商业授权价格高批量部署时要严格合规Word AltChunkWord 打开时自动渲染 HTML结果依赖 Word 客户端服务端不可控易触发安全提示docx4j ImportXHTML开源可控转换结果是原生 OOXML 元素学习曲线稍陡版本选型要仔细最终我选择了 docx4j这也是这篇文章后面所有讨论的基础。2. 环境准备版本选型与 Maven 配置选好技术方向后第一件事是搭环境。docx4j 这个库的版本变化比较大8.x 和 11.x 的接口签名、模块划分都很不一样。如果你是从别人的老项目里抄依赖很容易踩进“类找不到”的坑。我用的组合是 docx4j-JAXB-ReferenceImpl docx4j-ImportXHTML版本选 11.4.9。之所以选 ReferenceImpl是因为它使用独立的 JAXB 实现不依赖 JDK 内置的 JAXB在 Java 11 以及更高版本上跑起来更省心。如果你还在用 Java 8用 InternalImpl 也能跑但为了少一点环境差异建议直接上 ReferenceImpl。pom.xml 里的依赖配置如下properties docx4j.version11.4.9/docx4j.version /properties dependencies dependency groupIdorg.docx4j/groupId artifactIddocx4j-JAXB-ReferenceImpl/artifactId version${docx4j.version}/version /dependency dependency groupIdorg.docx4j/groupId artifactIddocx4j-ImportXHTML/artifactId version${docx4j.version}/version /dependency /dependencies这里有个容易踩的坑网上很多老教程写的是docx4j这个 artifactId但在 11.x 版本里主库已经被拆成了docx4j-JAXB-ReferenceImpl和docx4j-JAXB-InternalImpl两个方向如果直接引老坐标依赖解析会出问题或者拉到的是一个很老的版本。所以你要是新项目认准我上面这个组合就行。docx4j-JAXB-ReferenceImpl 会传递依赖一批 JAXB 相关的库比如 jakarta.xml.bind-api、jaxb-runtime 这类Maven 会自动处理不需要你手动加。但有一点要注意如果你的项目里已经有别的 JAXB 实现比如 GlassFish Jersey 或者老版的 JAXB RI建议把传递依赖排一下避免运行时出现 Multiple JAXB contexts 之类的冲突。另外Java 版本建议用 8 以上我实际测试 11 和 17 都没问题。如果你的服务运行在容器里注意给 JVM 留足内存因为 docx4j 在构建对象树时比较吃内存尤其是 HTML 里嵌套了大量表格时。后面我会在性能部分细说。依赖搞定后先别急着写业务代码。我建议先写一个最简 main 方法创建一个空的 WordprocessingMLPackage然后保存成一个 docx验证环境没有问题。这一步能帮你把“依赖缺失”和“业务代码 bug”这两个问题隔离开排查起来舒服很多。3. 核心实现从 HTML 到 Word 的转换流程3.1 先跑通一段最小可用代码先看一段能跑通全流程的 Java 代码。这段代码把一个 XHTML 字符串转换成 Word 文档保存成 output.docx。import org.docx4j.Docx4J; import org.docx4j.convert.in.xhtml.XHTMLImporterImpl; import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.openpackaging.parts.WordprocessingML.NumberingDefinitionsPart; import java.io.File; import java.io.FileOutputStream; import java.util.List; public class HtmlToWordDemo { public static void main(String[] args) throws Exception { // 1. 创建空的 Word 文档包 WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.createPackage(); // 2. 初始化默认编号定义处理 ul/ol 列表必须有这一步 NumberingDefinitionsPart ndp new NumberingDefinitionsPart(); ndp.unmarshalDefaultNumbering(); wordMLPackage.getMainDocumentPart().addTargetPart(ndp); // 3. 初始化 XHTML 导入器 XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); importer.setHyperlinkStyle(Hyperlink); // 4. 设置 baseURL图片和外部 CSS 会基于它解析 String baseUrl new File(src/main/resources).toURI().toURL().toString(); // 5. 准备 XHTML 内容 String xhtml !DOCTYPE html html langzh-CN head meta charsetutf-8/ style body { font-family: Microsoft YaHei, sans-serif; font-size: 10.5pt; } h1 { font-size: 22pt; color: #333; } table { width: 100%; border-collapse: collapse; } th, td { border: 1px solid #999; padding: 6px; } /style /head body h1自动化报告/h1 p这是正文内容支持b加粗/b、i斜体/i、u下划线/u。/p ul li第一项/li li第二项/li /ul table trth字段/thth说明/th/tr trtd版本/tdtd1.0/td/tr /table /body /html ; // 6. 转换返回的是 OOXML 内容对象列表 ListObject content importer.convert(xhtml, baseUrl); // 7. 把转换结果追加到主文档 wordMLPackage.getMainDocumentPart().getContent().addAll(content); // 8. 保存 try (FileOutputStream out new FileOutputStream(new File(output.docx))) { Docx4J.save(wordMLPackage, out); } } }这个流程看着简单但里面有几个必须注意的细节。第一个是 NumberingDefinitionsPart。docx4j 默认创建的空文档里没有编号定义如果不手动初始化HTML 里的ul和ol虽然也能转换但生成的编号是坏的Word 里打开列表项会被渲染成普通段落或者编号从错误的位置开始。unmarshalDefaultNumbering()会把 docx4j 内置的一套默认编号模板导入进来这样ul、ol才能正常映射成 w:numPr。第二个是 baseURL。XHTML 里的 CSS 外部样式表和图片引用都是基于这个路径去解析的。如果你不设置图片和样式会找不到。我通常会把 baseURL 设置成项目里的一个静态资源目录或者根据业务情况动态传入 HTML 对应的服务端路径。第三个是 importer.convert() 的返回值。它返回的不是一个新的 WordprocessingMLPackage而是一个 List里面装的是 XHTML 元素转换后的 OOXML 内容对象比如 w:p、w:tbl、w:sdt 这些。你可以把这个 List 直接塞进原有文档的 MainDocumentPart.getContent() 里实现“在已有文档中插入 HTML 内容”的效果。这是 docx4j-ImportXHTML 最实用的地方。3.2 先做一步 XHTML 清洗能省很多事HTML 和 XHTML 的区别没你想的那么小。后台编辑器输出的 HTML 是宽松模式的标签不闭合、属性不带引号、br不写自闭合这种情况在浏览器里没问题但 XHTMLImporter 是基于 XML 解析的遇到不合规的 HTML 会直接报解析异常或者静默丢内容。所以转换之前我建议先做一步 XHTML 清洗。我通常用 jsoup 做这件事。它本身就是 HTML 解析库能把不规范的 HTML 纠正成 XML 规范的 XHTML。import org.jsoup.Jsoup; import org.jsoup.nodes.Document; import org.jsoup.nodes.Entities; public String cleanHtmlToXhtml(String rawHtml) { Document doc Jsoup.parse(rawHtml); doc.outputSettings() .syntax(Document.OutputSettings.Syntax.xml) .escapeMode(Entities.EscapeMode.xhtml) .charset(UTF-8); return doc.outerHtml(); }这一步的作用是把 src 属性、空标签、布尔属性这些全部规范成 XHTML 能接受的形式。比如meta charsetutf-8会被补成meta charsetutf-8/br会变成br/。做完这步再交给 XHTMLImporter可以避免很多“莫名其妙丢样式”的问题。3.3 把内容插入已有 Word 模板前面说的是从空白文档开始生成但真实业务里更常见的是套模板。比如固定封面、固定落款、固定页眉页脚只在文档中间插入动态内容。docx4j 处理这种场景非常顺手。WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.load(new File(template.docx)); XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); importer.setHyperlinkStyle(Hyperlink); ListObject content importer.convert(xhtml, baseUrl); // 追加到文档末尾 wordMLPackage.getMainDocumentPart().getContent().addAll(content); try (FileOutputStream out new FileOutputStream(new File(result.docx))) { Docx4J.save(wordMLPackage, out); }如果你不想插到末尾而是插到某个占位段落后面可以先遍历wordMLPackage.getMainDocumentPart().getContent()找到锚点段落的下标然后用add(index, obj)插入。这个方法在做自动化报表时非常实用比如先用 Word 设计好封面页、声明页、落款页然后在中间预留一个空段落代码里找到这个段落的 index把转换出的 List 插进去最后另存为新文档。整个过程完全是服务端自动化不需要人工再打开 Word 去调整。4. 样式、表格、图片三大高频场景的处理细节4.1 CSS 样式映射到 Word 属性时别拿 Word 当浏览器docx4j-ImportXHTML 内置了一个 CSS 解析器能把常见的内联样式和style样式映射到 Word 的 run 属性上。映射关系大致如下CSS 样式映射后的 Word 属性说明font-familyw:rFonts中文字体建议显式写成 Microsoft YaHei 或 SimSunfont-sizew:sz注意 pt 与 px 的换算浏览器默认 16px 约等于 12ptfont-weight: boldw:bfont-style: italicw:icolorw:colorbackground-colorw:shdtext-decoration: underlinew:utext-alignw:jcborderw:tblBorders / w:tcBorders表格边框支持得比较好line-heightw:spacing需要特别提醒的是CSS 里那些布局控制属性比如 flex、grid、position: absolutedocx4j 是不会处理的。Word 的排版模型是流式的XHTMLImporter 能做的只是把文本语义、段落间距、字体层级映射过去。你在设计 HTML 模板时就要有意识地限制复杂度别指望 Word 帮你做响应式布局。我在实际项目中遇到过这种情况HTML 里用了大量 margin 和 padding 来控制元素间距转换后 Word 里的段落间距完全不对。后来把 HTML 模板里的样式全部改成 Word 友好的写法比如用空段落控制间距、用表格控制横向布局最终效果才稳定下来。4.2 表格列宽为什么拖不动怎么让它能拖搜过“word 表格列宽无法拖动”的朋友应该明白这个坑不是只有 docx4j 会踩任何 POI、docx4j 生成的表格都会遇到。问题的根源在于 Word 对表格列宽的控制靠的是 tblGrid 里的 gridCol 和每个单元格 tcW 的宽度值。如果表格没有 gridCol或者宽度值是 autoWord 打开后会进入自动调整模式用户拖表格线时列宽不会按预期变化甚至根本拖不动。要解决这个问题推荐在 XHTML 里把表格布局显式设为 fixed并通过 colgroup 定义列宽。table stylewidth:100%; table-layout:fixed; border-collapse:collapse; colgroup col stylewidth:25%/ col stylewidth:75%/ /colgroup tbody tr th名称/th th说明/th /tr tr tdwarp/td td固定布局测试/td /tr /tbody /table转换后docx4j 会在 OOXML 里生成对应的 tblGrid 和固定布局属性。用 Word 打开时表格属性里的“列宽”显示为具体值拖动表格线也能正常调整。如果转换后还是拖不动还有一个可能Word 里表格属性设置了“自动调整”把它改成“固定列宽”就行。实操时可以在 Word 里右键表格 → 表格属性 → 选项 → 取消勾选“自动重调尺寸以适应内容”。这里顺带说一句如果你在网上去搜“poi 设置 word 表格单元格宽度”会发现 POI 方案绕来绕去很繁琐。docx4j 至少提供了一个更符合直觉的路径在 XHTML 里定义好 colgroup转换时自动映射成 tblGrid省去手动操作底层对象。4.3 图片与 baseURL先解决资源路径再谈样式图片是 HTML 转 Word 里最容易出问题的一环核心还是 baseURL。.convert(xhtml, baseUrl)里的 baseUrl 决定了img srcimages/pic.png这种相对路径图片去哪里找。如果 baseURL 设置成file:///D:/temp/那么实际加载的就是D:/temp/images/pic.png。如果业务系统传过来的 HTML 里是相对路径的图片而服务端又没法直接暴露静态目录可以先在代码里把图片下载到本地临时目录再把 img 标签的 src 改成新路径最后设置 baseURL 为这个临时目录。这招在处理“html 邮件转 Word”场景时特别管用因为邮件正文里的图片经常是 CID 引用需要额外替换。另一个需要注意的点是图片体积。有些富文本编辑器会把大图直接 base64 内嵌到 HTML 里一个 src 动辄几百 KB。docx4j 转换时会把这些图片解出来放到 word/media 目录如果图片太多生成的 docx 会非常大而且转换时内存占用也会显著上升。建议在进入转换链路之前先对 base64 图片做一次压缩或者降采样。4.4 中文字体别指望系统帮你猜HTML 页面在浏览器里显示正常到了 Word 里变成宋体原因通常在 font-family。XHTMLImporter 会把 CSS 的 font-family 映射到 Word 的 w:rFonts但中文字体的定义方式有讲究。推荐在 CSS 里显式声明中文字体名body { font-family: Microsoft YaHei, 微软雅黑, sans-serif; }这样转换后 Word 的 west font 和 eastAsia font 才会正确设置。如果完全不做中文字体相关配置docx4j 会按默认字号和默认字体处理最终在 Word 里显示成宋体或者默认主题字体。还要注意一点字体能否最终正常显示取决于打开 docx 的那台机器是否安装了对应字体。你就算在 CSS 里写了 Microsoft YaHei对方机器上没有这个字体Word 照样会回退。要做导出工具的同学最好在需求阶段就跟业务方确认清楚目标文件会在什么环境被打开。5. 实际踩坑常见问题与排查清单以下是我在这套方案上踩过的坑整理成一张速查表方便大家排查。问题现象大概率原因处理办法Word 表格列宽无法拖动表格布局是 autofit或 tblGrid 没有正确生成在 XHTML 中使用 table-layout:fixed colgroup 定义列宽生成的 Word 中列表全变成普通段落缺少 NumberingDefinitionsPart手动调用 unmarshalDefaultNumbering() 并 addTargetPartWord 打开提示文档内容无法读取HTML 不是合法 XHTML或残留 AltChunk用 jsoup 清洗 HTML避免 AltChunk 方式Word 关闭时卡顿文档内含未处理的 AltChunk或大量外部资源引用统一走 XHTMLImporter 生成原生内容移除 AltChunk保存显示磁盘已满临时目录空间不足、输出目录权限问题、图片资源过多检查 java.io.tmpdir 和输出目录压缩图片中文乱码编码不一致统一 UTF-8Html 里带上 charset代码里用 getBytes(StandardCharsets.UTF_8)中文字体被替换成宋体CSS 未显式声明 eastAsia 字体设置 font-family 为 Microsoft YaHei 等中文字体单独展开几个重点5.1 为什么 Word 关闭时很卡根源基本都出在 AltChunk 上。如果你用addAltChunk(AltChunkType.Xhtml, bytes)的方式把 HTML 原样塞进 docxWord 打开文档后需要用自己的解析引擎把这段 HTML 再转一遍。HTML 越复杂Word 就越卡尤其在保存和关闭的时候它还要重新计算一遍格式。再加上 Word 对非标 HTML 的容错度很低很容易弹修复窗口或者直接崩。我的做法是所有需要转换的 HTML 都走 XHTMLImporter 处理成原生内容绝对不在最终文档里保留 AltChunk。这样生成的 docx 里没有需要 Word 二次解析的内容打开和关闭都很干净。5.2 Word 保存显示磁盘已满但不一定是磁盘真的满了报“磁盘已满”的时候多数人第一反应是看磁盘剩余空间但其实很多时候问题出在临时目录或权限上。docx 本质是 zip 打包docx4j 在转换和保存过程中会使用大量临时文件尤其是当 HTML 里嵌入了很多图片时。如果java.io.tmpdir指向的目录空间不足或不可写Word 在保存时就会误报磁盘已满。遇到这个问题先把 JVM 的临时目录换到一个有空间、可写的路径比如-Djava.io.tmpdir/data/tmp同时确认输出目录有写权限。如果是在 Windows 上跑还要留意杀毒软件是不是锁住了文件。5.3 列表编号异常大多数情况是忘了一步很多第一次用 docx4j-ImportXHTML 的朋友会遇到列表转出来没有编号的问题。这个我已经在前面强调过了就是缺少 NumberingDefinitionsPart。docx4j 的空文档里不带编号定义ul、ol样式会丢失所以创建包之后一定要执行NumberingDefinitionsPart ndp new NumberingDefinitionsPart(); ndp.unmarshalDefaultNumbering(); wordMLPackage.getMainDocumentPart().addTargetPart(ndp);这行代码不复杂但很容易被忽略尤其在你复制了网上老版本代码的时候有些版本的处理方式不太一样。6. 扩展经验批量自动化与后续演进建议6.1 批量转换时的线程与内存控制如果你不是单文档转换而是要做一个服务接口同时处理大量请求有几个点要注意。docx4j 的 WordprocessingMLPackage 不是线程安全的每个转换任务都应该有自己独立的包实例不能把同一个包放在多线程里并发操作。正确的做法是每个任务内部创建 WordprocessingMLPackage、创建 XHTMLImporterImpl、转换、保存各自独立互不干扰。内存方面docx4j 构建对象树时比较吃内存尤其遇到大表格、大图片时会更明显。我在一个批处理任务里同时跑 50 个文档的转换堆内存设了-Xmx2g都出现过 OOM后来把任务改成固定大小的线程池逐个消费内存才稳定下来。如果你的服务也是分批处理记住一点转换完一个就释放一个不要让中间对象堆积。另外如果图片来自网络 URLdocx4j 在拉取图片时没有做超时控制的话很容易因为某个图片响应慢拖垮整个任务。我建议在进入 docx4j 之前先把远程图片下载到本地替换 src 路径再交给转换器。虽然多一步代码但稳定性提升非常明显。6.2 Markdown、HTML 邮件等场景怎么复用这套链路这套 docx4j ImportXHTML 的方案只接受 HTML不接受 Markdown。但 Markdown 转 Word 的常见做法是先转成 HTML再走这套链路。社区里有很多 markdown 转 HTML 的工具例如 commonmark-java、flexmark先转成 XHTML再用同样的 XHTMLImporter 导入 Word整个过程很顺滑。HTML 邮件也是类似。很多企业内部的周报、通知都是 HTML 邮件正文格式相对简单没有复杂 JS 和动态布局非常适合直接转换。只要把邮件正文的 HTML 清洗成 XHTML再用上面的代码处理即可。PDF 转 Word 就不建议硬套这套方案了。PDF 是排版后的固定布局和 HTML 的流式模型不一样docx4j 没法直接解析 PDF。如果业务上确实有 PDF 转 Word 的需求可能需要单独选型渲染或 OCR 方案。6.3 公式、复杂表格和后续维护如果 HTML 里带了 MathJax 或 MathML 公式docx4j-ImportXHTML 目前不能完美转换成 Word 的原生公式OMML。我在项目里处理这个问题的办法是把公式先渲染成高清图片再替换到 HTML 里。虽然不能编辑但至少保证了视觉呈现一致。关于后续维护我有两个习惯建议。第一是锁定版本docx4j 的 API 在不同大版本间变化很大升级前一定要看迁移说明。第二是建立回归测试集把常见的 HTML 片段标题、列表、表格、图片、复杂样式存成测试用例每次升级依赖后跑一遍确认生成的 docx 还能用 LibreOffice 命令行转换成 PDF 做对比检查避免某个小版本更新引入隐藏问题。我现在还会在这个方案上继续做一些小改造比如用模板变量占位的方式把封面和正文分开处理再把转换后的 HTML 内容插入到指定书签后面这比直接从头生成文档要稳定很多。如果你正在做类似的 HTML 转 Word 服务希望这篇整理能让你少走一点弯路。