简介一份面向 Java 后端与前端开发者的 Word 文档处理实战资源围绕 Apache POI 实现 Word 内容提取、Word 转 HTML并兼容 WPS、DOC、DOCX 等常见办公格式。资源包共 131 个文件压缩后约 726KB其中包含 92 个 xml 配置文件、22 个 jpeg 示例图片以及 java、class、properties、html 等源码与构建相关文件便于直接查看代码实现和运行效果。已有 1365 人学习下载。通过该资源可掌握利用 XWPFDocument、HWPF 等 API 遍历段落、读取字体颜色与样式、处理图片和表格最终生成可在网页中展示的 HTML同时还能了解 Maven 环境下 Spring Boot 测试类与前端页面的衔接方式。对需要做文档在线预览、内容抽取或办公文件格式转换的开发者有较高参考价值。1. 先搞清楚要什么Word转HTML本质是把内容和版式分开搬运做过两轮文档转换需求之后我最大的体会是Word转HTML不是另存为而是把docx、doc里存储的内容和版式信息重新翻译成浏览器能识别的HTML结构。批量场景下不可能让用户一个个打开Word再另存为服务端需要一套能自动处理的库于是就有了基于POI去做word内容提取、word转html这条路。这篇文章围绕“POI 处理 wps doc docx 转 html”讲透先选型再给可复现的代码最后把最常见的坑列成清单。适合服务端做在线预览、文档中台、批量抽取的开发者也适合要处理存量Word资料的新手。2. docx与doc的本质差异先选对POI入口再谈转换2.1 后缀只是表象docx是ZIP包doc是二进制容器判断格式的责任不在POI而在你。docx本质上是一个ZIP压缩包你可以用解压工具打开它里面是[Content_Types].xml、word/document.xml、word/media/这样的目录结构。正文、样式、图片各自作为独立的XML或二进制文件存放解析时只需要按XML节点去读非常规整。而老式的doc是OLE复合文档CFB整个文件是一个复杂的二进制容器文本、样式、图片按扇区分散存储读取时要从文件头开始逐层解析。这两种格式的解析模型完全不同所以POI里对应了两套API处理docx的XWPF处理doc的HWPF。这个差异在工程上直接决定了你的代码要怎么组织。最常见的做法是开工前先用扩展名分流.doc后缀走HWPF.docx后缀走XWPFWPS另存的doc同样按doc处理因为WPS生成的老格式doc在底层依然是CFB容器文件头没有品牌差异。用文件头魔数去判断也可以但扩展名分流在业务侧更直观排错时也少一层玄学。2.2 XWPF之于docxHWPF之于doc两条路线的能力边界XWPF这套API能把docx里的段落、表格、图片、样式映射成Java对象遍历顺序就是文档的阅读顺序。段落有getStyle()可以拿到样式IDrun里有图片和文本的混合内容表格能拿到行列和单元格文本。这些能力让docx转HTML变成一件可控的事情输出结构的还原度取决于你愿意写多少映射逻辑。HWPF就保守很多。它能把正文文本完整提取出来段落也能拿到一部分但表格单元格的内容经常混在一起合并单元格信息、图片在页面里的具体位置基本碰不到。硬要用HWPF还原复杂版式最终产物大概率是纯文字加一堆莫名空行连表格横竖都分不清。所以我处理老doc和WPS旧格式时默认按“内容提取”来做而不是“格式还原”。这也说明一个选型原则不要试图用同一套代码同时满足doc和docx。我给后端方案配路由时会写两个独立的转换器docx走完整HTML输出doc走提取文本再包装成简单HTML的降级路径。分开写的好处是docx的质量不会被doc的短板拖累排错时也能一眼定位到格式问题。2.3 先想清楚要“内容”还是要“版式”做技术选型前先回答一个问题这份HTML是给人看的还是给程序用的有的业务只是要从Word里抽正文、抽标题存到数据库做检索那根本不需要转HTML直接用XWPFWordExtractor拿纯文本就够了。有的业务是拿来在线预览需要保留标题层级、表格和图片位置这才需要完整走XWPF转HTML。把“内容提取”和“格式还原”分开看待会让整个方案简单很多。很多需求方嘴上说要“一模一样”实际验收时只看正文、标题和图片在不在。我的习惯是先把纯文本提取的接口做出来作为第一步再评估是否需要完整的HTML版式。这一步的关键是控制预期转换类需求最怕一开始就承诺像素级还原最后换来一堆抱怨。另一个容易忽略的点是内容提取的速度远快于格式还原。如果业务只要求可检索正文给一套纯文本接口就够了一个月跑上百万份文档也不心疼。反过来每条文档都要转完整HTML就得多考虑内存和超时问题这也是后面会展开的坑。3. 用POI把docx转HTML从最小实现到图片表格都不丢3.1 最小可用实现先让文字能出来先给一个能跑的完整类目标是把docx里的标题和正文变成HTML同时处理掉表格。代码不追求炫技但结构完整你可以直接编译运行import org.apache.poi.xwpf.usermodel.*; import java.io.*; import java.nio.charset.StandardCharsets; public class DocxToHtmlSimple { public static void main(String[] args) throws Exception { if (args.length 1) { System.err.println(用法: java DocxToHtmlSimple input.docx [output.html]); return; } File in new File(args[0]); File out args.length 1 ? new File(args[1]) : new File(in.getAbsolutePath() .html); StringBuilder sb new StringBuilder(); sb.append(!DOCTYPE htmlhtmlheadmeta charset\UTF-8\); sb.append(stylebody{font-family:sans-serif;line-height:1.6;max-width:900px;margin:0 auto;padding:20px;}/style); sb.append(/headbody); // try-with-resources 确保输入流关闭避免大文档占用文件句柄 try (InputStream is new FileInputStream(in); XWPFDocument doc new XWPFDocument(is)) { // 遍历正文段落把 Word 内置 Heading 样式映射成 h1~h6 for (XWPFParagraph para : doc.getParagraphs()) { String style para.getStyle(); String text para.getText(); if (text null || text.trim().isEmpty()) { sb.append(pnbsp;/p\n); continue; } String tag p; if (style ! null style.startsWith(Heading)) { int level 1; try { level Integer.parseInt(style.substring(Heading.length()).trim()); } catch (NumberFormatException ignored) { // 非数字的 Heading 样式按普通段落处理 } tag h Math.max(1, Math.min(6, level)); } sb.append().append(tag).append() .append(escape(text)) .append(/).append(tag).append(\n); } // 表格单独输出按行读取单元格 for (XWPFTable table : doc.getTables()) { sb.append(table); for (XWPFTableRow row : table.getRows()) { sb.append(tr); for (XWPFTableCell cell : row.getTableCells()) { sb.append(td).append(escape(cell.getText())).append(/td); } sb.append(/tr); } sb.append(/table\n); } } sb.append(/body/html); try (Writer w new OutputStreamWriter(new FileOutputStream(out), StandardCharsets.UTF_8)) { w.write(sb.toString()); } System.out.println(已输出: out.getAbsolutePath()); } private static String escape(String s) { if (s null) return ; return s.replace(, amp;) .replace(, lt;) .replace(, gt;) .replace(\, quot;); } }这段代码的逻辑分三步先拼HTML骨架再遍历XWPFParagraph输出段落最后遍历XWPFTable输出表格。每个文本节点都经过escape()转义防止文档里的、、破坏页面结构也会避免XSS注入风险。参数上有几个点值得说明。new XWPFDocument(is)传入的是FileInputStream简单直接但超大docx建议改用OPCPackage.open(file)再构造文档省一层内存拷贝。para.getStyle()拿到的不是显示名称而是样式ID不同模板里的Heading定义可能带前缀比如“Heading1”或“1”这里只处理了最常见的情况。表格输出没有加tbody浏览器能正常渲染如果你们的质检工具严格可以补上。3.2 图片处理Base64内嵌与目录引用的取舍上面的代码会把图片整个丢掉这对很多业务是不可接受的。docx里的图片挂在段落run上需要用run.getEmbeddedPictures()逐个取。下面这段增强逻辑解决“图片在原文中的位置”问题// 传入段落对象遍历其中的每个 run把图片以内嵌 Base64 形式输出 private static void appendParagraphContent(StringBuilder sb, XWPFParagraph para) { for (XWPFRun run : para.getRuns()) { // run 里可能既有文本又有图片按顺序追加 for (XWPFPicture pic : run.getEmbeddedPictures()) { byte[] data pic.getPictureData().getData(); String ext pic.getPictureData().suggestFileExtension(); // Base64 内嵌的好处是不用维护图片目录坏处是体积增加约 1/3 String b64 java.util.Base64.getEncoder().encodeToString(data); sb.append(img src\data:image/) .append(ext) .append(;base64,) .append(b64) .append(\ style\max-width:100%;\/); } } }逻辑说明先把段落里的所有run取出来每个run内部既能取文本也能取图片图片数据通过getPictureData()拿到字节数组再用Base64编码塞进src属性。图片的原始位置就保留在对应的段落里不会出现图片全部堆到页面底部的问题。参数说明Base64内嵌省去了图片落盘和路径管理但会让HTML文件膨胀约33%。如果文档里图片很多动辄几十MB的HTML页面浏览器打开一样卡。我一般会设置一个阈值单张图片超过200KB的改成提取到images/目录HTML里引用相对路径小于阈值的才用Base64。后面避坑部分会再展开说这两种方式各自容易出错的地方。3.3 POI依赖与版本几个常见的启动期报错转换代码写好了还得把依赖配对。POI的模块分得很细处理docx至少要引入poi-ooxml它同时会依赖poi、poi-ooxml-lite等基础模块。Maven坐标写成下面这样版本按你自己项目里使用的POI版本填写dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId !-- 版本号按项目实际情况填建议用当前稳定版 -- /dependency启动期最常见的两个报错一是NoSuchMethodError多半是项目里别的库传递依赖了一个旧版POI把新版的类覆盖了解决方法是检查整个依赖树统一POI全家桶的版本二是ClassNotFoundException: org.openxmlformats.schemas...说明缺少poi-ooxml-lite或xmlbeans相关模块把poi-ooxml的依赖完整带上就能解决。依赖配好之后建议先用一份最简单的docx跑通上面3.1的代码再逐步加图片、表格的处理。很多人一上来就把完整转换逻辑写完结果报错时分不清是格式问题、依赖问题还是代码问题。先让最小链路跑通后面加代码才有底气。4. 老doc与WPS产物的兼容方案能转换就转不能转就提取4.1 HWPF的真实边界老doc转HTML为什么容易翻车老doc和WPS保存的doc在POI里只能走HWPF而HWPF的能力边界决定了你不能对它期待太多。它能拿到正文文本能拿到段落文本和部分样式名称但表格的单元格顺序、图片的定位、批注、修订记录这些基本都是残缺的。真要去还原HTML版式你会发现表格的行列都对不齐图片不知道插在哪一段样式名也跟模板里定义的对不上。我处理过的老doc里最头疼的是两种一种是早期用WPS编辑后另存的doc内部引用了大量非标准样式标记一种是经过了多次跨软件编辑的doc文本流里混着不可见字符和异常控制符。这两种场景下HWPF提取出来的内容甚至会有段落错位的现象正文顺序正确但表格位置全部挤到文末。所以我对老doc的策略很明确这是一条提取通道不是转换通道。系统入口统一收doc服务端只承诺“提取正文文本并按段落包成简单HTML”不承诺还原表格结构、图片位置和字体样式。这样能把交付预期控制在一个能完成的范围也不至于为存量文档耗费太多开发成本。4.2 doc降级路径提取文本手动包装成HTML下面是老doc的标准处理方式用WordExtractor拿纯文本再按换行符手动输出p标签。注意处理老doc特有的单元格分隔符import org.apache.poi.hwpf.HWPFDocument; import org.apache.poi.hwpf.extractor.WordExtractor; import java.io.*; import java.nio.charset.StandardCharsets; // 老 doc 的统一入口提取文本后按段落包装成简单 HTML public class DocToHtmlFallback { public static String convert(File docFile) throws IOException { StringBuilder sb new StringBuilder(); sb.append(!DOCTYPE htmlhtmlheadmeta charset\UTF-8\); sb.append(/headbody); try (InputStream is new FileInputStream(docFile); HWPFDocument hwpf new HWPFDocument(is); WordExtractor extractor new WordExtractor(hwpf)) { String raw extractor.getText(); // 老doc的段落分隔符通常是 \r表格单元格之间用 \u0007 分隔 String[] paragraphs raw.split(\r\n|\r|\n); for (String line : paragraphs) { String clean line.replace(\u0007, ).trim(); if (clean.isEmpty()) { sb.append(pnbsp;/p\n); } else { sb.append(p).append(escape(clean)).append(/p\n); } } } sb.append(/body/html); return sb.toString(); } private static String escape(String s) { if (s null) return ; return s.replace(, amp;) .replace(, lt;) .replace(, gt;) .replace(\, quot;); } }逻辑说明WordExtractor.getText()返回的是老doc正文文本它会把段落分隔符、单元格分隔符都带出来。这里先按常见的换行符切段再把\u0007这个单元格结束标记替换成空格避免表格内容粘连成一块。这段代码有几处要注意。raw.split(\r\n|\r|\n)同时兼容Windows和Unix换行老doc里绝大多数是\r。escape()必须放在最后因为老doc的文本里经常有半角引号和尖括号不转义会在浏览器里显示异常甚至破坏页面结构。输出用UTF-8如果业务的老doc全是中文见后面乱码那节的补充处理。4.3 WPS另存为docx后结构和差异点在哪儿WPS编辑的内容另存为docx之后底层依然是标准OOXML包结构XWPF能正常读取正文、段落和表格。但实际转换中会发现三个差异第一WPS对模板样式的命名在个别机器上会多出自定义前缀比如“WPSHeading”或“TOC1”导致3.1里用startsWith(Heading)的判断失效第二WPS生成的部分表格不显式声明边框属性而是依赖样式表继承POI读取时只能拿到文字边框在HTML里丢得一干二净第三WPS的公文类模板里经常带段前分页符转换出的HTML段落之间会出现大段空白看起来像排版稀疏。处理思路是样式判断不要只认固定前缀把拿到的styleId先打印出来看看再写映射表格边框不依赖源文件输出HTML时直接给table加CSS兜底段前分页符通过扫描段落属性里的pageBreakBefore标记来识别命中就输出一个分隔线而不是留白。这些细节说穿了不值钱但从WPS文档转出来的HTML质量往往就是靠这些细节拉开的差距。5. POI转HTML的常见坑现象、原因、解法都在这里5.1 图片不显示或全部堆在页面底部现象转换完的HTML里没有图片或者所有图片都集中出现在页面最底下像附录一样堆成一列。原因没有用run.getEmbeddedPictures()按段落取图而是直接调了doc.getAllPictures()拿到全部图片字节然后在遍历完所有段落之后统一追加到HTML末尾。甚至有人拿到了图片数据但没写img标签只把数据存在了变量里。解决图片必须挂在具体段落的run上取取到就立刻拼到当前的HTML流里。顺序就是文档阅读顺序。如果用了目录引用的方式还要确认HTML文件和图片目录的相对路径是否一致这是另一个常踩的点明明图片生成了页面里却是裂图。5.2 WPS表格转出来没有边框现象同一份表格微软Word里转出来有边框WPS里编辑过再另存的docx转出来就没有边框单元格内容是对的但整个页面像一张没格子的文本堆砌。原因WPS的表格可能不写w:tblBorders节点而是引用样式表里的边框定义。POI读取表格时只负责把单元格文本拿出来边框属于表格样式属性拿不到就自然丢掉了。解决输出HTML时给所有table加一套默认CSS边框不要依赖源文件是否声明。常见做法是table, td, th { border: 1px solid #999; border-collapse: collapse; }。如果业务要求保留部分表格无边框的原始效果那就需要在读取时检查tblBorders是否存在存在才输出对应样式不存在就输出默认边框。5.3 老doc提取中文乱码英文正常现象HWPF从老doc里取出的中文变成“锟斤拷”或直接是问号英文完全正常。原因老doc的中文编码依赖代码页信息文件头中的codepage声明缺失或被错误标记时POI会按默认映射读取字节中文环境最容易踩。还有一种来源是早期WPS生成的doc字符编码用的是本地化变种POI的HWPF对这部分支持不完整。解决先确认原始文档用了什么编码。能拿到原文件时优先在WPS里另存为docx再走XWPF这是最省事的路径拿不到U盘里的原文件时只能对WordExtractor.getText()返回的字符串做探测替换比如把无法解码的字节按GBK重新解码。注意这个操作要放在切段之前否则乱码区域会在切段时被拆散后续想修都找不到完整字节。5.4 大文档OOM或报Zip bomb现象一份几十MB的docx在本地转换没问题放到服务端一跑就OOM或者直接抛Zip bomb相关异常。原因XWPFDocument默认把整个ZIP包解压进堆内存文档里的内嵌图片、长XML节点都会放大内存占用。POI为了防止恶意压缩包攻击默认对ZIP条目的大小和压缩比做校验大图片或高压缩比的海量文本会命中安全阈值直接被拦下来。解决大文件不要用FileInputStream构造文档改成OPCPackage.open(file)再传给XWPFDocument。服务端要设上传大小上限一般超过30MB的docx建议走异步任务转换不要在线同步等待。安全阈值可以在特殊场景下放宽但需要同步评估上传来源是否可信。5.5 页眉页脚、页码、批注全部丢失现象源文档页眉有公司LOGO页脚有页码HTML里全都没有了批注也消失得无影无踪。原因XWPF的doc.getParagraphs()只遍历正文段落页眉页脚属于另一个关系要单独通过doc.getHeaderFooterPolicy()去拿。批注内容在注释关系里默认的遍历不覆盖。解决确认业务是否真的需要这些东西。在线预览场景里页眉页脚通常不是重点我会直接告诉需求方这些内容不在转换范围内。必须保留的需要在转换时读取页眉页脚的XML内容映射成HTML的顶部和底部区域。批注同理要单独解析comment关系。做完整版式还原的成本很高先把业务预期对齐再考虑要不要投入这部分工作量。6. 进阶用三份样张验证转换质量再决定投入方向文档转换这东西写代码只占一半验证占另一半。我现在每接一个转换需求都会先准备三份样张一份纯文字的普通docx一份带标题层级、表格、图片的复杂docx一份WPS保存或编辑过的doc。跑完转换后用下面这个清单逐项验收检查项预期结果不过时先排查什么标题层级一级标题出h1二级出h2样式ID映射逻辑是否覆盖实际styleId中文编码浏览器无乱码HTML的meta charset与代码转码逻辑表格完整性行列齐全、边框可见边框CSS是否兜底、合并单元格图片位置图片在正文对应段落出现run遍历顺序、Base64与目录引用兼容性三份样张都能产出HTML分流逻辑是否按后缀走对通道内容完整性正文与源文档一致抽取范围是否漏了文本框、表格内段落这份表跑完基本能判断当前方案值不值得继续投入。如果图片位置没法保证而业务又非要图片嵌在原文里你需要在Base64细节上多花时间如果业务只是要文本检索纯文本提取和简单HTML已经够用别在版式还原上死磕。进阶方向上如果想做得更稳可以把转换做成异步任务上传后先回执排队转换完再通知前端预览避免大文档把请求线程拖死。也可以考虑在POI之外留一个备用转换通道遇到POI处理不了的特殊文档时降级到其他工具保证系统“总能出结果”而不是卡死在某个格式上。我现在的习惯是接到文档转换需求先花半天写转换器再花一天做验证因为坑往往不在代码里而在文档的多样性上。要是只测试一份标准文档就上线后面各种对手件、WPS改过的、多人协作过的文件都会找上门。控制好边界规划好降级路径这套方案的维护成本其实很低。希望帮到你。本文还有配套的精品资源点击获取