写Word这件事在程序员眼里是件小事在业务部门眼里是件大事。一个合同模板里的错位、一个字段的漏填可能让整份文件返工。今天想聊的是如何在 .NET 环境里真正把 Word 生成这件事做得稳定、可维护——也就是“数据驱动文档”一边是 Word 自带的邮件合并Mail Merge另一边是自定义数据填充。这两条路都能解决“套模板、出文档”的问题但适用边界完全不同。这篇文章会覆盖邮件合并和占位符填充两种实现路线包含可以直接参考的 C# 代码、模板制作建议以及我在实际项目中踩过的坑适合正在做合同批量生成、通知批量导出、报表文档自动化的后端开发者参考。1. 数据驱动文档的本质MailMerge 和自定义填充的边界1.1 先分清两种需求我接触过的大部分项目需求都可以归纳成两种。第一种是“批量信函类”。同一个模板换掉几个关键字段生成几百份合同、录取通知书、缴费单。比如“尊敬的张三您的订单金额为 1000 元”模板结构完全不变变的只是人名、金额、日期这些变量。这类需求最标准的解法就是 Word 的 MailMerge 字段模板里插入MERGEFIELD数据源提供每一行的值Word 负责逐条渲染。第二种是“动态报告类”。比如检测报告、审计报告、项目总结。这类文档不只是字段值在变结构也在变。同一个模板里可能这个月有 5 条检测项下个月有 20 条可能有合格项也有不合格项需要按条件显示不同的段落可能还需要插入图片、图表、附件清单。这时候单纯靠 MailMerge 就非常吃力因为 MailMerge 擅长的是“同名字段批量替换”而不是“根据数据动态增加或删除段落、表格行”。把这两类需求分清直接决定了后续的技术路线。别看很多团队刚开始都觉得自己只需要“简单替换”进了开发才知道业务方口中的“简单”通常包含动态表格、条件段落和图片插入。1.2 为什么“搜索替换”听起来容易做起来很难不少人一开始会想到最朴素的方式把模板 Word 文件当作字符串模板读取全文查到占位符就替换然后输出。听起来天经地义但落到 OpenXML 层面就会撞上一面墙——Word 文档的正文并不是一整块文本而是由大量w:rRun和w:tText节点组成的。同一个段落里“你好{{姓名}} 这几个字Word 会按字体、拼写检查、修订状态、样式变化切成好几个 Run。占位符本身完全可能被拆成两半{{在一个 Run 里姓名在另一个 Run 里}}在第三个 Run 里。如果你只是对Document.InnerText做一次Replace然后把字符串写回去最后你就会发现文档里有的地方替换成功有的地方少了一半有的地方直接报“文档损坏需要修复”。这不是 OpenXML SDK 的问题而是 Word 文档的本质决定的文本内容不是连续字符串而是“若干段带格式属性的文本碎片”。这个问题我会在第 4 章给出真正能落地的处理方式这里先记住一个结论不要试图在整篇文档层面做字符串替换一定要下探到段落级甚至 Run 级去处理。2. 技术路线对比COM互操作、OpenXML SDK与第三方库怎么选2.1 COM互操作最接近 Word但服务器环境要慎重COM 互操作是 .NET 里调用 Word 最传统的方式通过Microsoft.Office.Interop.Word直接操作 Word.Application 对象。它的优点是功能覆盖度极高MailMerge、域更新、目录、分节、页眉页脚、图表、字体格式Word 里有的功能理论上都能通过 COM 做一遍。但它有几个绕不开的坎。第一服务器必须安装 Microsoft Office而且只用 Windows。第二Word 本质是一个 GUI 客户端程序不是为高并发服务器设计的。一个进程打开多个 Word 实例长时间运行内存和句柄释放稍不注意就会出问题。第三微软官方其实也不建议在服务端无人值守地运行 Office 客户端组件因为 COM 容易出现对话框卡住、进程残留、权限问题。我们在生产环境用 COM一般会外加一个“值守回收机制”定期杀掉残留的 WINWORD 进程或者在渲染服务崩溃后自动恢复。所以我的结论是如果你的项目跑在 Windows 服务器上、文档量中等且模板里大量使用域字段、目录、复杂页眉页脚这类 OpenXML 很难模拟的功能COM 仍然是最可靠的路线。如果目标是 Linux 容器、无头环境、高并发就不能把 COM 作为主方案。2.2 OpenXML SDK跨平台、可控性高但要接受“自己做更多事”OpenXML SDK 是微软官方的文档格式 SDK基于 .NET Standard/.NET可以在 Linux、macOS 上运行。它的核心思路是docx 文件本质上是一个 ZIP 包里面是一堆 XML 文件SDK 将这些 XML 包装成强类型对象模型。OpenXML 的优势非常明显不依赖 Word 安装、不弹窗、适合服务端批量处理、并发模型和普通后端服务一致。缺点也很直接它并不能“执行”Word 的 MailMerge 功能。MailMerge 属于 Word 应用程序运行时计算出来的逻辑OpenXML 只是读取和写文档结构并不会帮你在模板的字段代码里取数据算结果。要做类似的批量渲染你需要自己实现“识别占位符、映射数据、替换内容”这条链路。用 OpenXML 生成的文档只要数据结构写对了Word 打开后格式和原生制作基本一致。问题在于付出的开发成本越复杂的模板越要花时间处理w:tbl、w:drawing、w:header这些结构。2.3 第三方库的定位除 OpenXML SDK 之外生态里还有不少库。NPOI 主要面向 Excel对 Word 的支持能力有限表格可以但页眉页脚、图片、复杂样式做起来很痛苦。OpenXmlPowerTools 是对 OpenXML SDK 的增强提供了一些合并、清理文档的工具但更新频率一般。Aspose.Words、Spire.Doc 这类商业库在没有安装 Word 的情况下也能模拟 MailMerge对复杂文档的支持更完善但需要评估授权成本和依赖体积。我的建议是优先把 OpenXML SDK 和 COM 这两条腿站稳。如果遇到 OpenXML 实在搞不定的高级功能再考虑引入商业库作为补充不要一上来就把全部希望押在某个库上。2.4 我的选型心法一句话总结看模板复杂度看部署环境看并发量。如果模板由业务人员频繁维护里面有很多 MailMerge 域、嵌套表格、复杂页眉建议选择“Word 兼容方案”COM 或商业库。如果系统跑在 Linux 容器里模板结构相对可控OpenXML 是不二之选。如果既有大量动态表格又需要域字段计算结果那就在服务端拆开主体用 OpenXML 渲染特定复杂块用商业库或预转换好的模板块来组装。3. 邮件合并实战用C#批量生成合同与通知3.1 在Word里把模板做成“能合”的样子邮件合并的第一步不是写代码而是回到 Word 客户端把模板做好。很多人喜欢在正文里手工输入“{{姓名}}”这种花括号占位符这没有问题但它和 Word 的 MailMerge 字段是两种东西。如果你要用 Word 原生的邮件合并功能模板里应该插入MERGEFIELD域。在 Word 里插入的方法很简单打开模板把光标放到需要替换的位置按Ctrl F9插入域代码输入MERGEFIELD 姓名 \* MERGEFORMAT然后按F9更新域。更直观的方法是使用“邮件”选项卡里的“插入合并域”按钮选择字段名后 Word 会自动插入。字段名必须是稳定标识建议全部用英文或拼音不要用中文字段名否则在 COM 的 DataSource 映射时容易出编码问题。模板里能插入 MergeField 的位置包括正文、表格单元格、页眉页脚。要注意页眉页脚里的域在合并时可能因为节的不同而出现不更新所以尽量把需要批量替换的变量集中在正文区域。3.2 用 COM 执行邮件合并并逐条保存这里给出一个 C# 示例。先引用Microsoft.Office.Interop.Word然后打开模板连接到数据源逐条记录导出。下面的代码适合把 Excel 或 CSV 作为数据源using Word Microsoft.Office.Interop.Word; public void RenderMailMergeFromDataSource(string templatePath, string dataSourcePath, string outputDirectory) { var word new Word.Application { Visible false, DisplayAlerts Word.WdAlertLevel.wdAlertsNone }; Word.Document doc word.Documents.Open(templatePath, ReadOnly: false); try { word.Options.ConfirmConversions false; doc.MailMerge.MainDocumentType Word.WdMailMergeMainDocType.wdFormLetters; doc.MailMerge.OpenDataSource( Name: dataSourcePath, ConfirmConversions: false, ReadOnly: true, LinkToSource: false, AddToRecentFiles: false, Revert: false, Format: Word.WdOpenFormat.wdOpenFormatAuto, Connection: ProviderMicrosoft.ACE.OLEDB.12.0;Data Source dataSourcePath, SQLStatement: SELECT * FROM [Sheet1$], SQLStatement1: ); int recordCount doc.MailMerge.DataSource.RecordCount; for (int i 1; i recordCount; i) { doc.MailMerge.DataSource.FirstRecord i; doc.MailMerge.DataSource.LastRecord i; doc.MailMerge.Execute(Word.WdMailMergeDestination.wdSendToNewDocument); var mergedDoc word.ActiveDocument; string fileName Path.Combine(outputDirectory, $Output_{i}.docx); mergedDoc.SaveAs2(fileName, Word.WdSaveFormat.wdFormatXMLDocument); mergedDoc.Close(false); } doc.Close(false); } finally { word.Quit(); Marshal.ReleaseComObject(word); } }这段代码的注意点OpenDataSource里的 Provider 是 ACE OLEDB服务器需要安装 Access Database Engine。很多服务器因为没有安装这个引擎或者装了 32 位/64 位不匹配导致运行到这一步直接报错。所以在上生产环境之前务必先在干净的服务器上做一次连通性验证。如果你的数据不在 Excel 里而是来自数据库或接口建议不要走OpenDataSource强行接外部数据源而是把数据拉成内存里的 DataTable然后逐条渲染。这是我在生产项目里的常用做法用 OpenXML 或书签替换实现“单条记录渲染”既规避了数据源驱动的兼容性问题又拥有完全可控的字段映射。3.3 不依赖Word的OpenXML替换实现前面说了OpenXML 不能执行 Word 的 MailMerge 计算。但如果你的模板只是普通文本占位符我们完全可以自己写一个稳定的替换机制。核心思路是在每个段落内部先把所有 Run 的文本拼起来在拼接后的完整字符串里做替换再把替换结果写回段落。using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; public static bool ReplaceInParagraph(Paragraph paragraph, Dictionarystring, string map) { var runs paragraph.ElementsRun().ToList(); if (runs.Count 0) return false; var text string.Concat(runs.Select(r r.GetFirstChildText()?.Text ?? )); var newText text; foreach (var kv in map) { newText newText.Replace(kv.Key, kv.Value); } if (newText text) return false; var firstRunProps runs[0].GetFirstChildRunProperties(); foreach (var run in runs) { var t run.GetFirstChildText(); if (t ! null) t.Remove(); if (run.GetFirstChildBreak() null run.GetFirstChildTabChar() null) { run.Remove(); } } var newRun new Run(); if (firstRunProps ! null) { newRun.Append(firstRunProps.CloneNode(true)); } newRun.Append(new Text(newText) { Space SpaceProcessingModeValues.Preserve }); paragraph.Append(newRun); return true; }关键点有两个。第一Space SpaceProcessingModeValues.Preserve必须加上否则 Word 打开时可能把空格压缩掉。第二我把非文本节点像Break、TabChar的 Run 保留下来避免替换一次把段落里的换行符给删掉。这个函数是后续所有文本填充的地基实际项目里我会把模板里的所有段落都遍历一遍再传入上面那个 map。4. 自定义数据填充实战模板、占位符、表格与图片4.1 占位符设计如何和业务人员约定我强烈建议在项目启动阶段就定好一套占位符规范。视觉上最好用双花括号比如{{姓名}}、{{日期}}、{{金额}}因为普通文本里很少出现重复花括号不容易误替换。如果你需要在同一个位置反复填充多段内容比如“检测结论”可能是几段文字那就不能只放占位符还要考虑区域的概念。Word 里适合做区域的元素有两个书签Bookmark和内容控件ContentControl。书签的优势是名字稳定可以在正文里包住一整段内容控件的优势是编程模型更清晰可以设置标题属性用代码按标题查找。我的习惯是简单文本变量用{{变量}}占位符需要动态插入整段、多段或图片的用内容控件或带书签的段落。这样业务人员在 Word 里一看就知道哪里能改、哪里是逻辑区域。4.2 替换段落文本并保留格式上一章给出的ReplaceInParagraph是一个“丢卒保车”的写法整个段落最后可能只保留第一个 Run 的格式属性。对于多数场景比如整行都是同一种字体、字号、颜色的文本这是可接受的。如果你需要特别精细的格式保留比如占位符前面是黑体后面是楷体混排在一个段落里那就不能用段落级合并替换了。更稳妥的做法是逐段逐 Run 扫描找出包含占位符的片段在最小范围内重建文本。简单来说你可以先把段落的所有 Run 按顺序编号拼接成 text 对象数组然后在查找占位符时记录它跨越了哪几个 Run只重建这些 Run 的文本位置其余 Run 原封不动。这样格式不会大面积丢失。4.3 动态表格用模板行克隆生成多行数据动态报告里最高频的操作就是往表格里按数据条数生成行。比如一份检测报告里检测项列表有 5 条还是 20 条需要自动生成对应行数。OpenXML 的处理方式如下先在模板里保留一行“模板行”这行里用占位符表示列例如{{检测项}}、{{标准值}}、{{实测值}}、{{结论}}。渲染时克隆这个行节点替换克隆行里的占位符然后把克隆行插到模板行前面最后把模板行本身删掉。代码思路public static void FillTable(Table table, Dictionarystring, string columnMap, ListDataRow rows) { var templateRow table.ElementsTableRow() .FirstOrDefault(r r.InnerText.Contains({{检测项}})); if (templateRow null) return; foreach (var row in rows) { var newRow (TableRow)templateRow.CloneNode(true); foreach (var paragraph in newRow.DescendantsParagraph()) { ReplaceInParagraph(paragraph, columnMap); } templateRow.InsertBeforeSelf(newRow); } templateRow.Remove(); }有几个细节需要补一下。第一如果表格有标题行希望在多页中重复显示Word 模板里右键表格行选择“属性-行-在各页顶部以标题行形式重复出现”对应的 OpenXML 结构是w:tblHeader在克隆行时也要保留这个属性。第二克隆出来的行如果继承了模板行的行高w:trHeight数据多时可能导致表格拉伸可以在模板行的表格属性里把“允许跨页断行”打开。第三列宽问题如果模板行设置了固定宽度你克隆出来的行会继承同样的宽度这通常是好事但如果你在代码里新建表格就要自己手动设置每个单元格的TableCellWidth否则表格打开后列宽会变得很怪。4.4 图片填充最好的办法是“先占位、再换图”在 OpenXML 中动态插入图片是最容易出问题的地方因为一个完整的Drawing对象包含Inline、Extent、DocProperties、Blip等好几层节点新手很容易拼错结构。我的建议是不要在代码里从零创建 Drawing而是让模板里先放一张占位图片然后在渲染时替换这张图片的内容。具体做法是在 Word 中插入一张 1x1 像素的白色图片或不显眼的占位图片选中图片后在“格式”选项卡里设置“替换文字”把替换文字写成固定标识比如{{图片:签字}}。在 OpenXML 里图片的替换文字对应Drawing里的DocProperties.Title属性。代码可以这样找到目标图片public static void ReplaceImageByTitle(WordprocessingDocument doc, string title, Stream imageStream) { var mainPart doc.MainDocumentPart; var drawings mainPart.Document.Body?.DescendantsDrawing().ToList(); if (drawings null) return; foreach (var drawing in drawings) { var docProp drawing.DescendantsDocumentFormat.OpenXml.Drawing.Wordprocessing.DocProperties() .FirstOrDefault(); if (docProp null || docProp.Title?.Value ! title) continue; var blip drawing.DescendantsDocumentFormat.OpenXml.Drawing.Blip().First(); string relId blip.Embed!.Value!; var imagePart (ImagePart)mainPart.GetPartById(relId); imagePart.FeedData(imageStream); } }这里通过Blip.Embed拿到图片关系 ID然后直接替换对应 ImagePart 的数据流。图片的宽高由模板里的占位图片决定所以即使换了图片也不会撑坏版式。如果业务上需要按实际图片尺寸调整宽高就再修改Extent节点里的Cx和Cy数值单位是 EMU1 英寸 914400 EMU。4.5 页眉页脚和分页符页眉页脚里的占位符最容易漏掉。OpenXML 里正文和页眉在物理上存储于不同的 Parts 中所以只遍历MainDocumentPart.Document.Body是够不到页眉页脚的。必须再遍历HeaderPart和FooterPart里的段落执行相同的替换流程foreach (var headerPart in mainPart.HeaderParts) { foreach (var paragraph in headerPart.RootElement.DescendantsParagraph()) { ReplaceInParagraph(paragraph, map); } }分页符的问题更阴险。如果你在段落里用了w:br typepage强制分页使用我前面那种“先拼文本再删 Run”的方式时如果那个 Run 是空文本只带 Break那么删除 Run 时会把强制分页也删了。所以我在ReplaceInParagraph里特别判断了Break和TabChar。实操中我建议遇到复杂分页需求时把分页符放到独立的段落里避免和数据占位符挤在一个段落。5. 服务化落地封装一个DocumentRenderer并处理并发5.1 渲染服务的基本接口代码写清楚只是一半真正上生产需要一个干净的服务封装。我习惯把渲染能力定义成一个接口这样上层业务不用关心底层是 OpenXML 还是 COMpublic interface IWordRenderer { Taskbyte[] RenderAsync( string templatePath, Dictionarystring, object data, CancellationToken cancellationToken); }调用方只需要传模板路径和数据字典拿到 byte 数组后可以直接返回给前端下载也可以转成文件流。用byte[]比直接在服务端创建临时文件更安全省去了清理临时文件的各种麻烦。WebAPI 里一行代码就能返回return File(bytes, application/vnd.openxmlformats-officedocument.wordprocessingml.document, output.docx);5.2 COM场景下的并发控制If 你选了 COM 路线并发问题必须认真对待。Word COM 组件要求线程是 STA 模式而Task.Run默认跑在 MTA 线程池里直接调用 COM 会出现奇怪的问题轻则操作失败重则线程卡死。正确做法是在专门的 STA 线程里启动 Word 实例public static void RunInSta(Action action) { var thread new Thread(() action()); thread.SetApartmentState(ApartmentState.STA); thread.Start(); thread.Join(); }另外我建议把 Word 实例总数限制为 1。也就是说服务内部用一个信号量或队列把所有渲染任务串行化始终只有一个 WINWORD 进程在跑。高并发场景不要靠多开 Word 去解决那样只会让服务器内存暴涨甚至导致 Word 崩溃。每个渲染任务完成后主动调用Quit和Marshal.ReleaseComObject释放所有 COM 引用。生产环境里最好把这个渲染模块单独拆成一个 Windows 服务或者独立进程。主网站只需要往队列里丢任务渲染进程逐个处理。这样即使 Word 进程偶尔崩溃也不会拖垮整个 Web 服务。5.3 OpenXML场景的内存与文件锁OpenXML 没有 COM 那些线程模型问题但同样要小心模板文件的重复使用。不要在渲染过程中直接打开并修改模板原文件否则并发任务同时写同一个文件会互相覆盖。正确做法是先把模板文件读成字节放到一个 MemoryStream 里再以可编辑方式打开这个内存流。模板原文件始终保持只读这样所有并发任务都能安全共享同一个模板路径。var ms new MemoryStream(File.ReadAllBytes(templatePath)); using (var doc WordprocessingDocument.Open(ms, true)) { // 执行占位符替换、表格填充、图片替换 doc.Save(); } return ms.ToArray();这里还有一个细节WordprocessingDocument.Open在可编辑模式下打开后如果某个地方异常退出内存流里可能残留半成品。我建议在渲染前先复制一份模板字节再在副本上操作异常时直接丢弃副本模板永远不收影响。6. 高频踩坑复盘从字段替换失败到表格列宽异常6.1 占位符被拆开替换后只剩半个词这是 OpenXML 替换最高频的问题。前面讲过Word 会把文本拆成多个 Run。如果你只对某个Text节点做字符串包含判断占位符{{姓名}}被拆成{{和姓名两个节点后就永远替换不成功。解决方式就是第 3 章那个ReplaceInParagraph按段落聚合所有 Run 的文本再统一替换。建议新建一个“模板自检”工具在开发阶段扫描模板里所有段落把包含占位符但未生效的节点报告出来避免上线后手工翻找。6.2 表格列宽无法拖动或越拉越乱很多人在“Word表格列宽无法拖动”这个问题上被困扰。这里有个 OpenXML 层面的解释如果你通过代码生成或修改表格但没有正确设置表格网格w:tblGrid或者设置了w:tblLayout typefixed那么 Word 打开后你会发现所有列宽都不对鼠标拖动列宽时也会被强制弹回。解决的方法是如果模板是 Word 里手工做好的尽量不要用代码重新构建表格结构而是复用模板中的表格行如果必须新建表格注意三个结构w:tblGrid里的w:gridCol数量必须和单元格数量一致每个w:tcPr/w:tcW的宽度要合理表格的布局方式设置为自动或按需。我见过很多项目因为表格结构里的gridCol数量不同导致 word 打开时触发“无法修复的内容”提示。6.3 替换文本后整段字体变成了默认字体原因很直白你把原 Run 都删了只保留第一个 Run 的RunProperties。如果那个 Run 本身没有显式设置字体替换后就会用模板的默认字体。如果遇到这种情况可以不要只取第一个 Run 的属性而是去取段落中占位符所在 Run 的属性或者干脆在替换时统一指定字体。比较稳妥的方案在代码里找出占位符所跨的 Run取这些 Run 中出现频率最高的格式属性作为新 Run 的属性。这种细节在批量生成合同中影响很大因为合同通常包含中英文、数字、金额同一段落里混排很正常。6.4 邮件合并的“^”和换行问题在 Word 界面里^表示“查找的内容”^p表示段落标记这是 Word 查找替换语法里的符号很多同学会把它们误当成普通文本去替换最后发现文档里出现了字面量的^p。如果你需要从代码里插入换行OpenXML 中应该使用Break元素或者用Environment.NewLine但不是所有地方都生效。最稳妥的方式是构造new Paragraph(new Run(new Text(第一行)), new Run(new Break()), new Run(new Text(第二行)))。如果你是在 MailMerge 数据里传入带换行的文本要注意 Word 域结果中的换行也会被当作域属性的一部分保留直接从字符串替换换成带Break的 Run 结构更可靠。6.5 公式和图片的特殊处理很多“公式图片转 Word”的需求本质上都是想把数学公式塞进文档。Word 的公式有两种来源MathType 生成的 OLE 对象以及 Word 原生 OMML 公式。OLE 对象在 OpenXML 中是一个EmbeddedObject替换起来非常复杂。OMML 公式则是一大堆m:oMath节点手工拼接成本很高。我的建议是如果动态生成的公式数量少直接把公式做成图片插入如果数量多且要求可编辑就在模板里预先放置公式或 OLE 对象然后通过程序替换其内容。最理想的情况是业务方把公式归类成有限的固定集合例如“标准偏差”“置信区间”每种公式预先做好模板渲染时只切换数值不切换公式结构。下面整理了一个高频问题速查表方便开发时快速定位问题现象本质原因推荐处理替换后只剩半个字段占位符被拆在多个 Run段落级聚合文本后替换表格列宽被固定无法拖动w:tblGrid或固定布局异常不重建表格用模板行克隆字体变成默认字体删除所有 Run只保留第一个属性取占位符原 Run 属性复用打开文档提示需要修复XML 结构缺失或嵌套错误用 OpenXmlValidator 校验Word 进程残留COM 未正常退出统一进程回收与超时机制页眉页脚未替换未遍历 HeaderPart/FooterPart单独遍历替换图片填充后变空白图片关系 ID 或数据流未保存直接替换 ImagePart.FeedData合并后变量为空数据源连接失败或字段名不匹配先用单条记录调试模板7. 选型建议与实践心得如果你现在要开始一个“.NET 生成 Word”的项目我的建议浓缩成三句话第一优先走 OpenXML 模板占位符路线。这套方案跨平台、稳定、可控模板由业务人员在 Word 客户端制作代码只负责数据映射和结构复制。如果模板中大量使用了域字段、目录、复杂图形再评估 COM 或商业库。第二无论选哪条路模板维护流程都要规范化。最好指定专人维护模板模板里不允许手工增删样式业务人员改完模板后需要跑一遍服务端渲染测试确认没有把占位符误删或把表格行拆掉。我见过太多因为模板被随手改动而突然批量生成的文档格式错乱的生产事故。第三做好幂等和回滚。数据驱动文档的渲染输入是数据和模板但输出结果受模板版本影响很大。我实践中的做法是把模板文件的完整字节存一份备份渲染时记录模板的哈希值每次出问题都能马上回溯是哪一版模板引起的。这个习惯会帮你节省大量排查时间。还有一个小技巧也是我踩过几次坑之后养成的每次改模板不要只改一份而是在模板里同时保留“示例数据”和“渲染数据”两个 Sheet 或两套字典。开发环境用示例数据跑通确认格式无误生产环境再切真实数据。这样格式问题和数据问题可以完全隔离。Word 文档自动化这件事本质上不是“能不能生成”而是“生成得是否稳定、可维护、经得起批量运行”。你只要把模板结构、替换层级、并发控制和异常回收这四个环节想清楚后面就很少会被动加班了。