简介面向Java开发者与前端工程师的Word文档处理与转换资源基于Apache POI实现Word内容提取及Word转HTML覆盖.doc/.docx以及WPS生成文档的兼容处理。资源通过实际项目Demo演示如何读取段落、字体样式、图片与表格并将其转换为结构化HTML标签同时兼顾CSS布局与前端展示需求为内容管理系统或在线预览场景提供可落地的实现思路。资源包共131个文件压缩后仅726KB以xml配置、java源码、jpeg图片和html样例为主并附带Maven封装脚本与依赖jar便于直接导入工程运行。当前已有1353人学习下载适合具备一定Java基础、希望快速实现Word在线预览或文档转换功能的中级开发者。其中代码工程包含了完整的文档解析流程从XWPF/Document对象遍历到图片二进制提取与HTML生成均有对应实现同时引入WPS与微软Office的差异处理思路并给出前端页面中的表格、文本样式还原效果示例。借助该资源可大幅缩短自研文档转换模块的周期为后续扩展页眉页脚、超链接等高级特性提供基础。 做Word转HTML这个需求几乎每个做OA、文档预览、知识库的团队都会撞上。早些年大家习惯用Jacob调Word COM组件但服务器上装Office的成本和稳定性实在让人头疼后来转向POI方案的人越来越多。这个标题里的组合很有意思——word内容提取、word转html-POI、wps doc docx转html基本把国内文档处理的核心痛点都点出来了既要兼容Windows生态里的老doc又要处理新格式docx还得防着WPS保存出来的文件不按常理出牌。我前前后后用POI做过几轮Word转换服务踩过的坑比文档还厚这篇就把完整的实现思路和排坑记录整理出来给准备做或者正在做这个功能的同学一个参考。1. 动手前的格式判断为什么docx、doc和WPS文件必须分开对待很多第一次接触Word解析的人拿着一个FileInputStream就往POI里塞然后被一堆奇怪的异常砸懵。这里最关键的一点是Word的两种格式从底层上就是完全不同的东西POI对应的处理API也完全两套。1.1 docx是OOXML封装的zip包doc是OLE复合文档docx本质上是一个zip压缩包里面包含word/document.xml、word/media/、word/rels/等结构化文件。POI里对应的入口是XWPFDocument解析效率高、数据结构清晰图片、表格、样式都能顺着XML层级拿。doc则是微软早期的OLE复合文档格式二进制结构复杂POI对应的入口是HWPFDocument。HWPF的维护力度远不如XWPF很多doc里的高级格式比如嵌套表格、文本框、复杂的样式继承解析出来是残缺的甚至直接抛出UnsupportedOperationException。我在一次老文档迁移任务中统计过HWPF对doc的完整保真率大概在七成左右段落和基础字符没问题但版面细节就别指望了。1.2 WPS文件的特殊体质WPS保存的文件按照扩展名走docx或docPOI能识别并解析。但WPS有自己的私有格式描述尤其是涉及公式域、文本框、修订记录这些特殊对象时具备一定的兼容性偏差。比如WPS生成的docx在解析smartTag或自定义XML部分时POI有概率识别为未知元素而静默跳过。这也意味着不能用一套代码无脑处理所有Word来源要先识别文件类型再选择对应解析策略并且对WPS来源的文件做额外的校验和后处理。2. 基于POI 5.x实现docx转HTML主流程与关键代码当前主线方案用POI 5.2.x版本。老项目如果还在用3.x系列建议升级因为5.x在XWPF的样式解析上补了很多能力尤其是表格边框、段落间距、图片缩放这些转换时会直接用到的细节。2.1 依赖引入dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version5.2.5/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-scratchpad/artifactId version5.2.5/version /dependencypoi-scratchpad是HWPFdoc解析所在的模块只转docx的话可以不引但考虑到格式兼容性建议一并带上。2.2 核心转换代码import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.converter.core.XWPFConverterException; import org.apache.poi.xwpf.converter.xhtml.XHTMLConverter; import org.apache.poi.xwpf.converter.xhtml.XHTMLOptions; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.OutputStream; public class DocxToHtmlConverter { public static void convert(String docxPath, String htmlPath) throws Exception { try (FileInputStream in new FileInputStream(docxPath); OutputStream out new FileOutputStream(htmlPath)) { XWPFDocument document new XWPFDocument(in); XHTMLOptions options XHTMLOptions.create(); // 控制图片导出这里选择内嵌base64省去单独管理图片文件的麻烦 options.setExtractor(new FileImageExtractor(new File(D:/temp/images))); options.setURIResolver(new FileURIResolver(new File(D:/temp/images))); XHTMLConverter.getInstance().convert(document, out, options); } } }注意这里的XHTMLOptions有两个关键配置ImageExtractor决定图片落到磁盘还是转base64URIResolver决定HTML里引用图片的路径前缀。如果做单文件输出我建议用Base64EmbeddedImageExtractor直接把图片变成base64字符串塞进img标签里后续不用处理图片资源分发问题。代价是HTML体积变大一个2MB的docx转出来可能变成3~4MB的HTML适合内网传输或临时预览。2.3 导出图片的三种策略独立图片目录 相对路径引用适合大规模文档转换存储但需要保证图片目录和HTML一起迁移。base64内嵌适合单文件分发、预览但生成的HTML体积偏大。对象存储CDN把图片上传OSS返回URL填入src。适合在线文档系统。我实际项目里用的是第一种加第三种混合内网管理后台用base64公网分享走OSS。3. 老式doc文件的处理HWPF能力有限需要用这个补充方案3.1 HWPF能转但别期望太高import org.apache.poi.hwpf.HWPFDocument; import org.apache.poi.hwpf.converter.WordToHtmlConverter; import org.w3c.dom.Document; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.transform.OutputKeys; import javax.xml.transform.Transformer; import javax.xml.transform.TransformerFactory; import javax.xml.transform.dom.DOMSource; import javax.xml.transform.stream.StreamResult; import java.io.FileInputStream; import java.io.FileOutputStream; public class DocToHtmlConverter { public static void convert(String docPath, String htmlPath) throws Exception { try (FileInputStream in new FileInputStream(docPath)) { HWPFDocument wordDocument new HWPFDocument(in); Document newDocument DocumentBuilderFactory.newInstance() .newDocumentBuilder().newDocument(); WordToHtmlConverter converter new WordToHtmlConverter(newDocument); converter.processDocument(wordDocument); Transformer transformer TransformerFactory.newInstance().newTransformer(); transformer.setOutputProperty(OutputKeys.ENCODING, UTF-8); transformer.setOutputProperty(OutputKeys.INDENT, yes); transformer.transform(new DOMSource(newDocument), new StreamResult(new FileOutputStream(htmlPath))); } } }这个方案实测下来有几个明显的局限图片不会自动导出到文件或base64需要自己遍历HWPFDocument的字符流提取。表格的宽度、边框颜色、合并单元格信息大量丢失。文本框中的文字有可能丢失或者跑位。WPS保存的doc文件在HWPF里解析容易遇到段落属性读取失败。3.2 实用路线doc统一升级为docx再走XWPF路线从业务稳定角度出发我更建议后端搭建一个转换前置服务用LibreOffice headless模式把doc统一转成docx然后再走XWPF的完整通道。LibreOffice是免费的不需要Office授权Linux服务器上部署也很方便。soffice --headless --convert-to docx --outdir /data/convert /data/upload/old.doc这个方案解决了HWPF保真率低的问题因为LibreOffice内部对doc的解析比HWPF成熟得多转出来的docx再用POI解析表格样式和分页符的丢失率明显降低。注意转换前要确保系统安装了中文字体否则转出来的docx里的中文渲染会有问题实际是字体映射缺失导致显示异常但字体信息本身还在。4. 转换过程中最容易踩的五个坑及排查链路这部分是这篇的重点每一个都是我在真实业务中花了大半天甚至几天排查出来的。4.1 图片导不出或图片路径错乱现象docx里明明有图片但转出来的HTML中img标签缺失或者src指向了不存在的路径。排查链路先看XWPFDocument.getDocument()的XML里word/media目录是否存在图片文件。如果XML里有r:embed标记但media目录下没文件说明原文档的图片是链接引用没真正打包进docx。如果media里有文件但转出来没有img问题大概率出在XHTMLOptions的ImageExtractor实现上。POI的XHTMLConverter默认FilerImageExtractor存储路径处理有问题遇到相对路径异常就静默跳过。查看POI日志里有没有image not found之类的警告。我自己遇到过一次文档中用EMF格式插图POI的XWPF画布转换器不认识EMF直接跳过了。解决方案重写ImageExtractor把图片字节流直接写出并且用UUID重命名图片避免文件名冲突和特殊字符问题。4.2 表格样式大面积丢失现象转换后的HTML里table没边框、单元格宽度全乱、合并单元格变成了多个独立单元格。排查链路POI的XHTMLConverter在默认情况下对表格的样式输出精简到极致表格边框和背景色不会自动生成内联样式。合并单元格在处理时依赖w:vMerge和w:gridSpan两个XML属性POI在这块的解析逻辑偶尔会漏读gridSpan。解决方案转换后对HTML做一次表格样式补充——用Jsoup解析生成好的HTML遍历table标签凡是没设置border的统一补上border1和基础的内联样式同时根据原文档中每个单元格的gridSpan信息手动生成colspan属性。我建议写一个后处理工具类把表格样式修复和图片路径替换做成一个流水线避免在POI配置层死磕。4.3 中文字体变成乱码或样式被替换现象原文档用的是宋体HTML里却显示为默认黑体或者导出后中文全部变成问号。排查链路先确认原docx的font-family信息。POI读取到的字体名可能是宋体也可能是SimSun取决于文档是用什么输入法/软件生成的。如果HTML输出的meta charset不是UTF-8浏览器会按GBK解析中文字符直接乱掉。POI在转换时字体样式输出逻辑只认ascii码范围的字体映射中文字体经常不进style。解决方案在XHTMLOptions中设置字符编码为UTF-8并自定义一个字体解析器检测到中文字体名时强制映射到Web安全字体列表比如把宋体映射为SimSun, 宋体, serif把黑体映射为Microsoft YaHei, 微软雅黑, sans-serif。实测这样处理后浏览器渲染基本与原文一致。4.4 WPS生成的docx结构与标准OOXML有偏移现象WPS另存为的docxPOI解析时部分段落间距、缩进、项目符号消失某些自定义块直接不显示。排查链路用解压工具打开WPS生成的docx观察document.xml中paragraph节点里是否存在WPS自定义的标记比如w14:或wps:前缀的标签这些POI部分支持。检查WPS是否以兼容模式保存。WPS默认保存为docx时其实做了内部格式映射某些样式写在了w:pPr/w:pStyle中但styleId和标准Word命名不一致导致POI查样式表时匹配不到。解决方案对WPS来源的文档不要直接依赖POI解析出来的style定义而是额外跑一遍样式兜底——当发现某段落没有样式定义时从上一段落继承基本格式。这个方案不能百分百还原但能让内容完整呈现不丢段落。4.5 大文档转换内存溢出现象100页以上的图文混排文档转换时JVM频繁Full GC甚至OOM。排查链路POI的XWPFDocument默认把整个文档的XML都加载进内存图片也会按原字节流缓存大文档自然内存爆炸。5.x版本引入了POIXMLDocumentPart的流式读取机制但XWPFDocument本身仍然不是流式的。解决方案换用XWPFIterator逐段读取每次只解析一个段落转成HTML字符串后写入临时文件避免整个文档对象常驻内存。图片提取后立刻写入硬盘释放字节数组。给转换服务单独设置JVM参数-Xmx2g以上并开启CMS或G1实测G1对大文档友好。5. HTML后处理与线上实战建议POI转出来的HTML只是一个半成品直接输出到前端页面排版细节基本没法看。这里分享我线上运行的二次处理方案。5.1 构建HTML后处理管线POI原始HTML - Jsoup解析 - 补齐缺失图片 - 修复表格样式 - 清理无效标签 - 压缩内联样式 - 输出最终HTMLJsoup遍历Document节点树做统一处理比正则修改HTML靠谱得多正则遇到嵌套标签会疯掉。关键处理点给所有img加上max-width:100%防止大图撑破页面。表格统一加上border-collapse:collapse。删除POI生成的冗余span标签这类标签经常嵌套三层只为一个加粗。把style属性里的pt单位统一转成px或rem方便Web端展示。5.2 样式隔离在线预览页面如果套用全局CSS转换出的HTML段落很容易被站点样式污染。我建议给转换出的HTML外层套一个固定类名的容器然后在后处理阶段把会用到的所有样式全部内联化确保不依赖外部样式表。.word-preview-container p { margin: 0.5em 0; line-height: 1.6; } .word-preview-container table { border-collapse: collapse; width: 100%; }5.3 转换任务异步化大文档转换耗时动辄几秒甚至十几秒不能在请求线程里同步执行。我目前的架构是前端上传文档后后端立刻返回一个转任务ID转换完成后通过WebSocket或轮询通知前端拉取HTML。转换线程池用有界队列避免大量并发时把服务器内存打满。5.4 文本提取与转换分离的设计思路标题里特意提到了word内容提取这其实是另一个高频需求。做了转换功能后文本提取可以复用同一个解析流程先用XWPFDocument读取文档然后遍历段落、表格单元格、页眉页脚把纯文本拼接出来。注意要按文档流的顺序遍历否则表格里的文本会被挤到末尾影响摘要生成和全文检索的准确性。遍历顺序建议正文段落 - 表格中的文本按单元格顺序 - 文本框 - 页眉页脚每类元素之间用换行分隔。这样提取出的文本既能用于搜索引擎索引也能用来生成文档摘要和转HTML是两条独立但共享解析结果的分支。6. 一个完整的转换服务项目结构参考最后给一个我目前线上跑的项目结构可以直接抄作业word-converter/ ├── src/main/java/com/example/wordconv/ │ ├── controller/WordConvertController.java │ ├── service/ │ │ ├── WordConvertService.java │ │ ├── DocxToHtmlService.java │ │ ├── DocToDocxBridgeService.java │ │ └── HtmlPostProcessor.java │ ├── converter/ │ │ └── CustomImageExtractor.java │ └── util/ │ ├── FontMapper.java │ └── TextExtractor.java转换服务对外只暴露两个接口convertToHtml(fileId)和extractText(fileId)。内部根据文件扩展名路由到docx通道或doc通道doc通道先走LibreOffice升级再到docx通道。所有转换产物原始HTML、图片集、纯文本统一存OSS或本地存储数据库只记录文件状态和路径索引。这套方案从开发到稳定运行我前后迭代了快一个月其中后处理管线花了三分之一的精力。回过头看POI本身的转换能力只是基础真正决定线上体验的是那些边界情况的处理和展示层的适配。如果你们团队也在做类似的需求建议先把WPS生成的各种奇怪文件这个测试集准备好跑一遍再上线能少熬好几天夜。本文还有配套的精品资源点击获取