Java导出复杂Word新思路：模板引擎+XML代替POI硬编码

做Java后端的人，迟早会遇到一类让人头大的需求：导出Word。而且一旦到了“复杂”这个级别，比如动态表格、单元格合并、图片嵌入、页眉页脚区分，大多数人的第一反应是掏出Apache POI，然后写上几百行代码，调一个下午的单元格宽度，最后还被产品经理一句“这个样式不对”打回重做。这篇文章要聊的，是一条更贴近真实业务、维护成本也低得多的路：用FreeMarker或Velocity这类模板引擎，直接渲染Word的XML格式，把Word文件本身当成模板，Java代码只负责准备好数据。内容会讲清楚为什么这种方案能解决POI硬编码的痛点，Word XML底层到底是什么样的结构，以及一套可以直接照着写的完整实操流程，适合正在做报表、合同、验收单、简历等复杂Word导出的Java工程师参考。

1. 方案选型：为什么是“模板引擎 + Word XML”，而不是纯POI硬编码

1.1 先盘点一下POI硬编码的“痛点清单”

Apache POI是目前Java生态里操作Office文件最常用的库，它确实强大，但强大不等于好用。尤其是导出复杂Word时，POI暴露出来的问题非常现实。第一是代码量爆炸：你要创建一个带合并单元格的表格，需要手动计算行数和列数，调用 mergeCells、setCellMargins、setWidth 这一堆API，一段十行的表格渲染逻辑常常写出一百行Java代码。第二是样式难以控制：Word里的样式体系非常复杂，字体、间距、边框、缩进、分页符都有对应的XML属性，POI虽然封装了一部分，但很多细粒度样式还是要你手动拼CTP、CTR这些底层对象，本质等于直接写XML，却比写XML更啰嗦。第三是维护成本高：需求一旦变化，比如表格增加一列、段落加粗、页眉换文案，都得改代码重新发版，业务人员和开发人员的沟通成本极高。

这些问题在“一次性简单导出”场景下还不明显，但凡是真实业务里的合同、报价单、验收报告，往往动态性极强，而且样式要求严格贴合业务方提供的样例Word。用POI从零构造这种文档，Coding的体感就是在“手工搭积木”，一边搭一边还要猜“Word到底是怎么记录这些样式的”。所以当我第一次尝试“模板引擎渲染Word XML”这个方案时，最大的感慨是：原来Word一直躺在那里告诉你怎么做，只是我们用错了工具。

1.2 模板引擎的思路：Word本身就是一份XML，为什么不让模板引擎来填充

这里要理解一个关键事实：Word的docx本质是一个zip压缩包，里面装的全是XML文件，而更早的Word还有一种“Word 2003 XML”格式，整个文档就是一份单独的XML文件。不管哪种形态，文档内容在底层都是标签树，比如段落是 <w:p>，文字段是 <w:r><w:t>，表格是 <w:tbl>。既然本质是XML，那模板引擎这类专门做文本填充的工具就天然适合干这件事。你先把做好的Word另存为XML，把需要变化的位置替换成 ${xxx} 或 #foreach 循环，然后用FreeMarker或Velocity把数据填进去，生成一份新的XML，再用Word打开，就是一个完整的、样式和模板完全一致的Word文档。

这个思路最爽的地方在于，样式问题被彻底绕开了。你在Word界面里把字体、颜色、边框、对齐全部排好，剩下的交给XML标签去保留，Java代码里连一个 setBold 都不用写。业务方改样式，也只需要改模板Word再另存成XML，不需要开发介入。这大概是所有方案里“老板改需求最不疼”的一种。

1.3 Word XML的两种落地形态：2003 XML 与 docx 解包重打包

在实际项目里，用模板引擎跑Word XML有两种常见落地方式。第一种是直接使用“Word 2003 XML文档”格式，也就是文件名后缀为 .xml、根节点叫 <w:wordDocument> 的那一种。它最大的优势是简单：整个文档就是单文件XML，直接当成FreeMarker的模板文件渲染，保存成 .xml 后Word可以直接打开，也可以改后缀为 .doc 给老版本兼容。第二种是处理现代 .docx，思路是先解压docx，编辑内部的 word/document.xml，渲染完成后再重新打成zip包。这种方式更贴近现在办公默认的docx格式，但复杂度也上去了：压缩包里的 [Content_Types].xml、_rels/.rels、图片资源路径都要处理，稍有不慎就会生成一个“Word提示文件已损坏”的文件。

从实践体感来说，我的建议是最小闭环阶段优先选Word 2003 XML方案，因为它的反馈链路最短，模板见效果快，适合快速落地。等跑通之后，如果业务方硬性要求必须输出docx，再考虑把2003 XML生成的结果另存为docx，或者走docx解包重打包的路子，但那是在前一种方案稳定后才值得去做的优化。

1.4 FreeMarker还是Velocity：一张表讲清楚

标题把FreeMarker和Velocity并列是有原因的，这两个都是在Java里非常有年代感的模板引擎。FreeMarker语法丰富，内置方法多，像日期格式化 ?string('yyyy-MM-dd')、空值处理 !、集合操作 ?size，做文档渲染非常顺手。Velocity语法相对轻量，#set、#foreach、#if 简单直白，老项目用得非常多，但要处理复杂逻辑时往往需要额外挂工具类。下面这张表可以帮你快速做选型。

结论很直接：新项目、没有历史包袱，选FreeMarker；老项目已经大量使用Velocity，或者团队对Velocity熟悉，继续用Velocity也完全没问题，因为本文这套方案本身不依赖特定引擎的独有功能，核心是“模板引擎 + XML渲染”的组合方式。

2. 吃透Word XML结构：模板引擎能搞定的底层逻辑

2.1 先认识 Word 2003 XML 的骨架

在动手做模板之前，至少要能看懂一份Word XML。这里不要求你背下所有标签，但主干结构必须清楚。一份最简单的Word 2003 XML是这样开头的：

xml复制<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?mso-application progid="Word.Document"?>
<w:wordDocument xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml"
                xmlns:v="urn:schemas-microsoft-com:vml">
    <w:body>
        <w:p>
            <w:r>
                <w:t>这是正文内容</w:t>
            </w:r>
        </w:p>
    </w:body>
</w:wordDocument>

这里面的层次逻辑其实很直观：w:body 是文档正文的根容器，w:p 是段落（Paragraph），w:r 是文字运行区间（Run），w:t 才是真正存放字符串的节点。你用Word排版时，一个回车就是一个段落，一段连续同样式文字就是一个Run。模板引擎要做的，就是把这些节点里的文字替换成动态数据，或者把某个表格行包裹进循环标签里。理解这个“段落 → Run → 文本”的三层结构基本就够了，剩下就是在模板里寻找理论上可以插入标签的位置。

2.2 表格、图片在XML里的关键节点

复杂Word里通常离不了表格，表格在XML里的结构是 w:tbl（表格）包裹若干 w:tr（行），每行里又有若干个 w:tc（单元格），单元格内再嵌套段落和Run。比如一个两行两列的表格，简化后的XML结构大概是：

xml复制<w:tbl>
    <w:tr>
        <w:tc>
            <w:p><w:r><w:t>表头1</w:t></w:r></w:p>
        </w:tc>
        <w:tc>
            <w:p><w:r><w:t>表头2</w:t></w:r></w:p>
        </w:tc>
    </w:tr>
    <w:tr>
        <w:tc>
            <w:p><w:r><w:t>${item.name}</w:t></w:r></w:p>
        </w:tc>
        <w:tc>
            <w:p><w:r><w:t>${item.price}</w:t></w:r></w:p>
        </w:tc>
    </w:tr>
</w:tbl>

图片则稍微特殊一点，Word 2003 XML里的图片通常通过 <w:pict> 节点引入，图片的二进制数据经Base64编码后放在 <w:binData> 里，再被 <v:imagedata> 引用。理解这些节点，是为了后续在模板中“插入循环”“插入图片”时知道该往哪个位置包标签。你不需要背下来，但打开一份XML能大致看懂哪里是正文、哪里是表格、哪里是图，这就够了。

2.3 占位符被拆散：新手最常见的翻车点

用Word另存XML时有一个很坑的细节：你在Word界面里输入的一串文字，存成XML后并不一定完整地躺在同一个 <w:t> 里。Word会根据“排版需要”把一个单词或词组拆成多个Run，比如 ${name} 可能被拆成 ${na 和 me} 两段，甚至每个字母一个Run。这会导致模板引擎渲染时完全匹配不到占位符，最后生成出来的文档里还残留着 ${name} 这样的裸文本，排查起来非常恼火。

解决办法有两个。第一个是“替换法”：在Word模板里先用一串不会引起歧义的普通文本当占位符，比如 __name__、@@name@@，另存XML后用文本编辑器的查找替换，把这些占位符统一替换成 ${name}，再把 <w:t> 节点之间的差异忽略掉，因为你要的只是一段可被模板引擎识别的纯文本。第二个是“同样式合并法”：在Word里选中占位符文字，确保它全部是同一个字体、同一个字号、同一种加粗状态，这样另存XML时有一定概率合并在同一个Run里，但不能100%保证。我的经验是把第一招当主力，稳妥、可控、不依赖Word的“心情”。

3. 实操全流程：用FreeMarker生成一份带表格和图片的复杂Word

这一章会给出一个完整的实战案例，场景是生成一份“项目验收报告”，里面包含大标题、项目基本信息段落、一个动态行数的设备清单表格、一个带页眉的说明段落以及一张嵌入的现场图片。整个过程分成六步，每一步都很关键。

3.1 第一步：用Word排版并另存为XML

首先在Word里做一份最终的样例文档，把所有固定内容写好，把需要动态变化的位置先用普通文本占位符替代。比如标题位置写 __title__，项目名称写 __projectName__，设备清单表格保留一行作为模板行，单元格里写 __deviceName__、__deviceNum__、__deviceRemark__。注意，图片位置可以先随便插入一张占位图。排好后，点击“文件 → 另存为”，文件类型选择“Word 2003 XML 文档（*.xml）”。这一步通常能直接成功，少数情况下如果文档里用了过新的特性，Word会提示保存时会丢失某些功能，一般不用太在意，只要正文、表格、图片的排版正常即可。

存好后用VS Code或Notepad++打开这个XML，先不要急着改，而是用Ctrl+F搜索 __title__，看看它是不是完整地在同一个 <w:t> 节点里。大概率会看到被拆开的情况，这正是2.3里说的坑，接下来用文本编辑器的全局替换，把 __title__ 统一替换为 ${title}，其余占位符同理。如果碰上被拆散的，先手动把拆散的 <w:t> 节点合并成一段完整文本再换，或者直接在XML里把多段 <w:t> 拼成一个节点，这一步虽然有点琐碎，但处理过一次之后，后面再做模板就顺手了。

3.2 第二步：改造XML模板，加入FTL语法

把占位符替换成FreeMarker语法之后，模板文件就初步具备了动态能力。这个阶段要把模板文件重命名成 report.ftl.xml，后缀带 .ftl 是为了让FreeMarker加载时按模板处理，同时也便于IDE识别。打开模板，文件头保持原样，正文里可以看到类似这样的片段：

xml复制<w:p>
    <w:r>
        <w:t>${title}</w:t>
    </w:r>
</w:p>
<w:p>
    <w:r>
        <w:t>项目名称：${projectName}</w:t>
    </w:r>
</w:p>

如果是表格行要循环，找到设备清单表格里用来当模板行的那段 <w:tr>...</w:tr>，在它的前后分别加上 <#list deviceList as device> 和 </#list>。设备名称、数量、备注里的占位符则写成 ${device.name}、${device.num}、${device.remark}，也就是用循环变量去取对象属性。这里有一个实用细节：循环体外再放一个空行模板，或者在表格后保留一个空段落，否则某些版本的Word在渲染大量行时会出现表格被文件末尾“吃掉”的兼容问题，这是我在真实项目里踩过的一个坑。

3.3 第三步：Java端数据模型与渲染代码

数据模型就是普通的POJO。上面的例子中，需要一个 DeviceItem 类，包含 name、num、remark 三个字段，另外再加项目名称、标题、图片Base64等字段。然后写一个最基础的FreeMarker渲染方法：

java复制public class WordExportService {

    public void exportReport(Map<String, Object> data, OutputStream out) throws Exception {
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
        cfg.setDefaultEncoding("UTF-8");
        cfg.setClassForTemplateLoading(WordExportService.class, "/templates");

        Template template = cfg.getTemplate("report.ftl.xml");
        try (Writer writer = new OutputStreamWriter(out, StandardCharsets.UTF_8)) {
            template.process(data, writer);
        }
    }
}

调用时把数据装进Map，比如 data.put("title", "2024年度项目验收报告")、data.put("deviceList", deviceList)、data.put("imageBase64", base64String)，然后调用渲染方法，输出流写成 FileOutputStream，文件后缀保存为 .xml。生成后用Word打开，正常情况下样式和模板一致，动态内容全部就位。这一步的代码量其实很小，核心工作全在模板制作阶段。

3.4 第四步：处理动态表格行

动态表格行是复杂Word导出里最常见的需求。前面在模板里用 <#list> 包住了目标 <w:tr>，这就能实现行的重复生成。但实际操作时有两个点要额外注意。第一是表头行和表体行要保持结构一致：如果表头使用了跨行合并单元格，表体行的单元格结构也要完全对齐，否则生成后表格列宽会乱。第二是合并单元格的处理：如果某个单元格需要纵向合并，在XML里通常是上一行的 <w:tc> 带有 vMerge 标记，下一行对应位置不写内容但保留 vMerge 标记，你在做模板循环时，这类合并标记是在“模板行”里写好的，循环多少次都会原样保留，效果是每行都能跟上一行合并，这个特性用来做“设备类型跨行分组”非常顺手。

3.5 第五步：嵌入图片（base64方案）

图片在Word XML里本质是一段Base64字符串，所以FreeMarker模板里指定一个变量占位即可。操作上分两步：先用Python或Java的图片工具把图片读成Base64字符串，再丢进数据模型。模板XML中图片相关的关键片段大概是：

xml复制<w:pict>
    <w:binData w:name="wordml://picture00001.png">${imageBase64}</w:binData>
    <v:shape id="_x0000_i1025" type="#_x0000_t75" style="width:300pt;height:200pt">
        <v:imagedata src="wordml://picture00001.png" o:title="scene"/>
    </v:shape>
</w:pict>

Java端准备数据的代码大致是这样的：

java复制byte[] imageBytes = Files.readAllBytes(Paths.get("scene.png"));
String base64 = Base64.getEncoder().encodeToString(imageBytes);
data.put("imageBase64", base64);

注意图片大小。如果原图过大，Base64字符串会非常长，XML文件膨胀得厉害，Word打开和保存都会变慢。所以我在真实项目里会先对图片做压缩，控制在几百KB以内，特别是现场照片这种场景，压缩到宽度1200px左右完全够打印和在线预览。

3.6 第六步：生成、打开、验证

渲染完成后，得到的 report.xml 文件直接用Word打开，如果一切正常，会看到一份跟模板排版一致的动态文档。打开后建议做三件事：检查字体是否丢失、检查图片是否显示、检查分页是否符合预期。字体问题通常是模板里用了目标机器没有的字体而导致回退，这属于模板问题，在模板里统一字体就能规避；图片不显示则要去查Base64变量是否为空、binData 的 w:name 是否和 imagedata 的 src 指向一致；分页问题一般不影响内容，但如果要求严格，可以在模板里手动插入分页符，而不是依赖自动分页。

4. Velocity方案怎么写：老项目也能无缝接入

4.1 Velocity模板写法对照

虽然我推荐新项目用FreeMarker，但很多存量系统的技术栈里早就有了Velocity，这时候没必要为了导出Word强行引入新依赖。Velocity渲染Word XML的思路完全一致，只是模板语法略有区别。同样的表格循环，Velocity写法是：

velocity复制#foreach($device in $deviceList)
<w:tr>
    <w:tc>
        <w:p><w:r><w:t>${device.name}</w:t></w:r></w:p>
    </w:tc>
    <w:tc>
        <w:p><w:r><w:t>${device.num}</w:t></w:r></w:p>
    </w:tc>
</w:tr>
#end

Java端渲染代码用VelocityEngine：

java复制VelocityEngine ve = new VelocityEngine();
ve.setProperty(RuntimeConstants.RESOURCE_LOADERS, "classpath");
ve.setProperty("classpath.resource.loader.class", ClasspathResourceLoader.class.getName());
ve.init();

Template template = ve.getTemplate("templates/report.vm.xml", "UTF-8");
VelocityContext context = new VelocityContext();
context.put("title", "2024年度项目验收报告");
context.put("deviceList", deviceList);

try (Writer writer = new OutputStreamWriter(new FileOutputStream("report.xml"), StandardCharsets.UTF_8)) {
    template.merge(context, writer);
}

4.2 空值、日期格式化等细节差异

Velocity处理空值有一个细节要牢记：如果VelocityContext里没有放入某个变量，模板中写 ${projectName} 会原样输出 $projectName 字符串，导致Word里出现莫名其妙的变量名。解决办法是写 $!{projectName}，这个语法表示“如果变量为空则输出空字符串”。FreeMarker则用 ${projectName!''} 达到同样效果。两者都能保证模板渲染时不会因为空值报错，但格式不同，迁移时容易踩坑。另外日期格式化方面，FreeMarker内置了 ?string('yyyy-MM-dd')，Velocity老版本没有内置日期格式化，通常需要在Context里放一个工具实例，比如 context.put("dateTool", new DateTool())，然后在模板里写 $dateTool.format('yyyy-MM-dd', $report.date)。这些差异不算大，但足以决定一次调试要花多长时间。

4.3 我的建议：什么场景坚持用Velocity，什么场景换FreeMarker

如果项目里有大量既有的Velocity模板，比如邮件通知、HTML页面都基于Velocity，那导出Word也继续用Velocity，能减少团队学习成本，保持技术栈统一。如果导出Word是一个全新模块，而且未来还要面对较多复杂逻辑，比如多个动态区块、复杂的条件判断、嵌套的循环，FreeMarker的表达式能力和错误提示会更友好。实际项目里我见过两边混用的情况，只要把模板文件命名和后缀规范好，比如 *.ftl.xml 和 *.vm.xml，就不容易混淆。

5. 避坑指南：实际项目中的问题排查实录

5.1 生成的文件打不开，提示“内容有错误”

这是模板引擎渲染XML最经典的报错。出现这个提示，意味着渲染结果不是一份合法的XML。常见原因有几种，第一是数据里的特殊字符没转义，比如项目名称里出现 &、<、>，直接拼到XML里就会破坏结构；第二是模板本身的XML格式不完整，比如某个标签没闭合；第三是图片Base64字符串过长导致解析不完整。排查时建议先用文本编辑器打开生成的XML，检查占位符位置的输出内容，再用浏览器直接打开XML，浏览器会精确提示第几行第几个字符有问题。关于特殊字符，我的习惯是写一个工具方法统一清洗数据，把XML规范要求的5个转义符全部处理掉，再放进数据模型。

5.2 占位符没被替换成功，Word里残留 ${xxx}

这个问题十有八九是占位符被Word拆散到了多个 <w:t> 节点，前面2.3里讲过。解决方法是回到XML源文件，用整体替换思路处理。另外还有一种可能：占位符里有全角字符或空格，比如 ${ title }，模板引擎按变量名匹配时会失败。所以制作模板时，占位符一律用半角字符，里面不要有任何空格，尽量保持统一格式。

5.3 中文变乱码

乱码通常只有一个原因：编码不一致。XML文件头声明的是UTF-8，FreeMarker渲染时设置的也是UTF-8，生成文件时输出流也是UTF-8，这三者必须保持一致。如果从Word另存的XML头部声明的是GB2312，或者你手动改过模板文件的编码，随时都可能出乱码。我的做法是：拿到Word另存的XML后，第一时间用VS Code重新以UTF-8保存一次，统一编码，后面所有环节都默认UTF-8，基本不会遇到乱码。

5.4 图片不显示，Word里是个红叉或空白

图片不显示的排查优先级依次是：Base64字符串是否正确、w:binData 和 imagedata 的关联名称是否一致、图片编码后的字符串是否被模板引擎截断。Base64本身是一长串纯文本，只要模板里没有任何多余的空格、换行或字符集转换，一般情况下能正常工作。另外有些模板引擎默认会开启HTML转义，这虽然不会影响Base64，但会影响 & 这类字符，如果发现生成后的XML里 binData 内容被转义，需要关闭转义或单独处理。

5.5 模板文件一大就卡慢，渲染性能如何优化

Word 2003 XML格式的模板，内容一多文件体积自然不小，尤其嵌入了多张图片后，模板可能达到几十MB。FreeMarker加载大模板时，内存和解析时间都会明显上升。我的建议是拆分模板策略：把整个文档拆成多个小的模板片段，比如封面一个模板、正文一个模板、附件一个模板，渲染后再把生成的XML片段拼接起来；如果必须单文件，至少在服务启动时缓存Template对象，而不是每次请求都 getTemplate。实测下来，启动时加载一次之后，单次渲染几百KB的XML数据基本在几百毫秒以内，完全能接受。

收尾：一点个人经验

做Word导出这几年，我的体会是：凡是“样式复杂、格式多变”的导出需求，优先考虑模板引擎+XML，而不是一上来就写POI。先找业务方要一份最标准的样例Word，把它变成XML模板，再去填数据，这个思路能省掉大量无意义的编码和沟通成本。最后再分享一个小技巧：模板文件和生成代码里，所有占位符统一风格，比如都用 __xxx__ 做普通占位、 ${xxx} 做动态变量，这样后期维护模板时，只要搜一下就能分清哪些是还没替换的、哪些已经是模板引擎语法，排查问题会快很多。