企业官网建设流程全解析

简介：这份资源面向Java后端与前端开发者，聚焦Word文档内容提取与Word转HTML的完整实现，基于Apache POI处理.doc、.docx及WPS文档，解决跨平台共享与网页展示中的格式转换问题。包内共131个文件，以92个xml配置、22个jpeg图片素材为主，另含properties配置、class字节码、java源码、mvnw与cmd构建脚本、jar依赖及html、md说明文档，压缩包约726KB，属于轻量级Maven工程示例。资源围绕文本、样式、图片、表格的提取与HTML标签映射展开，涵盖字体颜色、字号、加粗斜体等样式还原，图片经ImageIO转存后以img标签引用，表格则生成table、tr、td结构，并涉及WPS与DOC、DOCX的兼容性适配思路。目前已有1370人学习下载，适合需要快速搭建文档转换原型、理解POI API调用链路与HTML结构映射的开发者参考，也可作为前端优化展示效果的实践素材。

1. 从一份“文档地狱”说起：POI 把 Word 转 HTML 到底靠不靠谱

上周帮一个做企业知识库的朋友处理一批历史文档，三千多份.doc和.docx混在一起，要求全部转成能在浏览器里直接预览的 HTML，还得保留标题层级、表格和图片。他第一反应是找在线转换工具，结果批量上传卡死、格式错乱、图片丢了一半。我接手后用的方案是 Apache POI，准确说是XWPFDocument处理 docx、HWPFDocument处理 doc，再配合WordToHtmlConverter输出 HTML。这套组合在 Java 生态里算是老牌选手了，但坑也是真不少——字体丢失、样式错位、WPS 生成的文档结构异常，每一个都能让你加班到凌晨。这篇笔记就把我从环境搭建到批量落地的完整过程拆开，包括参数怎么调、哪些场景 POI 搞不定、以及我踩过的那些血泪坑。如果你手头正好有 Word 转 HTML 的需求，不管是做文档预览、内容迁移还是知识库入库，下面的内容应该能帮你省掉至少两天的试错时间。

2. POI 处理 Word 的底层逻辑：为什么 doc 和 docx 要分开对待

2.1 两种格式的本质差异决定了 API 不能混用

.doc是微软早期的二进制复合文档格式，内部结构像一个小型文件系统，用HWPFDocument来解析；.docx则是 OOXML 标准下的 ZIP 包，里面是一堆 XML 文件，用XWPFDocument处理。很多人第一次写代码时会想“能不能统一用一个入口”，答案是不能。POI 官方也没有提供统一的抽象层，你必须先判断文件后缀或魔数，再走不同的解析路径。

这个差异带来的直接影响是：.doc的样式信息存储方式更原始，POI 对它的支持也相对弱一些。比如.doc里的表格嵌套超过两层，HWPFDocument解析出来经常丢边框；而.docx因为结构清晰，XWPFDocument能拿到完整的段落属性、运行属性和样式继承链。所以如果你的文档以.docx为主，POI 的转换质量是可控的；如果.doc占大头，建议先做一轮格式升级，或者接受一定程度的样式损失。

2.2 WordToHtmlConverter 的工作机制与局限

WordToHtmlConverter是 POI 提供的一个转换器类，它继承自AbstractWordConverter，核心逻辑是遍历文档的段落和表格，把每个元素映射成对应的 HTML 标签。段落映射成<p>，表格映射成<table>，图片会被抽取出来存成文件或转成 Base64。但要注意，这个类最初是为HWPFDocument设计的，对XWPFDocument的支持是通过XWPFWordExtractor间接实现的，所以处理 docx 时有些样式属性拿不到。

我一般会重写WordToHtmlConverter的几个方法，比如processParagraph和processTable，在里面手动补充字体、颜色、对齐方式这些信息。下面是一个最小可运行的转换入口，先跑通再逐步加定制：

import org.apache.poi.hwpf.HWPFDocument; import org.apache.poi.hwpf.converter.WordToHtmlConverter; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.converter.xhtml.XHTMLConverter; 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.*; public class WordToHtml { public static void convert(String inputPath, String outputPath) throws Exception { File inputFile = new File(inputPath); String fileName = inputFile.getName().toLowerCase(); if (fileName.endsWith(".docx")) { convertDocx(inputFile, outputPath); } else if (fileName.endsWith(".doc")) { convertDoc(inputFile, outputPath); } else { throw new IllegalArgumentException("不支持的文件格式: " + fileName); } } private static void convertDocx(File inputFile, String outputPath) throws Exception { try (XWPFDocument docx = new XWPFDocument(new FileInputStream(inputFile)); OutputStream out = new FileOutputStream(outputPath)) { // XHTMLConverter 对 docx 支持更好，能保留更多样式 XHTMLConverter.getInstance().convert(docx, out, null); } } private static void convertDoc(File inputFile, String outputPath) throws Exception { try (HWPFDocument doc = new HWPFDocument(new FileInputStream(inputFile))) { Document htmlDoc = DocumentBuilderFactory.newInstance() .newDocumentBuilder().newDocument(); WordToHtmlConverter converter = new WordToHtmlConverter(htmlDoc); converter.processDocument(doc); Transformer transformer = TransformerFactory.newInstance().newTransformer(); transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8"); transformer.setOutputProperty(OutputKeys.INDENT, "yes"); transformer.transform(new DOMSource(htmlDoc), new StreamResult(new FileWriter(outputPath))); } } public static void main(String[] args) throws Exception { convert("input.docx", "output.html"); } }

这段代码的逻辑很直白：先按后缀分流，docx 走XHTMLConverter，doc 走WordToHtmlConverter。XHTMLConverter是 POI 后来补充的，对 OOXML 的支持比老转换器完整，能拿到段落缩进、行距这些属性。WordToHtmlConverter处理 doc 时，processDocument会遍历整个文档树，把字符属性和段落属性映射成内联样式。注意OutputKeys.INDENT设成yes只是让输出好看，对渲染没影响，但调试时能帮你快速定位结构问题。

2.3 Maven 依赖怎么选版本

POI 的版本选择有个原则：不要追最新，选稳定版。我目前用的是 5.2.x 系列，配合poi-ooxml和poi-scratchpad。poi-ooxml负责 docx，poi-scratchpad负责 doc，两个都要加。如果你只需要处理 docx，可以去掉poi-scratchpad，能省几 MB 的包体积。

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.3</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.3</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-scratchpad</artifactId> <version>5.2.3</version> </dependency>

版本不一致是常见翻车点。比如poi-ooxml用 5.2.3 而poi用 4.1.2，运行时会报NoSuchMethodError，因为内部 API 签名变了。统一版本号是最省事的做法。

3. 样式还原实战：字体、表格、图片一个都不能少

3.1 字体和段落样式的映射策略

POI 默认转换出来的 HTML 用的是<span style="font-family:...">这种内联样式，好处是兼容性强，坏处是文件体积大。如果你的文档动辄几十页，生成的 HTML 可能超过 1MB。我一般会做一层后处理，把重复的内联样式抽成 CSS 类。但这一步要小心，因为 Word 里的样式继承链很复杂，直接合并可能改变渲染效果。

字体丢失是最常见的问题。Word 文档里用了“宋体”“微软雅黑”，转成 HTML 后在浏览器里显示成默认字体，原因是 POI 拿到的字体名是中文，而 CSS 的font-family需要加引号或回退列表。解决办法是在转换后的 HTML 里做一次替换：

// 在输出 HTML 后做后处理，补充字体回退 String html = readFile(outputPath); html = html.replace("font-family:宋体", "font-family:'SimSun','宋体',serif"); html = html.replace("font-family:微软雅黑", "font-family:'Microsoft YaHei','微软雅黑',sans-serif"); writeFile(outputPath, html);

这个替换逻辑看着粗糙但有效。更稳妥的做法是重写WordToHtmlConverter的processRun方法，在生成样式字符串时就拼好回退列表。不过重写方法的成本较高，需要熟悉 POI 的内部类结构，适合对样式要求极高的场景。

段落对齐和缩进也容易出问题。Word 里的“首行缩进 2 字符”转成 HTML 后可能变成text-indent: 0，因为 POI 拿到的缩进单位是 twips（二十分之一磅），需要换算成 px 或 em。换算公式是px = twips / 20 * 96 / 72，简化后约等于twips * 0.0667。我一般会在后处理阶段统一做一次单位转换。

3.2 表格转换的边界处理

表格是 Word 转 HTML 的重灾区。POI 对简单表格的处理没问题，但遇到合并单元格、嵌套表格、斜线表头就容易出错。合并单元格的问题在于XWPFTable的getNumberOfColumns()返回的是最大列数，而实际每行的单元格数量可能不一致，直接遍历会数组越界。

我的处理方式是先构建一个二维矩阵，把每个单元格的gridSpan和vMerge属性读出来，再决定colspan和rowspan的值：

// 处理 docx 表格的合并单元格 for (XWPFTableRow row : table.getRows()) { int colIndex = 0; for (XWPFTableCell cell : row.getTableCells()) { CTTcPr tcPr = cell.getCTTc().getTcPr(); int colspan = 1; int rowspan = 1; if (tcPr != null && tcPr.isSetGridSpan()) { colspan = tcPr.getGridSpan().getVal().intValue(); } if (tcPr != null && tcPr.isSetVMerge()) { // vMerge 为 restart 表示合并起始行，continue 表示被合并 if (tcPr.getVMerge().getVal() == STMerge.CONTINUE) { continue; // 跳过被合并的单元格 } // 向下查找 continue 的行数来确定 rowspan rowspan = calculateRowSpan(table, row, colIndex); } // 生成 <td colspan="..." rowspan="..."> 标签 colIndex += colspan; } }

这段代码的关键是gridSpan和vMerge两个属性。gridSpan告诉你这个单元格横跨几列，vMerge告诉你纵向合并的状态。STMerge.CONTINUE的单元格要跳过，否则 HTML 表格会多出空列。calculateRowSpan需要自己实现，逻辑是向下遍历后续行，统计同一列位置vMerge为CONTINUE的数量。

嵌套表格更麻烦。POI 的XWPFTableCell里可以再取getTables()，但转换器默认不会递归处理。我一般会在processTable方法里加一层递归判断，如果单元格里有嵌套表格，就单独生成一段 HTML 再塞进去。注意嵌套层级不要超过三层，再深浏览器渲染也会出问题。

3.3 图片抽取与 Base64 内联的取舍

Word 里的图片在 docx 中是以二进制流存在word/media/目录下的，POI 可以通过getAllPictures()拿到。转换时有两个选择：存成独立文件用<img src="...">引用，或者转成 Base64 直接内联。前者适合图片多的场景，HTML 文件小、加载快；后者适合单文件分发，不用管图片路径。

我一般用 Base64 内联，因为知识库场景下 HTML 要入库，独立图片文件管理起来麻烦。转换代码如下：

// 从 docx 中抽取图片并转 Base64 List<XWPFPictureData> pictures = docx.getAllPictures(); Map<String, String> picMap = new HashMap<>(); for (XWPFPictureData pic : pictures) { String base64 = Base64.getEncoder().encodeToString(pic.getData()); String mimeType = pic.getPictureType() == Document.PICTURE_TYPE_PNG ? "image/png" : "image/jpeg"; picMap.put(pic.getPackagePart().getPartName().getName(), "data:" + mimeType + ";base64," + base64); }

拿到picMap后，在生成 HTML 时把<img>的src替换成对应的 Base64 字符串。注意 Base64 会让 HTML 体积膨胀约 33%，如果文档里图片很多，生成的 HTML 可能超过 10MB，浏览器打开会卡。这种情况建议还是存独立文件，用相对路径引用。

提示：WPS 生成的 docx 在图片存储上有时不符合 OOXML 标准，getAllPictures()可能返回空列表。遇到这种情况可以用OPCPackage直接读 ZIP 条目，绕过 POI 的封装。

4. 批量转换与性能调优：从单文件到三千份的工程化

4.1 批量处理的线程模型与内存控制

单文件转换跑通后，下一步就是批量。三千份文档如果串行处理，按每份 2 秒算需要 100 分钟，显然不可接受。我一般用固定大小的线程池，核心数设为 CPU 核数的 1.5 倍，因为转换过程有 IO 等待，适当超配能提高吞吐。

// 批量转换的线程池配置 int coreCount = Runtime.getRuntime().availableProcessors(); int poolSize = (int) (coreCount * 1.5); ExecutorService executor = new ThreadPoolExecutor( poolSize, poolSize, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue<>(500), // 队列容量限制，防止内存堆积 new ThreadPoolExecutor.CallerRunsPolicy() // 队列满时由调用线程执行 ); // 提交任务 for (File file : files) { executor.submit(() -> { try { WordToHtml.convert(file.getAbsolutePath(), outputPath); } catch (Exception e) { // 记录失败文件，不要中断整个批次 log.error("转换失败: {}", file.getName(), e); } }); } executor.shutdown(); executor.awaitTermination(1, TimeUnit.HOURS);

这里有两个关键参数：队列容量和拒绝策略。队列设成 500 是防止文件列表过大导致内存溢出，每个任务对象虽然不大，但积压多了 GC 压力会很明显。拒绝策略用CallerRunsPolicy是让提交任务的线程自己跑，相当于自动降速，比直接丢弃任务安全。

内存方面，XWPFDocument会把整个文档加载到内存，一份 10MB 的 docx 解析后可能占用 50MB 以上的堆空间。如果并发数太高，很容易 OOM。我的经验是堆内存 2GB 的情况下，并发数不要超过 8。可以在启动脚本里加-Xmx2g -Xms2g，避免堆动态扩展带来的性能波动。

4.2 转换失败的分类与重试策略

批量转换最怕的是个别文件失败导致整个批次中断。我的做法是把失败文件单独记录，按异常类型分类处理。常见的失败类型有三种：文件损坏、格式不支持、样式异常。

文件损坏的表现是OfficeXmlFileException或IOException，这种基本没救，直接跳过。格式不支持通常是.doc里嵌了 OLE 对象，POI 解析不了，可以尝试用HWPFDocument的getEmbeddedObjects()判断，如果有嵌入对象就标记为“需人工处理”。样式异常不会抛异常，但生成的 HTML 明显错乱，比如表格全部变成纯文本，这种需要人工抽检。

重试策略上，我一般只对IOException做一次重试，因为可能是文件被占用或磁盘临时问题。其他异常重试也没用，浪费资源。重试时加一个短暂的延迟，比如 500ms，给系统一点恢复时间。

4.3 输出 HTML 的清理与压缩

POI 生成的 HTML 里有很多冗余标签，比如空的<span>、重复的style属性、无意义的<o:p>标签。这些不影响渲染，但会让文件体积膨胀 30% 以上。我一般用jsoup做一次清理：

// 用 jsoup 清理 POI 生成的冗余标签 Document doc = Jsoup.parse(new File(outputPath), "UTF-8"); doc.select("span:empty").remove(); // 删除空 span doc.select("o\\:p").remove(); // 删除 Office 命名空间标签 doc.select("[style=]").removeAttr("style"); // 删除空 style 属性 // 压缩空白字符 doc.outputSettings().prettyPrint(false); String cleaned = doc.html(); Files.write(Paths.get(outputPath), cleaned.getBytes(StandardCharsets.UTF_8));

jsoup的prettyPrint(false)会去掉格式化缩进，能再省 10% 左右的体积。注意清理后要验证一遍渲染效果，有些空 span 虽然看着没用，但可能承载了 CSS 继承的断点，删掉后样式会变。我一般会保留一层抽检机制，随机抽 5% 的文件人工看一眼。

5. 避坑指南：那些让我加班到凌晨的 POI 问题

5.1 中文乱码：现象是浏览器打开全是问号，原因是编码没统一

POI 读取文档时用的是文档内部编码，输出 HTML 时如果没指定UTF-8，FileWriter会用系统默认编码，在 Windows 上就是 GBK。两者不一致就乱码。解决办法是全程用OutputStreamWriter指定StandardCharsets.UTF_8，并且在 HTML 的<head>里加<meta charset="UTF-8">。另外，Transformer的OutputKeys.ENCODING也要设成UTF-8，三个地方缺一不可。

5.2 WPS 文档结构异常：现象是段落丢失或表格错位，原因是 WPS 的 OOXML 实现有偏差

WPS 保存的 docx 在word/document.xml里有时会缺少w:pPr节点，或者把样式信息放在非标准位置。POI 按标准解析时就会跳过这些段落。我遇到过一次，一份 20 页的文档转出来只剩 3 页。解决办法是用OPCPackage直接读 XML，手动补全缺失的节点，或者用XWPFDocument的getParagraphs()遍历时加一层空判断，把没有pPr的段落也纳入处理。

5.3 图片丢失：现象是 HTML 里<img>标签的 src 为空，原因是图片关系 ID 没对上

docx 里的图片通过r:embed属性关联到word/_rels/document.xml.rels里的关系 ID。POI 的getAllPictures()返回的列表顺序和关系 ID 不一定一一对应，直接按索引取会拿错图。正确做法是用getPackagePart().getRelationship()拿到关系 ID，再和文档里的r:embed值匹配。这个坑我踩了两次才记住。

5.4 大文件 OOM：现象是转换到一半抛OutOfMemoryError，原因是文档太大且并发过高

一份 50MB 的 docx 解析后可能占用 500MB 堆空间，如果同时跑 10 个任务，2GB 堆直接爆。解决办法有两个：一是限制单文件大小，超过 20MB 的走单独的低并发队列；二是用XWPFDocument的流式读取模式，但 POI 对流式支持有限，XWPFDocument本身还是全量加载。我一般用第一种，简单有效。

5.5 样式继承断裂：现象是标题变成了正文样式，原因是 POI 没解析样式继承链

Word 的样式可以继承，比如“标题 1”继承自“标题”，再继承自“正文”。POI 的XWPFParagraph.getStyle()只返回直接样式 ID，不会向上追溯。如果文档里用了自定义样式，转换后就丢了层级。解决办法是手动读XWPFStyles，构建样式继承树，在转换时把父级样式合并进来。这个工作量不小，但如果你的文档对标题层级有严格要求，值得做。

6. 进阶技巧：用 XSLT 做二次加工与转换质量验证

POI 生成的 HTML 是“能用”级别，但离“好用”还有距离。我一般会在转换后加一层 XSLT 转换，把内联样式抽成 CSS 类，同时统一标签结构。XSLT 的好处是规则可配置，不同文档类型用不同的样式表，不用改 Java 代码。

<!-- simplify.xsl：把内联样式抽成 class --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="span[@style]"> <span class="{generate-id()}"> <xsl:attribute name="data-style"> <xsl:value-of select="@style"/> </xsl:attribute> <xsl:apply-templates/> </span> </xsl:template> </xsl:stylesheet>

这个样式表把每个带style的span转成带style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />