DocX适合简单静态文档生成但不支持复杂模板；OpenXML SDK可精准操作底层结构但易出错；MailMerge仅限基础域填充；推荐OpenXML+预编译模板片段组合方案。
用 DocX 库直接生成 Word，适合简单报告但不支持复杂模板
如果你只是导出表格、段落、标题这类静态结构，DocX（来自 Novacode.DocX）上手最快。它不依赖 Office 安装，纯 .NET 实现，生成的是真正的 .docx 文件。
常见错误是误以为它能“打开并修改现有模板”——它只能新建或加载已有文档，但对 Content Controls、MailMerge 域、样式继承等支持极弱，填个变量名都得手动找段落再替换文本，容易漏掉隐藏字段或破坏格式。
- 用
DocX.Load("template.docx")加载后，doc.ReplaceText("{{name}}", "张三")只匹配纯文本，遇到加粗/换行/表格内文字就失效 - 没有原生表格数据绑定，循环插入行得靠
table.InsertRow()一行行拼，列宽、边框、合并单元格全得手动算 - .NET 6+ 项目需确认 NuGet 包版本：旧版
DocX不兼容net6.0，要用DocX.Core替代，API 几乎一样但命名空间不同
用 OpenXML SDK 操作原始文档结构，灵活但易出错
当你必须复用带样式、页眉页脚、内容控件或条件章节的 Word 模板时，OpenXML SDK 是唯一可控方案。它让你直接读写 .docx 的底层 XML 结构，相当于在 ZIP 包里改文件。
典型翻车点是没关流或没调 Save()：加载 WordprocessingDocument 后，所有修改都在内存，不显式保存就等于白干；更隐蔽的是，改完 Body 却忘了更新 DocumentSettingsPart 或 NumberingDefinitionsPart，导致编号错乱或样式丢失。
- 替换
Content Control（如rich text或plain text）必须用SdtElement定位，不能只搜文本——因为用户可能在控件里敲了空格或换行 - 插入表格数据前，先用
Table.CloneNode(true)复制模板行，再清空原行内容，避免样式被新行覆盖 - 调试时别直接双击生成的
.docx——Office 会静默修复损坏的 XML。用7-Zip打开看word/document.xml才知道实际写了啥
用 DocX + MailMerge 域做最简模板填充，但仅限基础场景
如果模板里只用 «Name» 这类传统域代码，且不涉及重复区块（比如多行订单）、条件显示（比如“金额>1000 显示红色”），可以走 Office 自带的邮件合并路径，配合 DocX 的 MailMerge 方法。
关键限制在于：Word 必须用 Insert → Quick Parts → Field → MergeField 插入域，不能手打 «» 符号——后者只是普通文本，DocX 根本识别不了。而且所有域必须在主文档区域，页眉页脚里的域默认不参与合并。
- 调用
doc.MailMerge.Fields.Add("Name", "张三")后，必须紧接着doc.MailMerge.Execute()，否则字段不刷新 - 合并后生成的文档，域代码会被清除，变成纯文本。想保留可编辑性？做不到
- 如果模板里有
IF域或REPEAT域，DocX完全不支持解析，会直接跳过
推荐组合：OpenXML SDK + dotnet-template 预编译模板片段
真正稳定的方案，是把高频变动部分（比如客户信息表、产品列表）抽成独立 .xml 或 .json 数据源，用 OpenXML SDK 加载模板后，按预定义规则注入。比硬编码逻辑更易维护，也比全靠字符串替换可靠。
最容易被忽略的细节是字体和编码：中文模板若用 SimSun 字体但生成环境没装该字体，Word 会 fallback 到其他字体，导致排版偏移；更麻烦的是，如果模板里用了 UTF-8 BOM 的外部 JSON，OpenXML 读取时可能把 BOM 当作非法字符报错。
- 模板中所有动态位置（如表格起始行、备注段落）用唯一
Bookmark标记，代码里用document.Bookmarks["OrderList"]定位，比找文本或样式稳定得多 - 生成前检查
document.MainDocumentPart.Document.Body是否为空——有些模板导出时会意外清空 Body，结果输出空白页 - 测试时务必用不同版本 Word 打开（2016 / 365 / Online），
OpenXML写的文档在 Web 版常出现页眉错位，本地版正常
Word 模板的“所见即所得”全是假象，背后是 ZIP + XML + OPC 容器的混合体。越想省事用字符串替换，后期越要花十倍时间修格式错乱和域失效。真要长期维护，不如花半天把关键区块抽象成 Bookmark + 数据契约。
