简介：面向需要在服务端或客户端免安装Office环境操作Word文档的.NET开发者，这套C# DocX资料整合了开源库源码与可运行demo，覆盖文档创建、内容编辑、样式调整、图片表格插入、模板替换以及一键转换PDF等日常办公自动化需求。压缩包约4.93MB，内含244个文件，以83个C#源码文件、86个docx示例文档为主，同时提供7个dll运行库、sln/csproj工程文件、编译缓存及说明文档，方便直接编译调试与对照阅读。已有277人学习，包内亲测可用的Xceed.Document.NET.dll和Xceed.Words.NET.dll与完整案例，对正在做文档自动化的开发者有直接参考价值，可省去自行排查环境与依赖的时间。通过源码与demo，可快速掌握动态生成报告、合同以及批量转换PDF的实现思路，理解Word文档元素的对象模型与API调用方式，并能基于现有代码二次开发，提升实际项目中的Word处理效率。

1. DocX 源码包拆解：C# 无 Office 环境编辑 Word 的最短路径

做工具软件的工程师大多撞过这堵墙：客户要求自动生成 Word 报表，服务器上却不允许装 Office。第一反应是 COM 调用 Word，但运维不给装，COM 这条路直接断掉。后来我拿到一份 DocX 源码包，里面带着 Xceed.Document.NET.dll 和 Xceed.Words.NET.dll 两个核心库，外加可直接运行的 demo，才把这块硬骨头啃下来。DocX 是 C# 环境里读写 .docx 的开源类库，核心价值是纯托管代码操作 Word 文档，不需要本机安装 Microsoft Office，也不依赖 COM 组件。环境里装不装 Word，它都能新建段落、插入表格、替换文本、设置样式，生成的文件能被 WPS 和 Office 正常打开。这份资源适合做报表生成、批量文书处理、文档自动化管线的开发者，也适合想绕过 Office 环境限制、把文档生成逻辑写进服务端的工程师。这篇笔记把这套源码和 demo 完整拆一遍：DLL 怎么引、最短代码怎么跑、核心编辑操作落哪些 API、转 PDF 的边界在哪、以及我实际翻车时踩过的坑。

2. DLL 引用与第一个可运行 Demo：从引用方式到输出 Hello.docx

2.1 源码包里先看什么：DLL 与 Demo 的工程结构

解压资源后，别急着把整个文件夹拖进解决方案，先花两分钟看清目录结构。这个包里通常包含四块内容：DocX 库的 C# 源码目录、一个可运行的 demo 工程、两个核心 DLL 文件（Xceed.Document.NET.dll 和 Xceed.Words.NET.dll），以及 demo 输出用的示例 docx 文档。源码目录的价值在于：运行报错时可以直接跳进库内部看逻辑，不需要靠猜；demo 工程的价值在于：它是这个 DLL 版本下最可靠的调用范例，比网上零散片段准得多。

动手前我习惯做三件事，顺序固定，能省掉后面大半的排查时间。第一，右键点击两个 DLL 文件，打开属性看“详细信息”，记录下产品版本和文件版本——这个版本号直接决定你的目标框架能不能兼容，老版本 DLL 跑在 .NET 6 上有时候会出 IOException。第二，打开 demo 工程的 .csproj 文件，看 TargetFramework 写的是哪个版本，这通常就是 DLL 作者验证过的环境，照抄最稳。第三，确认两个 DLL 最终都出现在输出目录里，调试时不带的话运行时直接报找不到程序集，这类问题后面单独说。

这个包的实用之处在于源码齐全，库内部对 OpenXML 文件包的处理逻辑都摆在眼前。调试时按 F11 能进到库实现里看它怎么解压 document.xml、怎么写段落，这种可观测性是纯 NuGet 包给不了的。从一个可正常编译运行的 demo 开始改，远比从零搭环境快。

2.2 引用 DLL 的三种方式和工程配置

把 DLL 接进项目的做法有三种，按我自己的使用频次排序：第一是直接添加引用，在解决方案资源管理器里右键“引用”，点“添加引用”，切到“浏览”标签，选中 Xceed.Words.NET.dll 就行，Xceed.Document.NET.dll 会自动跟着被识别。第二是把两个 DLL 放进项目根目录下的 lib 文件夹，用 csproj 的 HintPath 显示指明位置，适合团队协作时统一路径，避免每个人引用的 DLL 来自不同位置。第三是走 NuGet，包名是 DocX，它能拉取依赖并自动做版本管理，但如果手里的项目已经有这两个 DLL 文件，就完全没必要再从包源拿一份，版本不一致反而会埋雷。

我一般选择第二种，因为源码包里自带的 DLL 和源码是配套的，用 HintPath 锁住这份 DLL，能防止别人误用别的版本。下面的 csproj 片段是实际工程里可以用的写法：

<ItemGroup> <Reference Include="Xceed.Words.NET"> <HintPath>..\lib\Xceed.Words.NET.dll</HintPath> <Private>True</Private> </Reference> <Reference Include="Xceed.Document.NET"> <HintPath>..\lib\Xceed.Document.NET.dll</HintPath> <Private>True</Private> </Reference> </ItemGroup>

说明一下这里几个节点的作用：HintPath 告诉编译器去指定位置寻找 DLL；Private 设为 True 表示运行时把 DLL 复制到输出目录，这样发布后的程序集文件夹里会自动带上这两个文件，不至于在别的机器上触发“找不到程序集”。如果项目用的是 .NET Framework 2.0/4.x 或 .NET Core 3.1，直接引用基本不会出怪问题；如果是 .NET 5 以上，建议先在 demo 工程里把同样的代码跑一遍，确认这套版本的 DLL 在目标框架下不抛异常再迁到业务工程里。

引用的代码写法上也有一点需要注意。文件顶部要把两个命名空间都 using 进来，否则编译器不认识 DocX 类型：

using Xceed.Words.NET; using Xceed.Document.NET;

两个命名空间缺一个都会导致类型解析失败。前者负责文档模型类，后者提供部分基础类型和枚举，具体到代码里基本都用 DocX 作为入口，但 using 不能省。

2.3 跑通最小 Demo：无 Office 生成第一个 docx

环境配好后，第一个目标不是做复杂报表，而是用最短代码生成一个能正常打开的 Hello.docx，验证 DLL 在当前工程里真的可用。下面是控制台程序里最小可用的一版：

using System; using System.Drawing; using Xceed.Words.NET; using Xceed.Document.NET; class Program { static void Main() { string filePath = @"D:\temp\Hello.docx"; using (DocX doc = DocX.Create(filePath)) { Paragraph title = doc.InsertParagraph("Hello DocX") .FontSize(20) .Bold() .Color(Color.Red); title.Alignment = Alignment.center; doc.InsertParagraph("这是一份由 DocX 生成的示例文档，当前系统未安装 Office。"); doc.Save(); } Console.WriteLine("生成完成: " + filePath); } }

这段代码的核心逻辑分三步：DocX.Create 负责在指定路径创建空白文档对象，InsertParagraph 追加一个新段落并返回 Paragraph 实例，链式调用设置字号 20 磅、加粗、红色，Save 把内存中的文档结构落盘。这里一定要用 using 包裹 DocX 实例，因为 DocX 实现了 IDisposable，内部持有文件流，不释放的话文件会被一直占用，第二次运行就会报文件被另一进程使用。FontSize 的单位是磅，20 磅对应 Word 里的一号字附近；Color 来自 System.Drawing，不要漏掉 using System.Drawing。Alignment.center 是段落对齐枚举，DocX 提供的值有 left、center、right 和 both，注意是 .NET 风格的小驼峰命名。

跑完这条命令，到 D:\temp 下找到 Hello.docx，双击用 Word 或 WPS 打开，看到居中的红色标题和一行正文，说明这条链路已经完全打通。到这里，资源和工程之间已经建立起了稳定的连接，接下来做复杂操作就是在这个对象模型上继续加元素，而不是再折腾环境。如果这一步打开文件时报错，先看运行目录下有没有两个 DLL，再看目标框架与 DLL 版本是否匹配，这两项占了此类问题的大半。

3. DocX 核心对象实战：段落、表格、图片与样式的编辑路径

3.1 段落与格式：从 InsertParagraph 到 Append 的层级关系

DocX 的文档模型是分层的：Document 包含多个 Paragraph，Paragraph 内部由 Run 组成。用 Word 的直观概念理解，Run 就是一段连续格式的文本片段。InsertParagraph 创建的是空段落，要真正往里填内容，需要调用段落上的 Append 方法，每次 Append 可以带上独立的格式设置，这样同一个段落里前几个词加粗、后几个词变斜体就能分开控制。

下面这段代码演示了在一个段落里混排不同格式的文字：

using (DocX doc = DocX.Create(@"D:\temp\Report.docx")) { Paragraph p = doc.InsertParagraph(); p.Append("注意：").FontSize(12).Bold().Color(Color.Red); p.Append("本节数据来自测试环境，仅用于功能验证。") .FontSize(10.5f) .Italic() .Color(Color.Black); p.Alignment = Alignment.left; p.LineSpacingAfter = 12f; doc.Save(); }

逻辑上，第一次 Append 写入的是“注意：”这个引导词，格式设置为 12 磅、加粗、红色；第二次 Append 追加的是说明正文，字号 10.5 磅（对应中文排版中的五号字）、斜体、黑色。两个 Append 在同一个 Paragraph 对象上执行，最终体现在 Word 里是同一个段落内两种不同字形的混排效果。LineSpacingAfter 控制段后间距，值越大段落间的空隙越大，单位按磅理解即可，在需要堆叠大量段落时这个参数能把版面拉开，避免文字挤成一团。各 Append 的返回值都是 Paragraph，所以链式调用可以一直写下去，但要注意链条里一旦某个方法返回类型变了，后面就不能继续接段落方法了——比如 Append 返回对象上不再有 InsertParagraph 可调。

3.2 表格操作：插入、合并单元格、设置边框

表格是报表类文档的主力元素。DocX 的 InsertTable 可以直接指定行列数，拿到 Table 对象后，通过 Rows 和 Cells 索引访问单元格，再往 Paragraphs 里写内容。单元格本身自带一个或多个 Paragraph，所以往单元格写文本的路径是 table.Rows[i].Cells[j].Paragraphs[0].Append(...)，这三层索引是新手最容易写错的地方。

实际项目里常见的是制造一个多行多列的表格，并且要对局部单元格做合并，代码如下：

Table table = doc.InsertTable(3, 4); table.Rows[0].Cells[0].Paragraphs[0].Append("项目"); table.Rows[0].Cells[1].Paragraphs[0].Append("计划值"); table.Rows[0].Cells[2].Paragraphs[0].Append("实际值"); table.Rows[0].Cells[3].Paragraphs[0].Append("偏差"); // 纵向合并第一列的前两行 table.Rows[0].Cells[0].MergeCells(table.Rows[1].Cells[0]); table.SetBorder(TableBorderType.Top, 1f, Color.Black); table.SetBorder(TableBorderType.Bottom, 1f, Color.Black); table.AutoFit = TableAutoFitBehavior.AutoFitToWindow; doc.InsertTable(0).Insert(table); doc.Save();

MergeCells 方法的参数是目标单元格，调用后会吃掉两行同一列之间的分隔线，做成 Word 里常见的跨行单元格效果。这里有个容易踩到的点：合并前第一行和第二行各自有独立单元格对象，合并后再通过 Rows[1].Cells[0] 访问时，返回的可能是空对象或已被合并的占位单元，所以合并操作要放在内容写入之前。SetBorder 用于设置边框，第一个参数是边框类型，枚举里有 Top、Bottom、Left、Right、InsideH、InsideV 等，第二个参数是线宽（单位是磅），第三个是颜色。AutoFit 三种取值中 AutoFitToWindow 让表格宽度自动匹配页面可排版宽度，AutoFitToContents 按内容撑开，Fixed 表示固定布局，报表场景下优先用 AutoFitToWindow，不然列宽会忽宽忽窄。

3.3 图片插入与页眉页脚：让文档更像成品

生成文档里经常要放公司 logo 或者截图，DocX 对图片的处理路径和文本不同。AddImage 方法先把图片文件读入文档资源，CreatePicture 再按指定宽高生成可插入的图片对象，最后 Append 到段落里。尺寸参数的单位是像素，传入的是图片在页面上的显示尺寸。

using (DocX doc = DocX.Create(@"D:\temp\WithLogo.docx")) { using (Image image = DocX.AddImage(@"D:\temp\logo.png")) { Picture picture = image.CreatePicture(40, 160); doc.InsertParagraph().Append(picture); } Footer footer = doc.Footers[FooterType.Default]; footer.InsertParagraph("内部资料 请勿外传").Alignment = Alignment.center; doc.Save(); }

逻辑上，AddImage 是静态方法，把外部图片加载进文档的资源列表；CreatePicture 的两个参数分别是高和宽，单位像素，实际应用中要注意保持图片原始宽高比，否则会拉伸变形。Footers 索引器的入参 FooterType.Default 代表默认节页脚，还有 FirstPage 和 EvenPages 可选，分别作用于首页和偶数页。页脚的文本会出现在文档每一页底部，对需要统一落款、行文编号的场景很实用。DocX 同样支持 Headers 对象，写法完全一致，把 Footer 换成 Header 即可。

3.4 查找替换与模板变量填充：报表自动化的核心打法

在实际业务里，文档结构往往是固定的，变化的是其中的数据。DocX 的 ReplaceText 方法可以完成占位符替换，这也是我把这套库接进业务系统的关键原因。约定俗成的做法是模板里写 {{变量名}} 这种带花括号的锚点，生成文档时用真实值替换：

doc.ReplaceText("{{name}}", "张三"); doc.ReplaceText("{{date}}", DateTime.Now.ToString("yyyy-MM-dd")); doc.ReplaceText("{{amount}}", "12,800.50");

ReplaceText 的默认行为是只替换第一处匹配。如果同一个变量在文档里出现多次且都要替换，需要改成带 options 参数的重载，传入 ReplaceTextOptions.All。另外 DocX 提供 FindUniqueByPattern 方法，支持用正则表达式查找文本，比如批量找到所有 {{ 开头、}} 结尾的片段，再遍历处理。用 {{}} 这种带边界的锚点比裸词替换安全得多，避免正文里恰好出现同名词语被误改——这是模板替换里最常见的翻车现场。

除了上面这些，DocX 还支持设置页面边距、添加超链接、插入复选框、编辑页眉页脚中的图片等。核心操作体系基本就是段落、表格、图片、替换这四类，把这一层 API 练熟，绝大多数文档生成需求都能覆盖。

4. 把 DocX 转 PDF：无 Office 与有 Office 两条路及边界

4.1 先说结论：DocX 本身不导出 PDF

DocX 只负责读写 docx 格式，它的模型层操作的是 OOXML 内容，并不包含 PDF 渲染引擎，所以 DocX.Create 出来的文档无论调用什么方法都找不到 ExportAsPdf 之类的原生能力。有些资料里提到老版本的 Dll 里有 SaveAsPdf，那是特定魔改版或者经过扩展的库，标准实现没有这个 API。转 PDF 必须借助外部手段，常见三条路：

这三条路里，服务端首选 LibreOffice，因为它无需图形界面、支持命令行批量转换，也不像 COM 那样容易把 Word 进程卡死在内存里。但如果目标机器明确允许安装 Office，COM 方案的排版保真度更高，使用时要做好资源释放。下一个小节重点讲 LibreOffice 的实际操作。

4.2 无 Office 环境：LibreOffice headless 批量转换

安装 LibreOffice 后，soffice.exe 会出现在安装目录的 program 文件夹下。转换是通过命令行参数完成的，核心是 --headless --convert-to pdf。我在 C# 服务端工程里的调用方式是启动一个独立进程，等它退出后检查输出文件是否生成：

public bool ConvertToPdf(string docxPath, string outDir) { string sofficePath = @"C:\Program Files\LibreOffice\program\soffice.exe"; ProcessStartInfo psi = new ProcessStartInfo { FileName = sofficePath, Arguments = $"--headless --norestore --convert-to pdf --outdir \"{outDir}\" \"{docxPath}\"", UseShellExecute = false, CreateNoWindow = true }; using (Process p = Process.Start(psi)) { p.WaitForExit(30000); if (p.HasExited) { string pdfPath = Path.Combine(outDir, Path.GetFileNameWithoutExtension(docxPath) + ".pdf"); return File.Exists(pdfPath); } p.Kill(); return false; } }

逻辑是拼装 soffice 的完整命令行，通过 Process 启动，等待最多 30 秒，超时则强制结束并返回 false。参数里 --headless 表示无界面运行，--norestore 表示不恢复上次会话，--convert-to pdf 指定输出格式，--outdir 指定输出目录，后接的引号是为了兼容路径中的空格。这个方案可以批量循环执行多次调用，但要注意并发场景下多个 soffice 同时启动可能争抢配置目录，导致转换失败。常见做法是在每次调用时额外带上 -env:UserInstallation，指定一个独立的临时配置目录，类似 file:///D:/temp/lo_profile1 这样，避免配置锁冲突。

这个方案的短板在字体和无边框渲染上。如果服务器没装中文字体，docx 里的宋体、黑体可能会被替换成默认字体，排版行距变样；如果表格边框被设置成无边框，LibreOffice 为保证可读性有时会自动补边框，导致视觉上多出线条。所以转 PDF 的环境建议装有和目标机器一致的中文字体，转换前用固定测试文档做一遍排版对照。

4.3 有 Office 环境：COM 方案与导出参数

如果目标机器装了 Office，且场景是低频转换，COM 是简单直接的选择。C# 里通过互操作程序集调用 Word 应用，代码量不大，但每一步都要注意释放资源：

using Word = Microsoft.Office.Interop.Word; Word.Application word = new Word.Application { Visible = false }; Word.Document doc = null; try { doc = word.Documents.Open(docxPath, ReadOnly: true); doc.ExportAsFixedFormat(pdfPath, Word.WdExportFormat.wdExportFormatPDF); } finally { doc?.Close(false); word.Quit(); System.Runtime.InteropServices.Marshal.ReleaseComObject(doc); System.Runtime.InteropServices.Marshal.ReleaseComObject(word); }

代码思路是启动一个不可见的 Word 实例，以只读方式打开文档，调用 ExportAsFixedFormat 导出 PDF。ExportAsFixedFormat 的第一个参数是输出路径，第二个参数指定导出格式为 PDF，除此之外还可以传第三个参数表示导出范围、第七个参数控制是否输出文档属性标记。finally 块里做清理：关闭文档、退出 Word、释放 COM 对象，这三步缺一不可。常见翻车点是只调 Quit 不释放 COM 对象，导致任务管理器里 WINWORD.EXE 常驻不退出，批量跑几次内存就上去了。

要注意，COM 这条路的排版保真度最高，但前提是系统里安装的确实是 MS Office。如果机器装了 WPS，Documents.Open 可能被 WPS 的 COM 注册项劫持，打开后导出行为变得不可控。这种情况下要么在运行转换的进程里指定 Word 的 ProgID，要么干脆改走 LibreOffice 方案。COM 还有个隐藏问题：Word 首次打开文档时会执行宏或加载项，如果模板带有异常内容会导致打开缓慢或弹窗阻塞，通常建议 ReadOnly 打开加 Visible 为 false 规避大部分弹窗。

5. 避坑 / 常见问题排查：DLL 引用、版本与中文乱码实测记录

5.1 运行时错误：找不到 Xceed.Words.NET.dll 或 Xceed.Document.NET.dll

现象：程序编译通过，但运行到 DocX.Create 附近就抛 FileNotFoundException，异常信息里明确提到 Xceed.Words.NET 或 Xceed.Document.NET。原因：这两个 DLL 没有被复制到程序运行的输出目录。直接添加引用时如果没把“复制本地”设为 True，或者发布时漏掉了这两个文件，运行时程序集加载器在当前目录找不到它们就会抛异常。解决方法是选中解决方案资源管理器里的引用项，打开属性面板，把“复制本地”设为 True；已经发布过的，手动把两个 DLL 拷到 exe 同目录。另外如果项目内同时存在其他版本的同一个 DLL（比如 NuGet 也引入了一份），输出目录里会出现两个同名文件，覆盖顺序混乱也会触发这个错。

5.2 编译错误：类型同时存在于这两个 DLL 中

现象：编译时报 CS0433，提示某个类在 Xceed.Document.NET 和 Xceed.Words.NET 中同时定义，类型不明确。原因：很多 DocX 版本里，两个 DLL 的依赖关系不是均匀的，Xceed.Words.NET 内部引用了 Xceed.Document.NET 中的部分类型，而项目代码同时把两个命名空间没有区分地 using 进来，编译器无法确定你用的是哪个定义。解决方法是不要同时把两个 DLL 都加到引用列表里，只添加 Xceed.Words.NET.dll，因为它已经隐式依赖了另一个；如果两个都得加，那么代码里显式写全限定名，比如 Xceed.Document.NET.Alignment。我实际处理时更倾向于把 Xceed.Document.NET.dll 从引用列表移除，绝大多数场景下只留 Xceed.Words.NET 一个引用就够了。

5.3 中文内容变成乱码或方块

现象：生成的 docx 在 Office 里打开，中文显示为乱码或者方块字形。原因分两层：一是代码里字符串本身编码不对，把 C# 源文件存成了非 UTF-8 格式，中文字符被破坏；二是字体不匹配，DocX 默认使用的字体名在系统里不存在，Word 就用替代字体渲染。解决方法是先确认 C# 源文件保存为 UTF-8 with BOM，再在代码里对包含中文的段落实显式设置中文字体，比如 .Font(new Font("微软雅黑"))，或者在文档创建后通过 Styles 设置默认字体名。我经常遇到的是第二类，尤其是服务器环境没有安装对应字体，替换字体后显示就正常了。

5.4 生成的 docx 打开时提示“文件已损坏，是否修复”

现象：用 DocX 保存出来的文件在 Word 里打开时弹出修复提示，点修复后内容基本完整，但每次打开都提示。原因：文档流没有正确关闭，或者保存时文档对象内有未正确初始化的元素（比如空表格、空图片引用），导致 OOXML 结构不完整。解决方法是三步排查：第一步确认所有插入的图片和表格都调用了对应的创建方法而不是直接 new；第二步检查代码中 DocX 的 using 是不是完整覆盖了 Save 之后的所有逻辑；第三步如果用了替换功能，确认替换后的文本里没有异常字符。我自己遇到过的场景是在合并单元格后没有重新计算表格结构，导致底层 XML 出现无效的网格范围定义。

5.5 转 PDF 后排版与 Word 里不一致

现象：同一份 docx 文件，用 LibreOffice 转出来的 PDF 和 Word 打开看到的效果有明显差异，常见是行距变大、自动换行位置不同、嵌入图片位置偏移。原因：LibreOffice 和 Word 对字体度量、段落间距、表格自动调整算法的理解不完全一致，这是引擎级差异，不是代码能完全消除的。解决方法是转 PDF 的目标环境装好和文档一致的中文字体（宋体、黑体、微软雅黑都要覆盖），另外在 docx 里尽量使用固定表格宽度而不是自动宽度，段前段后间距用磅值固定，不要依赖默认模板的样式继承。多语言混合文本的场景，LibreOffice 对中文的标点压缩处理与 Word 差异明显，能用半角标点就尽量别用全角。

5.6 许可证相关弹窗或提示

现象：某些封装包替换 DLL 后运行出现授权提示弹窗，或者初始化时抛 LicenseException。原因：DocX 库在商业使用上带有授权约束，部分版本会检查许可状态。解决方法是优先使用 Apache License 的开源分支，自带的这份 DLL 如果来自开源发行版则没有该逻辑；如果来自试用版，那集成到产品中要评估授权合规。实际项目里最稳妥的是只把 DocX 用于内部工具和生成逻辑，不把它的能力打包进商业产品的对外交付模块。遇到弹窗不要试图绕过，合法合规的做法是确认库的许可证条款后再使用。

6. 把 DocX 包进你的工具链：模板锚点批量生成文档的一个顺手写法

前几章解决了单文档怎么生成、怎么转 PDF、怎么排错，最后一节把这些能力串成一个可复用的批量生成工具。思路是：先用 Word 做一份带 {{变量}} 锚点的模板文件，用 DocX 打开并批量替换锚点，配合 JSON 数据源循环生成多份文档。这样做的好处是业务人员可以维护模板，工程师只维护数据映射，模板改版不用动代码。

public static void BatchGenerate(string templatePath, List<Dictionary<string, string>> dataList, string outDir) { for (int i = 0; i < dataList.Count; i++) { string outPath = Path.Combine(outDir, $"report_{i + 1}.docx"); using (DocX doc = DocX.Load(templatePath)) { foreach (var kv in dataList[i]) { doc.ReplaceText("{{" + kv.Key + "}}", kv.Value, ReplaceTextOptions.All); } doc.SaveAs(outPath); } } }

这个方法的逻辑很直接：DocX.Load 以模板文件为基底创建文档对象，遍历数据字典逐项替换锚点，所有 {{变量}} 全部替换完毕后另存为新文件。Run 到批处理时，外层传进来一个 List，每项代表一份独立文档的数据，循环内完成生成。SaveAs 和 Create 的区别是前者从已有文档加载，后者从空白创建，两者返回的都是 DocX 对象，后续 API 完全一致。ReplaceTextOptions.All 参数在这里是必须的，因为同一个模板可能要在一个段落里多次出现同一个变量，默认只替换第一处，不传全替换的话数据会漏。

使用这套工具时有几个习惯我从翻车经历里总结出来，已经形成固定流程。第一，模板锚点统一用大写加下划线命名，比如 {{PROJECT_NAME}}、{{REPORT_DATE}}，同时内置一份锚点清单给业务方，防止他们随手敲一个没定义的变量导致替换静默失败。第二，批量生成前先跑一条测试数据，生成的文档打开检查一遍再批量执行，尤其要留意纯文本之外的表格行数、图片位置这些 DocX 代码里写死的东西。第三，输出目录按日期加批次建子目录，生成完把 docx 原文件和 PDF 转换结果归档到一起，方便追溯。

从那以后我每次跑批量生成都会强制走一遍三件套：先确认 DLL 版本和目标框架匹配，再用最小 demo 验证当前环境能出文件，最后拿真实模板只替换一条数据做排版验证。这套动作看起来繁琐，但能拦截掉大部分“批量跑完发现全部要重做”的尴尬。希望这套思路帮你在文档自动化这条路上少踩几个坑。

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