Apache POI 解析.docx转HTML会丢失样式和结构，仅适用于纯文本提取；推荐用docx4j并配置Saxon-XSLT引擎导出HTML5，避免使用已废弃的HWPFDocument处理.doc文件。
用 Apache POI 解析 .docx 文件再转 HTML 会丢样式和结构
POI 的 XWPFDocument 只能读取原始文本、段落、表格等逻辑结构，不保留字体、颜色、缩进、页眉页脚等渲染信息。直接遍历段落拼 HTML 标签（比如把 run.getText() 套上 <p>）看起来像 HTML，但打印或浏览器里打开会严重错位，尤其是含图片、列表、分栏的文档。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 仅用于提取纯文本摘要或索引场景，别指望它生成可交付的 HTML
- 若必须用 POI，优先处理
.docx（不是.doc），后者需额外引入HWPFDocument，已多年无维护，解析失败率高 - 图片默认不导出，得手动调
document.getAllPictures()并写入本地路径，再在 HTML 中用<img src="...">拼接——但原位置无法还原
用 docx4j 导出 HTML 更靠谱，但默认输出是 XHTML 且依赖 XSLT 引擎
docx4j 内置了基于 XSLT 的转换器，能较好保留标题层级、列表、表格边框、超链接，甚至支持部分 CSS 类名映射。但它默认输出的是严格 XHTML（比如 <br/>），现代浏览器虽兼容，但和手写 HTML 风格不一致；而且 XSLT 处理过程容易因 JDK 版本升级失效（如 JDK 17+ 默认禁用内建 XSLT 处理器）。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 添加 Maven 依赖时注意版本：
org.docx4j的docx4j-JAXB-MOXy（推荐）比老版docx4j-core更稳定 - 启用 HTML 导出前必须调用
WordprocessingMLPackage.load(new File("..."))，不能跳过加载阶段直接 new 对象 - 关键配置：设置
HtmlExporterImpl的setOutputXHTML(false)可得普通 HTML5 输出；用setEmbedImages(true)能把图转为 data URL，避免外部路径问题
遇到 “TransformerFactoryConfigurationError” 或空白 HTML 输出
这是 docx4j 在 JDK 8u291+ 或 JDK 11+ 上最常见的运行时错误，本质是系统找不到可用的 XSLT 实现。即使代码没报编译错，最终生成的 HTML 文件也可能为空，或只有 <html><body></body></html>。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 显式指定 XSLT 工厂：启动时加 JVM 参数
-Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl - 同时引入 Saxon-HE（如
net.sf.saxon的saxon-he12.x），不要用老版本，Saxon 10+ 才完整支持 XSLT 3.0 和 docx4j 所需扩展函数 - 检查
word/document.xml是否损坏：用 zip 工具打开 .docx，看里面word/document.xml是否可读——有些 Word 自动保存的临时文档会缺根节点，导致解析直接静默失败
想支持 .doc（二进制旧格式）？基本没实用方案
POI 的 HWPFDocument 对 .doc 的支持停留在 2013 年左右，连 Word 2010 保存的文档都常解析出乱码或空段落；而 LibreOffice headless 转换虽能跑通，但需要部署完整办公套件、占用内存大、并发差，且 Windows 下路径空格或中文常触发 ProcessBuilder 启动失败。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 直接拒绝接收 .doc 文件——告诉上游用户“只支持 .docx”，这是最省事的方案
- 真要兼容，用 Python 的
pywin32（Windows）或unoconv（Linux）做中转：Java 调用命令行转成 .docx 后再交给 docx4j，但要注意超时控制和进程僵尸问题 - 别信“纯 Java .doc 解析库”的宣传，目前没有稳定、开源、持续维护的实现
真正难的不是调哪个 API，而是 Word 文档本身就没有标准 DOM 模型——同一份内容，不同版本 Word 打开后 XML 结构可能完全不同。所以生成的 HTML 总会有妥协，重点是明确你的场景到底需要“能看”“能搜”还是“能印”，再选工具链。
