企业官网建设流程全解析

简介：面向在Java应用中需要将数据导出为美观Word文档的开发者，这套可运行源码演示了基于Apache POI在纯代码环境下完成图文混排、自定义表格与样式控制的全链路实现。资源包共14个文件、约25KB，主体含4个Java核心源码与Maven/XML配置，另附示例Excel数据、示例PNG图片、已生成的DOCX结果文档，以及较详尽的IDEA/Eclipse导入指南。代码覆盖从初始化文档对象、读取字节流插入图片、设置字体与段落格式，到构建多级表格并调整边框底纹、最终输出Report.docx的完整过程；同时体现依赖管理、代码组织等工程实践，从依赖引入到生成文件一次运行即可跑通。附带TODO清单与MD说明，可直接运行验证并改造复用。目前已有45人学习/下载，非常适合具备基础Java知识、需要快速实现报表导出或办公自动化的开发者。

1. 运营下午四点丢来一句话：能不能导成 Word

运营下午四点丢过来一句话：“那个活动方案能不能导成 Word？”等你真的动手做 Java导出Word文档，才发现这事没想象中简单：直接用字符串拼文件，Word 根本不认；用文本流硬凑，打开就报损坏；好不容易用 Apache POI 写出一个 docx，表格列宽又不听话，图片还偶发不显示。这篇笔记就是围绕“可运行源码”来写的——我把自己在多个内部系统里做导出功能的通用方案拆开讲，包含依赖选型、最小可运行代码、表格图片操作，以及最容易翻车的几个坑。适合后端开发在项目里快速落地“数据 → 可下载的 docx”这条链路；新手可以照步骤跑通，熟手可以直接跳到第 5 章对比自己踩过的雷。

2. 选型判断：POI、Word 模板引擎和商业组件，谁适合你的场景

2.1 POI 的生态位置：为什么它至今还是后端导出的默认选项

Apache POI 里的 XWPF 模块是专门处理 docx 格式的纯 Java 实现，不需要本机装 Office，这在服务端部署时是非常关键的优势。你只要引入 poi-ooxml 依赖，就能创建文档、段落、表格、图片等绝大部分元素。它和 Word 的文档模型是对齐的：XWPFDocument 对应整个文档，XWPFParagraph 对应一个段落，XWPFRun 对应段落里的一段连续文本，XWPFTable 对应表格。理解了这个对应关系，后面写复杂结构时就不会迷路。

POI 的优势是可控性强。你可以在代码里动态决定“要几个段落、表格几行几列、哪些单元格合并”，数据从业务层传进来，循环生成即可。它不做任何模板假设，也就不会被模板的固定结构卡住。缺点是 API 层次偏底层，写一个带样式的段落通常要两三层调用，入门阶段会觉得啰嗦。但考虑到社区资料量，遇到问题基本都能搜到答案，这是它在内部系统里经久不衰的理由。

2.2 FreeMarker 模板方案适合什么：从 Word 另存为 XML 说起

除了 POI，另一条常见路线是模板引擎方案。后端先找业务人员要一份排版好的 Word 文档，把文件另存为 Word XML 格式，再把需要动态替换的位置改成${变量}或<#list>标签，最后用 FreeMarker 渲染并改回 .docx 后缀。这个方案的好处是样式完全沉淀在模板里，写 Java 代码的成本极低，适合合同、通知书这类“格式固定、内容变长短”的场景。

但这个方案有它的脆弱面。Word 另存出来的 XML 体积大、标签冗余，只要模板里有一个不规范的标记，渲染后就可能打不开或者字体样式错乱。动态表格和循环段落需要手动往 XML 里插<w:tbl>和<#list>，一旦套了嵌套表格，调试成本直线上升。我一般这样判断：业务表结构半张纸能写清、每页版式几乎不变的，走模板方案；数据来自多张表、行数不固定、甚至某些区块要按条件隐藏的，老老实实用 POI 从代码里生成。

2.3 什么时候不该硬扛 POI：商业组件和边界判断

POI 并不是万能的。如果你的场景是几十页、带复杂样式、域、修订记录的老旧 .doc 文件，或者要求“Word 打开后和设计稿像素级一致”，POI 会很吃力——它重内容结构，轻排版还原，打印视图下和 Word 原生的细节差距是存在的。这类需求我见过有人用商业组件去做，效果确实好，但涉及授权费用，部署和合规都要评估。

我个人的判断标准很简单：内部系统、数据驱动的动态报表，POI 足够；对外交付、格式复杂度高、愿意为还原度买单，再考虑商业方案。不要为了一两次导出就在项目里引入一套重量级东西，后续维护成本很容易超过收益。选型这件事，从来不是“哪个最强”，而是“哪个在你这套代码里活得最久”。

3. 用 POI 跑通第一个导出：从依赖到可运行的最小工程

3.1 依赖清单：poi-ooxml 和它的版本暗坑

Maven 项目里引入 POI 的依赖并不复杂，核心就一个 poi-ooxml。但版本暗坑不少，我在 5.x 系列踩过一段：老项目里可能有人引了 poi 3.x 或者 4.1.x，新代码用了 5.x 的包路径，启动时直接 NoClassDefFoundError。所以在写功能之前，先统一项目里的 POI 版本，不要多个版本混搭。

<dependencies> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency> </dependencies>

这段依赖声明里，poi-ooxml 会传递引入 poi、poi-ooxml-lite、xmlbeans、commons-compress 等子模块。需要留意的点：xmlbeans 的版本和 poi 是强绑定的，如果项目里其他地方也依赖了 xmlbeans，极容易产生 jar 包冲突。解决方式是在工程根 pom 里用 dependencyManagement 统一版本，或者在排查报错时先看一眼 classpath 里到底加载了哪个 xmlbeans。很多“代码明明没问题，跑起来就报错”的情况，都是这一步没处理好。

3.2 最小可运行代码：标题、段落、表格一起输出

依赖引好后，直接写一个可以运行的类。下面的代码会生成一个带标题、正文段落和一个三行三列表格的 report.docx，覆盖了最常用的三块能力：段落、文本、表格。

import org.apache.poi.xwpf.usermodel.*; import java.io.FileOutputStream; public class WordExportDemo { public static void main(String[] args) throws Exception { // 1. 创建一个空白 Word 文档对象 XWPFDocument doc = new XWPFDocument(); // 2. 创建标题段落，setText 写入内容，setBold 加粗 XWPFParagraph title = doc.createParagraph(); title.setAlignment(ParagraphAlignment.CENTER); XWPFRun titleRun = title.createRun(); titleRun.setText("月度设备巡检报告"); titleRun.setBold(true); titleRun.setFontSize(22); // 3. 创建正文段落，addBreak 实现段内换行 XWPFParagraph body = doc.createParagraph(); XWPFRun bodyRun = body.createRun(); bodyRun.setText("巡检区域：A车间"); XWPFRun bodyRun2 = body.createRun(); bodyRun2.addBreak(); bodyRun2.setText("生成时间：2025-06-01 14:30"); // 4. 创建 3x3 表格，先填表头再填数据 XWPFTable table = doc.createTable(3, 3); String[] headers = {"设备编号", "设备名称", "运行状态"}; XWPFTableRow headRow = table.getRow(0); for (int i = 0; i < headers.length; i++) { headRow.getCell(i).setText(headers[i]); } String[][] data = { {"EQ-001", "空压机", "正常"}, {"EQ-002", "传送带", "待检修"} }; for (int r = 0; r < data.length; r++) { XWPFTableRow row = table.getRow(r + 1); for (int c = 0; c < data[r].length; c++) { row.getCell(c).setText(data[r][c]); } } // 5. 输出到本地文件，try-with-resources 确保流关闭 try (FileOutputStream fos = new FileOutputStream("report.docx")) { doc.write(fos); } doc.close(); System.out.println("生成成功"); } }

这段代码的逻辑很直白：先建文档，再建段落，最后建表格并逐格填充数据，整体走的是“文档 → 段落/表格 → run”这条链路。doc.createParagraph()会在文档末尾追加一个段落，paragraph.createRun()创建 run，一个段落里可以挂多个 run，所以同一段里要混排“加粗 + 普通文本”时，就拆成两个 run 分别设置样式，这是 POI 和 Word 对齐的地方。

参数说明：setFontSize(22)里的数值对应 Word 里的字号数值，实际显示大小以打开文档为准，觉得标题偏大或者偏小直接调整这个数。addBreak()是段内换行，和 Word 里的软回车一致，它不会像直接拼接\n那样失效。doc.createTable(3, 3)创建的是 3 行 3 列的空表，行列索引从 0 开始，所以循环填充时用的是getRow(r + 1)，跳过了已经写好的表头。运行后项目根目录下应该出现 report.docx，双击打开正常即表示链路通了。

3.3 参数说明：样式、间距、分页符怎么控制

跑通之后，很快会面临“调样式”的需求。我刚接触 POI 时最不习惯的是它很多参数的单位和 Word 里的设置不是一个体系，下面几个是高频用到的，直接列出来当参考。

段落对齐用paragraph.setAlignment(ParagraphAlignment.CENTER)，可选 LEFT、CENTER、RIGHT、BOTH，对应 Word 里的四类对齐。字体颜色用run.setColor("FF0000")，注意是六位十六进制字符串，不带#。字体族用run.setFontFamily("宋体")，中文字体必须显式设置，否则默认字体在部分环境下打开会变成宋体以外的字体，观感不对。

段前段后间距用paragraph.setSpacingBefore(200)和paragraph.setSpacingAfter(200)，单位是 twips，1 磅等于 20 twips，所以 200 就是 10 磅。行距用paragraph.setSpacingBetween(360)，同样基于 twips。分页符有两种写法：paragraph.setPageBreak(true)给整个段落加“段前分页”，适合章节标题；run.addBreak(BreakType.PAGE)在 run 的位置插入分页符，适合“当前段写到这里就必须另起一页”的场景。

这里有个容易误解的地方：setSpacingBefore设置在段落上而不是 run 上，如果设了没生效，检查是不是加到了错误的 paragraph 对象上。另外，docx 的间距逻辑是先作用段落再作用文本，段落本身没有内容也会占高度，用空段落做间距时留心别叠出一个大空白。

4. 把导出做成生产级：表格、图片、动态数据和循环段落

4.1 生产报表的标准姿势：用 Map 封装数据，代码不写死

最小示例能跑通之后，下一步就是把代码从 demo 改成“能接业务”的方法。我记得自己第一次做的导出就是把整段逻辑写在 Servlet 里，数据从请求参数里一个字段一个字段取，写完之后别人不敢改，自己也不敢动。后来我的习惯是：导出的入口只接收List<Map<String, Object>>和一个标题，剩下的都是内部循环。

public void exportReport(List<Map<String, Object>> rowData, String title, String outputPath) throws Exception { XWPFDocument doc = new XWPFDocument(); // 标题段落 XWPFParagraph titlePara = doc.createParagraph(); titlePara.setAlignment(ParagraphAlignment.CENTER); XWPFRun titleRun = titlePara.createRun(); titleRun.setText(title); titleRun.setBold(true); titleRun.setFontSize(18); // 动态表格：表头固定，数据行数由传入集合决定 XWPFTable table = doc.createTable(rowData.size() + 1, 4); String[] headers = {"设备编号", "设备名称", "运行状态", "备注"}; for (int i = 0; i < headers.length; i++) { table.getRow(0).getCell(i).setText(headers[i]); } for (int r = 0; r < rowData.size(); r++) { Map<String, Object> row = rowData.get(r); XWPFTableRow tableRow = table.getRow(r + 1); tableRow.getCell(0).setText(String.valueOf(row.get("equipId"))); tableRow.getCell(1).setText(String.valueOf(row.get("equipName"))); tableRow.getCell(2).setText(String.valueOf(row.get("status"))); tableRow.getCell(3).setText(String.valueOf(row.getOrDefault("remark", ""))); } try (FileOutputStream fos = new FileOutputStream(outputPath)) { doc.write(fos); } doc.close(); }

这个方法只做三件事：建文档、填数据、落盘。业务层把查询结果封装成 List

参数说明：表头数组是固定四列，如果业务列数不固定，可以把 headers 也作为参数传进来，在方法内动态生成表头。行数由rowData.size() + 1决定，加的一行留给表头。这套结构扩展性比较好，后面要加序号列、加汇总行，都只需要在循环里补代码，不用动整体框架。

4.2 表格操作：合并单元格、设置列宽和行高

表格做复杂起来最头疼的两种操作：合并单元格和列宽控制。先说合并，POI 里水平合并有两种方式，我常用的是在目标单元格上设置 gridSpan，让它横向跨过 N 列。

public void mergeHeaderCell(XWPFTable table, int rowIndex, int colIndex, int colCount) { XWPFTableCell cell = table.getRow(rowIndex).getCell(colIndex); // 设置 gridSpan，让当前单元格横向跨越 colCount 个列 cell.getCTTc().addNewTcPr().addNewGridSpan().setVal(colCount); }

这个方法的原理是给单元格的 tcPr 加一个 gridSpan 属性，告诉 Word“这个格子占了 N 列的宽度”，后续的单元格会被自动挤到下一段区域。常见的场景是表头第一行只有“巡检明细”四个字，下面一行才是真正的列名，这时在第一行做合并，第二行正常填列名，结构就跟 Excel 里的纵向合并区别开来了。

列宽控制是另一个高频坑。只调cell.setWidth("3000")常常不生效，因为 docx 里列宽是表格层属性优先。正确的做法是先定义表格级宽度和布局方式，再处理每一列。

// 表格总宽设置成页面内容区全宽 table.setWidth("100%"); // 锁定表格布局，禁止 Word 按内容自动调整列宽 table.getCTTbl().addNewTblPr().addNewTblLayout().setType(org.openxmlformats.schemas.wordprocessingml.x2006.main.STTblLayoutType.FIXED); // 给每一列设置固定宽度，单位是 dxa（1 英寸 = 1440 dxa） int[] colWidths = {2000, 3000, 2000, 2000}; for (int i = 0; i < colWidths.length; i++) { for (int rowIdx = 0; rowIdx < table.getNumberOfRows(); rowIdx++) { table.getRow(rowIdx).getCell(i).setWidth(String.valueOf(colWidths[i])); } }

注意setWidth("100%")设置的是表格相对页面的宽度，setWidth("3000")设置的是单元格绝对宽度（dxa）。两者混用时，先设总宽再设列宽，最后用 FIXED 布局锁住。如果不加TblLayoutType.FIXED，Word 打开时会根据单元格文字长度重新分配列宽，你设的数字只是“建议值”，这是很多人说“我设了列宽怎么没用”的根本原因。

4.3 图片插入：本地文件、网络字节流和尺寸控制

报表里插图片，常见两类来源：本地文件路径和远端 URL 返回的字节流。POI 的 addPicture 接口接收的是 InputStream，所以两种来源最后都归一到字节流上。下面这段覆盖了“远端图片 → 字节数组 → 插入文档”的完整链路。

public void insertImageFromBytes(XWPFDocument doc, byte[] imageBytes, String fileName) throws Exception { XWPFParagraph para = doc.createParagraph(); para.setAlignment(ParagraphAlignment.CENTER); XWPFRun run = para.createRun(); try (ByteArrayInputStream bais = new ByteArrayInputStream(imageBytes)) { // PICTURE_TYPE_PNG 是文档类型常量，必须和真实图片格式一致 run.addPicture(bais, Document.PICTURE_TYPE_PNG, fileName, Units.toEMU(480), Units.toEMU(240)); } }

这里的四个关键参数：Document.PICTURE_TYPE_PNG是图片类型枚举，支持 PNG、JPEG、GIF 等；fileName是图片在 docx 包内部的文件名，任意字符串都行，但最好保留扩展名；后两个参数是图片显示宽高，单位是 EMU，Units.toEMU(480)会把 480 像素按当前环境换成 EMU 数值，换算逻辑等价于 96 DPI 下的物理尺寸。

最常见的问题是图片类型和真实格式不一致。有些图片接口返回的虽然是.png后缀，但内容是 JPEG 编码，这时候还在代码里写PICTURE_TYPE_PNG，Word 打开就会报“图片无法显示”。我后来养成的习惯是：拿到字节流先读前几个字节判断真实魔数，再决定用哪个类型常量。另外，远端图片要考虑超时和断流，接口超时或返回 502 时字节数组可能不完整，addPicture 不会报错，但生成的 docx 打开图片是坏的，所以上游图片拉取要做超时控制和失败兜底。

5. 避坑清单：文件损坏、内存溢出、图片不显示，7 条血泪经验

5.1 文件损坏：一个没关的流就能让 Word 打不开

现象：代码执行完，文件也生成了，但双击打开时 Word 提示“文件已损坏，是否尝试修复”。

原因：docx 是个 zip 压缩包，写完后如果 FileOutputStream 没有正确关闭，尾部 zip 结束标记可能没写完整；另一种常见场景是doc.write(fos)之后立刻对同一个文件做二次读写，流还没 flush 就被别的逻辑覆盖了。

解决：统一用 try-with-resources 包裹输出流，doc.write()之后不要立刻返回，等doc.close()执行完再算结束。异常处理务必放 finally 或 try 块内，不能让异常的路径跳过流关闭。

5.2 内存溢出：导出大文档时 XWPFDocument 有多能吃内存

现象：导出几千行表格时，JVM 直接 OutOfMemoryError，或者 GC 频繁把接口拖垮。

原因：XWPFDocument 在解析和构建时会维护整个文档的对象模型，一个 5MB 的 docx 解压后在内存里可能膨胀到几百 MB。几千行表格的单元格对象数非常庞大，再加上图片字节流驻留内存，很容易打爆堆。

解决：一是先估算数据量，单次导出超过 2000 行时考虑分页导出或限制导出条数；二是图片字节流用完立刻置空，不要长期挂在对象里；三是给导出接口单独评估堆内存，或者让导出任务跑在异步线程池里，避免把 Web 容器主线程拖死。这个问题的本质是“内存里同时活着的对象太多”，优化方向不是调大堆，而是减少驻留对象。

5.3 图片不显示：二进制流和格式检查

现象：docx 能打开，但整张图是一块空白，或者提示“无法显示该图片”。

原因：图片类型常量写错，比如 JPEG 内容用 PNG 常量；也有可能是字节流被提前读取关闭，传入 addPicture 时流里没有数据。

解决：拉取图片后先做魔数校验。PNG 的前 8 字节固定是89 50 4E 47，JPEG 前 2 字节是FF D8，判断完再确定常量类型。同时把网络拉流的超时设短一点，失败时跳过图片并在备注列写“图片加载失败”，比生成一个坏文件强得多。

5.4 表格列宽失效：默认表格样式在作怪

现象：设置了每列宽度，打开文档后窄列被文字撑宽，表格整体超过页面。

原因：docx 表格在没有明确布局类型时默认是 autofit，Word 会根据单元格内容长度自动调整列宽，代码里的 setWidth 只是初始值。

解决：设置表格列为 FIXED 固定布局，并在表格属性里显式声明总宽。两者缺一个，列宽都可能被内容撑破。还有一个细节：合并单元格的列宽以合并前各列宽度之和为准，合并后单独改某一列的宽度没有效果。

5.5 换行不生效：\n在 XWPF 里的真实行为

现象：在字符串里写"第一行\n第二行"，setText 之后打开文档，两段文字连在一起没有换行。

原因：XWPFRun.setText 只是把字符串作为纯文本写入 XML，\n在 XML 里只表现为空格，不产生 Word 里的换行效果。

解决：段内换行用run.addBreak()，它会插入<w:br/>标签；想要真正分段，就创建新的 XWPFParagraph。如果你是从数据库字段里读出带换行的文本，先按\n拆成多个 run，逐个 addBreak，再 setText，这样文本的原始换行信息才能保住。

5.6 版本冲突：poi-ooxml 和 xmlbeans 的版本绑定

现象：引入 poi-ooxml 后启动报NoClassDefFoundError: org/apache/xmlbeans/XmlObject，或者运行时报java.lang.ClassNotFoundException。

原因：项目里原本有低版本 xmlbeans，被传递依赖覆盖或者 classpath 加载顺序不对，POI 5.x 需要 xmlbeans 5.x 才能正常工作。

解决：在 pom 里用 dependencyManagement 把 xmlbeans 版本固定到与 poi-ooxml 匹配的版本，检查是否还有其他依赖也带了 xmlbeans。这里有个排查技巧：运行mvn dependency:tree看 xmlbeans 的版本路径，如果出现两个版本，优先显式声明高版本消除歧义。

5.7 模板另存为 XML 后的乱码问题

现象：用 FreeMarker 渲染模板，生成的 docx 打开后中文全是乱码。

原因：Word 另存为 XML 时默认加了 BOM，但 FreeMarker 渲染后模板头部的编码声明没跟上，或者 Java 读取模板时用了错误的字符集。

解决：读取模板文件时强制指定 UTF-8，渲染输出时也指定 UTF-8；如果是从 Word 另存得到的 XML，打开文件看一眼头部有没有encoding="UTF-8"，没有就手动补上。这里多说一句：如果模板里包含特殊符号（如&、<），这些符号会被 Word 转成实体或标签，手改模板时别直接删掉，否则渲染阶段就会报错。

6. 一个可复用的兜底技巧：把 docx 当 zip 拆开，直接定位导出问题

代码写完了，但交付前最怕一句话：“这个文档打不开。”与其对着代码一行行猜，不如直接看 docx 里面装了什么——docx 本质是一个 zip 包，格式合法与否、内容结构对不对，拆开就知道。

排查的第一步是验证压缩包完整性和查看核心内容。

# 验证 zip 完整性，输出 OK 才是结构完整 unzip -t report.docx # 直接查看 document.xml，也就是正文内容 unzip -p report.docx word/document.xml

unzip -t会逐个文件校验 CRC，如果输出里有bad CRC或cannot find zipfile directory，说明文件根本不是一个完整的 zip 包，问题大概率出在流没关闭或者写入过程被中断。unzip -p则把正文 XML 直接打到终端，表格标签丢了、段落结构错了、图片引用缺失，在这里都能直接看到。

我做过一次印象很深的排查：表格边框全部丢失，代码里设了边框样式但客户反馈没效果。解压后看word/document.xml，发现tblPr里根本没有边框相关的tblBorders标签，再回头查代码，发现是往 cell 级别设置了边框，而表格级边框才是控制外框的地方。这类问题用调试器看对象状态也能查，但直接看 XML 更快，因为 XML 是 docx 的“源代码”，代码里写的每一步设置，最终都会反映到这层标签上。

我现在每次写完导出功能，都会顺手加一个参数，导出后自动把 document.xml 打印到日志里，只打印关键片段，比如表格数量和段落数，用于快速核对结构。这个习惯帮我省了大量无意义的联调时间。另一个衍生技巧是：如果某个样式设了不生效，先把当前的 XML dump 出来，搜一下对应的标签在不在，在就说明设置位置不对，不在就说明代码路径没走到。比对着 API 文档反复猜效率高得多。

从第一次在 Servlet 里手拼字符串被 Word 打回，到后来一套 POI 导出工具在多个系统里复用，我最深的体会是：导出功能看起来简单，但“能生成文件”和“能安全交付文件”之间，隔着一整层对 docx 结构的理解。把这层结构摸透后，你也能像修普通代码一样去修文档问题，希望这些经验和代码能帮到你。

本文还有配套的精品资源，点击获取