Word转FTL实战解析：用FreeMarker模板动态生成Word文档-代码聚汇网

Word转FTL实战解析：用FreeMarker模板动态生成Word文档

戈玄白今天要做题·2026-09-04·阅读 22 GEO检测（免费）

FreeMarkerWord转FTLWord 2003 XML

|难度：普通|阅读约 40 分钟

1. 先别急着“转格式”：Word 和 FTL 差着整整一个“世界观”

先说一个很多人忽略的事实：Word 根本不能“直接转成 FTL”，网上那些教程第一步就叫你另存为 Word 2003 XML，其实绕了一个大弯。

FTL 是什么？它是 Java 模板引擎 FreeMarker 的模板文件，本质是一段带占位符的纯文本。FreeMarker 拿到这份文本之后，会把它当成字符串逐字逐句地读，遇到 ${变量} 就替换成数据，遇到 <#if>、<#list> 就执行逻辑，最终拼出一份完整内容。所以 FTL 本身不关心你生成的是 Word、HTML、邮件还是普通 txt，它只负责“把文本算出来”。

但 Word 文档不是这种脾气。早期的 .doc 是私有二进制格式，你用记事本打开就是一堆乱码；后来的 .docx 虽然本质上是一堆 XML，但它被压缩包外壳包着，里面是 word/document.xml、word/styles.xml、word/media/ 等一大堆文件。FreeMarker 可不会自己拆压缩包，更不能理解 Word 的排版模型。如果直接把 .docx 改名成 .ftl 丢给 FreeMarker 渲染，结果往往不是 Word 乱码，就是渲染出来一堆无法识别的二进制内容。

理解了这层，再去搜“Word 转 FTL”就不会被绕晕了。所谓“Word 转 FTL”，准确描述是：选一种 Word 能打开、同时又是纯文本/可被 FreeMarker 处理的中间载体，把 Word 里的内容改造成带 FTL 标签的模板。为什么都在用 Word 2003 XML？因为它是这个场景里出现最早、资料最多、也最容易用文本编辑器直接上手的一种载体。

1.1 FTL 的本质是一张带占位符的白纸，它只认文本不认排版

你可以把 FTL 模板想象成一张写满了句子、中间留了很多空槽的答题卡：

code复制尊敬的${customerName}：
    您有一条新的告警工单，编号为${orderNo}。

当后端把 customerName、orderNo 填充进去，这张纸就变成了完整内容。FTL 的规则非常简单，变量用 ${} 包裹，逻辑标签用 <#xxx> 包裹，没有别的高深机制。

恰恰是这份“简单”，让所有希望把 Word 当模板的人踩进了同一个坑：Word 是富文本，它内部不仅记录“我写了什么字”，还记录“每个字是什么字体、什么颜色、有没有加粗、段落间距多少、当前是第几节”，这些信息以非常复杂的结构藏在文件里。FTL 没有能力理解这套结构，它只能机械地把模板文本输出。想让它生成 Word，唯一办法是：确保你输出的文本本身就是 Word 能认识的 XML 源码。

换句话说，Word 2003 XML 这个格式之所以能当 FTL 的“内容载体”，是因为它让 Word 内容和 FTL 处在了同一个维度上——模板里写的每一段、每一行、每一个表格，在保存成 Word 2003 XML 后都是一个一个带 <w:...> 标签的纯文字节点，可以直接用查找替换往里塞变量，渲染出来后再让 Word 自己打开。

1.2 doc 是二进制、docx 是压缩包，都没法直接拿来当文本改

很多人第一次手动改 Word 模板，会下意识把 .docx 改名成 .zip，解压出 document.xml，然后把里面需要动态变化的文字替换成 ${xxx} 再打包回去。这条路不是完全走不通，但它有一个致命问题：你解压出来的 XML 只是文档的“正文部分”，样式、页眉页脚、主题、兼容性设置全部分布在其他文件里。一旦你用文本编辑器手动改了 document.xml，却漏掉 styles.xml 或 [Content_Types].xml 之间的关联，重新打包后 Word 就会立刻弹“文件已损坏，是否尝试修复”。

同时，直接改 document.xml 的体验非常差，因为 Word 保存 docx 时会插入大量辅助节点。比如你用 Word 打了一段“客户名称：张三”，打开 document.xml 可能看到：

xml复制<w:p>
    <w:r>
        <w:t>客户名称：</w:t>
    </w:r>
    <w:proofErr w:type="spellStart"/>
    <w:r>
        <w:t>张</w:t>
    </w:r>
    <w:r>
        <w:t>三</w:t>
    </w:r>
    <w:proofErr w:type="spellEnd"/>
</w:p>

一个字被拆成两段 run，中间夹着拼写检查标记。你要把“张三”整体替换成 ${customerName}，靠普通查找替换根本做不到，因为你得先想清楚哪些碎片能拼成一句话、中间的 proofErr 要不要删。这也是为什么很多人在 docx 直接改模板时，改出来的变量要么断成两截，要么渲染后句子莫名其妙多了空格。

而 Word 2003 XML 是另外一种存在。它把所有内容摊在一个扁平的单文件 XML 里，样式和正文都在同一个文件内，你不需要解压、不需要知道压缩包内部依赖。虽然它也逃不掉 Word 会拆 run 的老毛病，但至少你用文本编辑器打开它，看到的是一整段可读的 XML 流，搜内容、找节点、做替换都方便得多。

1.3 “另存为一个 XML”不是目的，真正的目的是让 FTL 能输出 Word 源码

顺着上面两条继续推，你会发现一个重要结论：Word 转 FTL 整个过程，本质上是把“用 Word 看到的排版界面”翻译成“一段带动态占位符的 WordprocessingML XML 源码”。

Word 2003 XML 的源码长什么样？一段包含“您好”两字的段落，保存后大概是：

xml复制<w:document xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml">
    <w:body>
        <w:p>
            <w:pPr>...</w:pPr>
            <w:r>
                <w:rPr>...</w:rPr>
                <w:t>您好</w:t>
            </w:r>
        </w:p>
    </w:body>
</w:document>

这段 XML 看起来像是给程序员看的天书，但它确实是 Word 自己能直接打开的文件格式。所以只要你用 FTL 把这段 XML 中的“您好”换成“您好，${name}”，FreeMarker 渲染后输出的依然是一段合法的 WordprocessingML，Word 自然能打开。

想通这一层后，再回头看网上教程，你会发现它们让你“另存为 Word 2003 XML、改后缀 .ftl”的真正价值，是在帮你找一个既能在 Word 里可视化编辑、又能让 FreeMarker 直接操作的文本化中间格式。Word 2003 XML 只是恰好在十几年前被老开发者选中的那一个。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 为什么搜“Word 转 FTL”翻十篇有九篇都在讲 Word 2003 XML？

既然 Word 2003 XML 是一个“能用但偏老”的方案，为什么现在搜出来还是满屏都是它？这里把原因拆开讲，因为它决定了你到底要不要照着做。

2.1 这个答案带有明显的年代痕迹，只是网上资料像滚雪球一样互相引用

我在查资料的时候有一个很直观的感受：凡是讲“Word 转 FTL 用 2003 XML”的文章，博客发布时间集中在 2012 年到 2018 年，而且里面的代码风格非常相似——统一的 StringWriter、统一的 FreeMarker Configuration、统一的把生成结果直接写成 .doc 文件。这说明大部分内容其实是从同一个“祖师爷”级帖子里复制扩展来的，后辈照着跑通了，又写成新的博客，内容越传越像，最后变成了中文技术圈的“标准答案”。

往前倒几年，2008 年前后正是 Java Web 项目大量泛滥的时期。那时候做“导出 Word”的功能，大家的常用技术栈是 Struts/Spring + FreeMarker。而 Apache POI 当时对 docx 的支持还没有现在这么完整，操作复杂表格容易丢样式。有人发现 Word 2003 XML 是纯文本，后端可以直接用 FreeMarker 生成模板，渲染后 Word 能打开，于是这套方案快速流行，成了 Java 导出 Word 的经典操作。

我绝不否认这套方案在当时解决了真实问题。但它的流行本身是一种“路径依赖”，并不代表它是目前技术条件下最好的选择。今天如果你去搜 Apache POI、poi-tl、docx4j 的文档，官方社区显然早已把重心放到了基于 docx 原生结构的新方案上。

2.2 从格式特点看，它确实有三个无法忽视的“方便”

抛开历史原因，Word 2003 XML 能在文本级模板领域活这么多年，是有硬道理的：

它不需要解压。docx 是一个 zip 包，想改里面的 document.xml 必须先解压、再修改、再压缩，只要错过压缩参数或漏文件，Word 就打不开；Word 2003 XML 是一个普通的 .xml 文件，双击用编辑器打开就能改，不存在打包依赖。
它能把样式一起带出来。这非常关键。另存为 Word 2003 XML 时，Word 会把正文涉及的样式定义汇总进同一个文件的首部，这意味着模板脱离 docx 压缩包独立存在时，字体颜色、段落缩进、表格边框信息不会全部丢光。
它能被 Word 直接反向打开。模板渲染出错时，你可以把生成的 XML 拿回 Word 双击打开，然后顺着 Word 的报错提示核对是哪些标签没配对，排错路径非常短。

对比一下：你如果直接对 docx 的 document.xml 做模板，渲染结果通常不能直接双击打开（因为 document.xml 只是 docx 的一部分，不是完整文档）。而 Word 2003 XML 是完整文档，渲染结果可以直接验证。这一点对“反复试错”的场景特别友好。

2.3 但你得清楚它的三个硬伤，别把“能用”当“好用”

不过，如果你现在打开 Word 2021 或 Office 365，新建一个包含多级标题、SmartArt、图片、复杂公式的文档，再试试另存为 Word 2003 XML，多半会弹出兼容性检查器提示“某些功能将被降级”。Word 2003 XML 的硬伤主要有三个：

对图片和媒体处理非常不友好。虽然 Word 2003 XML 也可以内嵌图片数据，但每张图片都变成一长串 Base64 文本，放在模板里可读性极差；如果用部门 LOGO、二维码等动态图片，后端需要先拼 XML 字符串再替换 Base64，整个流程十分笨重。
模板人工编写 Bug 率高。Word 保存出来的一段普通正文，在 XML 层面有大量 w:pPr、w:rPr、w:bookmarkStart 等节点，你要在正确位置插入 <#list> 或 <#if>，而一旦插错层级，轻则样式丢失，重则 Word 打不开。
对 Word 新式特性支持有限。内容控件、块模板、富格式公式、现代分节符这些功能在 2003 XML 里都不存在或者被降级，如果你需要生成高度复杂的动态 Word，这条路往往走不远。

所以我的结论是：网上 90% 教程都让转 Word 2003 XML，是因为“免费、直接、资料多”，而不是因为它“最正确”。要不要抄这条作业，取决于你的 Word 模板复杂程度。

3. 完整实操：把 Word 抄成 .ftl 并用 FreeMarker 写成真 Word

讲场景是为了辨路，接下来把最流行的老方案完整跑一遍。下面的步骤以 Java + FreeMarker 为例，Word 版本不限（2007 到 365 都行），目标是把一个“告警单通知”模板变成一个可动态渲染的 FTL。

3.1 先记住一个规则：在 Word 里不要直接输入 ${}

很多新手第一步就栽在这。为了图省事，直接在 Word 文档里打一句话：

code复制尊敬的 ${name}，你的工单 ${orderNo} 已派发。

保存为 Word 2003 XML 后，用文本编辑器打开，会发现这句话在 XML 里被拆得七零八落：

xml复制<w:p>
    <w:r><w:t>尊敬的 ${name}，你的工单 </w:t></w:r>
</w:p>

这还算好的。如果 Word 把这几个字符中的某一个标记成了拼写错误，或者在中间插入了语言证明，你看到的可能是一个 ${ 在一个 <w:t> 里、name} 在另一个 <w:t> 里。FreeMarker 不会去“跨节点合并文本”，它只会无脑把文本流输出，最终渲染结果就变成残缺的 ${na + me}，变量根本识别不了。

我的经验是：在 Word 里编辑模板时，先用全角或特殊占位符代替 FTL 语法，比如写作：

code复制尊敬的 #name#，你的工单 #orderNo# 已派发。

然后再把整个文档另存为 XML，用文本编辑器把 #name#、#orderNo# 全局替换成 ${name}、${orderNo}。这么做的原因是 #xxx# 不包含符号边界，Word 不容易在中间插入辅助节点，即使被拆了，你也能一眼看出断点在哪里并手动修复。

3.2 另存为 Word 2003 XML，然后全局定位替换

在 Word 里完成模板初稿后，执行“文件 → 另存为 → 其他格式”，在保存类型下拉框里选择“Word 2003 XML 文档”。

保存后得到的 .xml 文件通常非常大，因为里面塞满了命名空间、样式定义、文档设置。刚开始打开它你会觉得像看天书，但别慌，你只关心 w:t 标签里的文字。可以用 VSCode 或 Notepad++ 打开这个 XML，按 Ctrl + F 搜索你在 Word 里写的占位符。

假设原本 Word 段落是：

xml复制<w:p>
    <w:r>
        <w:t>尊敬的 #name#</w:t>
    </w:r>
</w:p>

替换成：

xml复制<w:p>
    <w:r>
        <w:t>尊敬的 ${name}</w:t>
    </w:r>
</w:p>

注意这里有一个极重要的细节：替换后的 ${name} 一定要整体待在同一个 <w:t> 标签内。如果替换完发现文本跨了两个 <w:t>，比如：

xml复制<w:r>
    <w:t>尊敬的 ${na</w:t>
</w:r>
<w:r>
    <w:t>me}</w:t>
</w:r>

FreeMarker 会直接当作一个单独变量名处理不出来。处理方式是手动把两段 <w:t> 文本合并，放到相邻的同一个 run 下，并删除多余的空 <w:t> 节点。这段啰嗦话几乎每一篇教程都不会写，但实际踩坑率极高。

3.3 把文件后缀改成 .ftl，注意编码一定选 UTF-8

把上面的 XML 在编辑器里保存好后，将文件重命名，比如 notice.xml → notice.ftl。此时这个文件已经是一个可被 FreeMarker 解析的模板，因为它内容是纯文本的 XML。

在这一步我强烈建议你检查两件事：

文件编码必须是 UTF-8，因为 Java 默认字符串编码在跨平台时很容易乱，模板文件统一 UTF-8 能避开后面 90% 的乱码问题。Word 2003 XML 文件本身会带有 <?xml version="1.0" encoding="UTF-8"?> 之类的声明，保存时也保持一致。
不要把 notice.ftl 放到 classpath 之外的目录。开发时建议放在项目 src/main/resources/templates 下，这样用 ClassTemplateLoader 加载最省心。

3.4 Java 侧渲染：用 FreeMarker 把模板“算”成 XML

模板准备好了，接下来是渲染代码。需要先引入 FreeMarker 依赖，以 Maven 为例：

xml复制<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.32</version>
</dependency>

核心渲染逻辑如下：

java复制import freemarker.template.Configuration;
import freemarker.template.Template;
import java.io.StringWriter;
import java.util.HashMap;
import java.util.Map;

public class WordFtlDemo {

    public String renderNotice() throws Exception {
        Configuration cfg = new Configuration(Configuration.VERSION_2_3_32);
        cfg.setDefaultEncoding("UTF-8");
        cfg.setClassForTemplateLoading(WordFtlDemo.class, "/templates");

        Template template = cfg.getTemplate("notice.ftl");

        Map<String, Object> data = new HashMap<>();
        data.put("name", "王大力");
        data.put("orderNo", "GD20260228001");

        StringWriter out = new StringWriter();
        template.process(data, out);
        return out.toString();
    }
}

模板渲染完成，out.toString() 拿到的是完整的 Word 2003 XML 文本。接下来你想让它变成“用户眼中的 Word 文档”，有两个常用做法：

直接把这段文本写入一个 .xml 文件，用户双击后系统会调用 Word 打开。
把这段文本写入一个 .doc 文件，因为它的内容本质是 XML 格式，Word 同样能识别（只是打开时可能弹一次“文件格式与扩展名不匹配”的提示，选“是”即可）。

我更推荐前者。如果你用 Spring Boot 做接口返回下载，大概是这么写：

java复制@GetMapping("/download/notice")
public void download(HttpServletResponse response) throws IOException {
    String xmlContent = wordFtlDemo.renderNotice();

    response.setContentType("application/xml");
    response.setCharacterEncoding("UTF-8");
    response.setHeader("Content-Disposition", "attachment;filename=notice.xml");
    response.getWriter().write(xmlContent);
}

如果你必须给用户返回 .doc 文件，把 Content-Disposition 里的文件名改成 notice.doc 即可，Word 打开时通常会询问是否打开，点“是”就可以正常显示。

3.5 表格循环：FreeMarker 的 `<#list>` 指令到底该插哪儿

模板内容如果只是替换几个变量，那这件事根本没有复杂到值得写一篇文章。真正容易出错的是动态表格。

举例，你的 Word 文档里有一个两行的表格：第一行是标题，第二行是样例数据。你想把第二行数据行变成循环体，当后端传递 10 条工单明细时自动拆成 10 行。这是典型的需求。

另存为 Word 2003 XML 后，表格结构大概是：

xml复制<w:tbl>
    <w:tr>
        <w:tc><w:p><w:r><w:t>工单号</w:t></w:r></w:p></w:tc>
        <w:tc><w:p><w:r><w:t>状态</w:t></w:r></w:p></w:tc>
    </w:tr>
    <w:tr>
        <w:tc><w:p><w:r><w:t>GD20260228001</w:t></w:r></w:p></w:tc>
        <w:tc><w:p><w:r><w:t>已派发</w:t></w:r></w:p></w:tc>
    </w:tr>
</w:tbl>

这时候，你需要把整个第二行包进 <#list> 指令里，数据行中的文字替换成变量。最终 XML 大致的修改位置如下：

xml复制<w:tbl>
    <w:tr>
        <w:tc><w:p><w:r><w:t>工单号</w:t></w:r></w:p></w:tc>
        <w:tc><w:p><w:r><w:t>状态</w:t></w:r></w:p></w:tc>
    </w:tr>
    <#list detailList as item>
    <w:tr>
        <w:tc><w:p><w:r><w:t>${item.orderNo}</w:t></w:r></w:p></w:tc>
        <w:tc><w:p><w:r><w:t>${item.status}</w:t></w:r></w:p></w:tc>
    </w:tr>
    </#list>
</w:tbl>

写代码侧时，把 detailList 放进数据模型：

java复制List<Map<String, Object>> detailList = new ArrayList<>();
Map<String, Object> line1 = new HashMap<>();
line1.put("orderNo", "GD20260228001");
line1.put("status", "已派发");
detailList.add(line1);

关键点在于：<#list> 的闭合标签 </#list> 必须放在数据行 <w:tr> 之后、表格结束 </w:tbl> 之前。不要尝试把 <#list> 插进某个 <w:p> 或 <w:tr> 里面包半个标签，这样 FreeMarker 渲染后很可能生成不完整的 XML 标签嵌套，导致 Word 认为文档结构损坏。

3.6 条件段落：用 `<#if>` 控制一段文字“出现或不出现”

有时候你需要根据后端数据决定某一段是否显示。比如告警单里有一段“紧急备注”，只有工单级别为紧急时才显示。

在 XML 中需要包住整个 <w:p>：

xml复制<#if level == "URGENT">
<w:p>
    <w:r><w:t>紧急备注：请立即处理</w:t></w:r>
</w:p>
</#if>

这里有一个反直觉的点：你在 Word 里看到的“一段”，在 XML 里可能由多个 <w:p> 组成，所以一定要先搜索定位好这段文字所在的 <w:p> 前后边界，再把它完整包住。如果 <#if> 写在某个 run 内部或段落节点内部，渲染逻辑不会报错，但输出结果往往会多出不可见的书签或段落属性残留。

4. 最容易踩的 5 个坑，以及排查办法

下面这些坑，是我自己把 Word 2003 XML + FTL 这套方案用在真实项目里时，一个一个踩出来的。单个问题看着都不大，但每个都能耗掉你半天时间。

4.1 Word 把占位符拆成了多个 run，导致变量渲染不出来

这是最经典的坑。你不是在 XML 编辑器里写模板，而是先用 Word 排版保存成 XML，再去替换占位符。Word 在编辑过程中会根据输入法切换、拼写检查、修订记录自动把文字切成多个 run。你搜索 #orderNo# 时可能发现它在 XML 里是这样：

xml复制<w:r><w:t>#orderNo</w:t></w:r>
<w:r><w:t>#</w:t></w:r>

替换后变成 <w:t>${orderNo</w:t> 和另一个 <w:t>}</w:t>，FreeMarker 无法解析。

判断方法：把 FTL 模板放到一个纯文本测试用例里跑一次，看渲染结果里有没有残留的 ${ 或 }。稳妥做法：替换前先搜索这个占位符在 XML 里被拆成了几段，如果超过一段，直接手动把这几个 <w:t> 及其 run 合并成一个。合并的规则很简单：把中间所有 <w:r> 子节点删除，只保留一个 <w:r><w:t> 包裹完整占位符。

4.2 XML 标签里混入了 FreeMarker 指令，导致标签嵌套错乱

FreeMarker 语法和 XML 标签长得非常像，都是尖括号。如果你把 <#if> 直接写在 XML 某个标签的属性位置，比如：

xml复制<w:p <#if show>style="display:none"</#if>>

这行模板 FreeMarker 自己能解析，但渲染完生成的 XML 往往是不完整的，Word 打开会提示“文件损坏”。原因很简单：XML 标签必须结构严谨，而 FreeMarker 在文本流中插入的内容很容易把标签劈成两半。

我的铁律：FreeMarker 标签只放在两个 XML 元素之间，绝不插进某个 XML 元素的属性或开闭标签内部。

4.3 特殊字符像 & < > 变成乱码，页面内容直接错乱

Word 自动保存的 XML 中，出现在 <w:t> 里的 & 符号会变成 &，如果你在 FTL 模板里直接写 北京市 & 上海市，没有写成 &，渲染后的 XML 就不合法。Word 打开时会发现这里有一段不属于标签的裸 &，直接视为文档损坏。

排查方法：把渲染出来的 XML 用浏览器打开，如果浏览器报错，十有八九是特殊字符没转义。遇到这种情况，把模板里的 & 替换成 &，把 < 替换成 <，把 > 替换成 >。

4.4 动态图片无处安放，模板里只有一串恐怖的 Base64

如果你要在 FTL 生成的 Word 里插入动态图片，比如每张工单自动带上二维码，Word 2003 XML 这条路会非常难受。因为图片在 2003 XML 里通常以二进制 Base64 文本的形式直接躺在 XML 里，你要么预先在文档里放一张“占位图片”，再在后端把这段 Base64 替换成新图片的 Base64，要么另想办法。

我实操过后的建议是：如果你的模板带有大量图片，就不要选 Word 2003 XML + FTL 方案，改用基于 docx 原生结构的模板引擎。因为 docx 里的图片是独立的 word/media/xxx.png 文件，模板引擎处理起来要比把整段 Base64 塞进 XML 文本可靠得多。

4.5 生成的文件 Word 提示“文件格式与扩展名不匹配”

这个提示大多出在渲染 XML 内容后你非要给别人返回 .doc 后缀的情况。Word 打开文件时会先读文件头，发现内容不是它熟悉的 doc 二进制格式、也不是 docx zip 结构，而是 XML，于是弹出不匹配提醒。

想彻底消掉提示，可以给返回文件加 .xml 后缀，或者干脆把内容用一个 Word 能识别的“包装层”包起来。不过在实际业务中，很多用户会嫌 .xml 后缀“不像 Word 文档”，这种场景我的处理方式是：下载后的文件名用 .doc，并在下载接口的响应头里明确用 application/msword 标记，同时写文档说明让用户打开时选“是”。很多老系统忍了这个提示很多年，今天依然能跑。

为了方便对照，我把上面问题汇总成一个速查表：

现象	可能原因	解决方案
渲染结果存在 `${name}` 字样	FreeMarker 无法识别变量或数据模型中 key 不存在	检查最终文本是否被 Word 拆成多个 w:t
Word 打开提示损坏	XML 标签嵌套错误、特殊字符未转义	用浏览器打开 XML 检查结构错误
模板更换后样式丢失	原样式不在 2003 XML 中或插入位置不对	回退到 Word 重新另存一次
循环行样式与第一行不同	`<#list>` 插错了位置	对比原始行完整 XML
扩展名提示不匹配	内容为 XML，后缀为 doc	改为 xml 后缀或提示用户选“是”

5. 更现代的替代路线：不是所有人都该继续用 2003 XML

聊到这儿，我必须坦白一个态度：现在做新项目，我不太推荐再走 Word 2003 XML + FTL 这条老路。原因前面说了，它维护成本高、图片处理困难、对 Word 新版特性支持差。更主要的是，目前已经有了一批既能可视化编辑模板、又能避开 run 拆分问题的新工具，用起来比手工改 XML 省心得多。

5.1 Apache POI 直接操作 docx：能精确控制但代码量大

如果你需要非常精细地控制每个段落的生成逻辑，Apache POI 是绕不开的选择。它可以直接读取 .docx，操作段落、表格、图片，甚至能直接往现有文档中插入空行、复制模板表格。

简单示意一下：假如你想把 docx 里第一段的文字改掉：

java复制import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;

InputStream in = new FileInputStream("template.docx");
XWPFDocument document = new XWPFDocument(in);

XWPFParagraph paragraph = document.getParagraphs().get(0);
paragraph.getRuns().forEach(run -> run.setText("替换后的内容", 0));

try (FileOutputStream out = new FileOutputStream("result.docx")) {
    document.write(out);
}

POI 的好处是它能识别 docx 的内部结构，你不需要关心 document.xml 到底长什么样，也不容易破坏压缩包内的依赖关系。代价是代码量明显上升，如果你要做一个包含 5 种表格、3 个动态图片、4 种条件段落的文档，POI 代码能写到几百行，后期维护全靠注释撑场面。

5.2 poi-tl：给 Word 做模板的正确姿势

poi-tl 是 Apache POI 生态里的一个模板语言，它在 docx 原生结构的上面封装了一套非常友好的模板语法，也就是你在 Word 里直接写 {{name}}，它会自动帮你处理 run 拆分的问题。

用 poi-tl 做模板时，Word 里写：

code复制尊敬的 {{name}}，你的工单 {{orderNo}} 已派发。

后端代码：

java复制import com.deepoove.poi.XWPFTemplate;

Map<String, Object> data = new HashMap<>();
data.put("name", "王大力");
data.put("orderNo", "GD20260228001");

XWPFTemplate template = XWPFTemplate.compile("notice.docx").render(data);
template.writeToFile("notice_result.docx");

这段代码比我之前展示的 FreeMarker 版本短了不知道多少，而且最大的优势是它能直接输入 .docx 格式的模板。你可以在 Word 里正常排版，把动态文字写成 {{变量}}，甚至表格循环用 {{#detailList}} 这种块语法，后端几行代码就能跑通。它内部会处理好 run 被拆分、图片替换、表格行复制这些脏活。

5.3 XDocReport 和 docx4j 各是什么场景

XDocReport 则是另一个思路，它支持用 FreeMarker / Velocity 语法来处理 docx 文档，可以认为它是“2003 XML 方案”的一种现代化升级，但它的学习成本并不比 poi-tl 低。docx4j 则更像一个偏底层的类库，适合做更多异构转换。一般情况下，新项目在“能可视化维护模板、能稳定输出 docx”这个目标下，poi-tl 是最省事的默认选择，我在具体项目里也基本固定用它。

为了让你直观地对比，我把常用方案列成一张表：

方案	模板可维护性	表格/图片支持	代码量	适合场景
Word 2003 XML + FreeMarker	中低，需要手改 XML	表格麻烦、图片困难	中	维护老项目、纯文本简单模板
docx + Apache POI	低，模板不好预览	全面但代码多	高	复杂定制、完全由代码控制
docx + poi-tl	高，Word 中写占位符即可	表格图片都很方便	低	新项目绝大多数业务模板
docx + docx4j	中	强	高	底层文档处理、定制功能

6. 我的选型建议和个人体会

这个话题写了这么长，最后我想把视角拉回现实工作里，说说我自己的判断。

如果你是刚接手一个祖传项目，代码仓库里已经有一堆 .ftl 模板，全是 Word 2003 XML 结构，那无论如何都应该先学懂这套方案，因为你不可能说服业务方“先重构再改需求”。该看的 XML 结构、该记的 run 陷阱，都要老老实实掌握。这个技术并不算废，老项目里能稳定跑十年的方案，一定有它值得尊重的地方。

但如果你是在新项目里做合同导出、证书生成、工单打印这类功能，我会直接建议用 poi-tl 或同类 docx 模板引擎。原因是维护模板的人大概率不是后端工程师，而是运营或行政同事。他们能在 Word 里熟练地打字、调样式、插图片，但你让他们打开 XML 文件去改 ${} 的位置，