先交代一下背景我之前做过好几个需要程序生成 Word 文档的项目有自动生成业务周报的有批量把数据库记录组装成合同附件的也有临时帮同事写的小工具。坦白讲最开始我在“到底用哪个库”这件事上绕了不少路网上关于 C# 创建 Word 文档的帖子很多但一半让你用 COM 交互操作另一半推 OpenXML还有一些直接引到商业组件上对只想快速把文档做出来的人来说信息反而越看越乱。这篇教程我按自己多次实战下来比较顺手的路线来写先带你用最省事的 Interop 方式跑通第一个 Word 文档再做标题、表格、图片这些高频排版接着讲模板批量替换的做法最后补上无 Office 环境的 OpenXML 备用方案。无论你是刚入门 C# 的新手还是要给项目接文档生成功能的朋友照着步骤都能快速落地。1. 动手前先选型Interop、OpenXML SDK、第三方封装库怎么权衡很多新手上来就想写代码但 C# 创建 Word 文档最麻烦的往往不是代码本身而是方案选错。等写到一半发现当前环境跑不起来或者要部署到服务器上才发现不能装 Office再回头换库就很痛苦。所以我建议第一步不写字先搞定选型。1.1 三套主流方案的原理与区别先看一张对比表再逐项解释。维度Interop 方式OpenXML SDK第三方库Spire.Doc / Aspose.Words实现原理通过 COM 调用本机 Word 进程直接读写 docx 内部的 XML 结构封装底层格式解析暴露高层 API是否需要 Office必须安装 Word不需要不需要跨平台仅 Windows服务端受限支持 Linux / macOS / Windows支持多平台学习成本低API 接近用户操作中高需要理解 XML 层级模型低API 很友好功能覆盖几乎覆盖 Word 所有功能很全但编码繁琐全封装度高性能慢每份文档都启动 Word 进程快无进程开销快授权成本免费但受 COM 使用规则限制免费开源商业授权部分库有免费版先说 Interop。它本质上是进程外 COM 通信你写一行new Word.Application()背后就是 Windows 拉起一个 Word 进程你的指令通过 COM 管道传给这个进程再由它操作文档。优势是 API 和用户在 Word 界面里的操作几乎一一对应“加粗”“居中”“保存成 PDF”都是接近直译级别的写法入门特别快。缺点也肉眼可见必须装 Office、进程管理不当会内存泄漏、服务端并发场景几乎不可用。OpenXML SDK 则是完全另一条路。docx 文件从本质上看就是一个 zip 压缩包里面装着document.xml、styles.xml这些 XML 文件。OpenXML SDK 就是不启动 Word直接对这些 XML 结构进行增删改。它不依赖 Office、跨平台、性能稳定是服务端生成文档的稳妥选择。缺点同样明显编码量大连一个段落都要把Paragraph、Run、Text一层层拼起来改个字体还得手动加RunProperties新手第一次接触确实容易懵。第三方库是封装好的“成品”比如 Spire.Doc 免费版能应对简单文档Aspose.Words 功能更强但要授权费用。它们的 API 通常很友好开发效率高适合复杂格式要求且预算到位的项目。1.2 什么样的项目选什么方案我的建议很直白自己电脑上临时生成文档、做桌面端小工具选 Interop这是今天最快能见到成果的路径。如果是要放到 Web 服务或后台任务里不建议 Interop直接用 OpenXML SDK宁可前期多写点代码后面部署和排障都会省心很多。至于第三方库公司有预算并且文档格式要求特别复杂再考虑不要把它当成默认选项。心里有了这个判断接下来的实战才不会跑偏。2. 用 Interop 快速跑通第一个 Word 文档这一节是全文的“最小可用版本”。环境是 Windows 安装了 Office开发工具用 Visual Studio 2022 或任意支持 C# 的编辑器。2.1 环境准备与引用配置新建一个控制台应用。目标框架方面.NET Framework 4.7.2兼容性最好选.NET 6/8也能跑但有些 PIA 行为会有差异我建议教程阶段直接用 .NET Framework。添加引用有两种方式方式一右键项目 - 添加 - COM 引用在列表里找 “Microsoft Word 16.0 Object Library”。方式二在 NuGet 搜索并安装Microsoft.Office.Interop.Word包这个更推荐因为 MSBuild 在纯命令行环境也能找到引用而且会主动带上 PIA 依赖。安装完成后在代码文件顶部加一行别名引用using Word Microsoft.Office.Interop.Word;这样写的好处是代码里看到Word.Application一眼就明白是 Word 的 Application不会和系统里的System.Application混淆后续要混写 ASP.NET 命名空间也不打架。2.2 创建文档、写入内容、保存的完整代码下面是一段能直接跑通的完整程序生成一份带标题和正文的 docx 文件。using System; using System.Runtime.InteropServices; using Word Microsoft.Office.Interop.Word; class Program { static void Main(string[] args) { Word.Application wordApp null; Word.Document doc null; try { // 创建 Word 实例但不显示界面 wordApp new Word.Application { Visible false }; // 新建空白文档 doc wordApp.Documents.Add(); // 在文档末尾添加段落并写入文字 Word.Paragraph titlePara doc.Content.Paragraphs.Add(); titlePara.Range.Text 第一份C#生成的Word文档; titlePara.Format.Alignment Word.WdParagraphAlignment.wdAlignParagraphCenter; // 设置标题字号和加粗 titlePara.Range.Font.Size 18; titlePara.Range.Font.Bold 1; // 在文末追加一段正文 doc.Content.InsertAfter(这是正文内容由 Interop 方式写入。); string savePath D:\Temp\HelloFromCSharp.docx; doc.SaveAs2(savePath); Console.WriteLine(保存成功: savePath); } catch (Exception ex) { Console.WriteLine(出现异常: ex.Message); } finally { // 关闭文档并退出 Word释放 COM 对象 if (doc ! null) { doc.Close(Word.WdSaveOptions.wdDoNotSaveChanges); Marshal.ReleaseComObject(doc); } if (wordApp ! null) { wordApp.Quit(); Marshal.ReleaseComObject(wordApp); } } } }这段代码有几个关键点需要理解new Word.Application { Visible false }启动 Word 进程但不显示界面生成文档时屏幕不会闪动。Documents.Add()基于 Normal 模板新建空白文档等价于你打开 Word 后新建了一篇空白文章。doc.Content是主文档范围Paragraphs.Add()在末尾加一个段落给Range.Text赋值就是在那个位置写字。wdAlignParagraphCenter是居中对齐对应的还有左对齐wdAlignParagraphLeft、右对齐wdAlignParagraphRight、两端对齐wdAlignParagraphJustify。SaveAs2是较新版本推荐使用的保存方法。如果业务需要直接转 PDF把保存路径后缀改成.pdf并传入FileFormat: Word.WdSaveFormat.wdFormatPDF即可一行完成 Word 转 PDF这个技巧我后面还会提到。2.3 COM 对象释放——没人提醒但迟早踩的问题如果你只复制上面的 try 部分把 finally 丢掉程序跑完以后打开任务管理器大概率能看到 WinWord.exe 进程残留。一次两次还好循环生成几十份文档后内存占用会非常吓人。为什么会这样因为 Interop 创建的是 COM 对象它有自己的引用计数。Marshal.ReleaseComObject是在手动减引用计数wordApp.Quit()是通知 Word 进程退出。两个动作都做了进程才会干净回收。我自己的经验是不需要对期间创建的所有小对象挨个释放。Paragraph、Range、Table 这些对象都寄生于 DocumentDocument 关闭后它们会随容器一起销毁逐个释放反而容易触发InvalidComObjectException。可靠做法就是 finally 里关闭文档、退出 Application再释放 doc 和 wordApp 这两个根对象就够了。3. 内容排版进阶标题、表格、图片一网打尽实际项目需求很少只是插入一行文字通常还要带标题层级、数据表格和配图。这一节讲高频操作的正确写法。3.1 标题层级和段落样式用 Word 内置样式设置标题是效率最高的做法它会自动维护大纲级别后续要做目录也能被识别。Word.Paragraph p doc.Content.Paragraphs.Add(); p.Range.Text 一、2024年度销售汇总; p.Style Word.WdBuiltinStyle.wdStyleHeading1; p.Format.Alignment Word.WdParagraphAlignment.wdAlignParagraphCenter;WdBuiltinStyle里有很多内置样式wdStyleHeading1是一级标题wdStyleHeading2、wdStyleHeading3依次是二三级标题wdStyleNormal是正文。设置标题之后不用手动调整字体大小样式会自带一套默认排版。如果还想微调可以像第 2 节那样继续覆盖Range.Font属性比如给标题文字加个颜色p.Range.Font.Color Word.WdColor.wdColorRed;。这里要注意一个细节设置Style之后再去改Font.Size时某些版本的 Word 会显示“这些属性基于样式手动修改可能会影响其他文本”。这不是报错只是提示直接忽略即可。3.2 表格创建与“列宽就是不听指挥”的解决方法表格是 Word 生成里最容易出幺蛾子的部分尤其是列宽。很多人设置完Column.Width发现根本不生效单元格内容一多表格自己就撑开了。下面这段是我验证过能稳定控制的写法。Word.Range endRange doc.Content; endRange.Collapse(Word.WdCollapseDirection.wdCollapseEnd); Word.Table tbl doc.Tables.Add(endRange, 3, 3); tbl.Borders.Enable 1; tbl.Range.Font.Size 10; tbl.AllowAutoFit false; for (int i 1; i tbl.Columns.Count; i) { tbl.Columns[i].SetWidth(80f, Word.WdRulerStyle.wdAdjustNone); } tbl.AutoFitBehavior(Word.WdAutoFitBehavior.wdAutoFitFixed); tbl.Cell(1, 1).Range.Text 产品; tbl.Cell(1, 2).Range.Text 销售额; tbl.Cell(1, 3).Range.Text 备注;关键在于两个动作AllowAutoFit false关掉表格自动适应内容然后逐列执行SetWidth(80f, Word.WdRulerStyle.wdAdjustNone)。SetWidth的第二个参数是调整方式wdAdjustNone表示直接修改当前列宽不去影响其他列和表格整体宽度。为什么很多人会遇到“手动拖拽列宽都拖不动”因为 Word 的表格默认启用了自动调整内容一旦超过设定宽度就会把列撑开。先关 AutoFit再把布局固定成wdAutoFitFixed列宽才能老实听话。这个经验在处理其他语言的文档生成库时也通用底层逻辑都是同一套。3.3 插入图片与尺寸控制插入图片用InlineShapes.AddPicture返回值是InlineShape对象可以通过它控制尺寸。Word.InlineShape shape doc.InlineShapes.AddPicture(D:\pic.png); shape.Width 300f; shape.Height 200f;AddPicture默认在光标所在位置插入。如果前面刚执行过Collapse(wdCollapseEnd)图片就会落在文档末尾。图片格式支持 PNG、JPG、GIF、BMPSVG 直接插不了。插完图片之后最好额外加一个空段落否则图片位于文档最末尾时可能会遇到段落标记缺失导致的目录、页脚错乱问题。4. 批量内容生成占位符替换和书签的正确姿势很多业务场景不是要“从零建全文”而是有一个模板需要把里面的变量替换成数据库里的真实值。比如工资单、合同关键条款、批量通知函。这一节的方法可以帮你应付这类需求。4.1 用 Find.Replace 批量替换占位符我在模板里写“尊敬的{姓名}女士/先生”程序一次性把{姓名}替换成“张三”这样一条数据库记录就能出一份独立文档。Word.Find find doc.Content.Find; find.ClearFormatting(); find.Replacement.ClearFormatting(); find.Text {姓名}; find.Replacement.Text 张三; find.Execute(Replace: Word.WdReplace.wdReplaceAll);Find.Execute的参数非常多包括是否区分大小写、是否使用通配符等。日常使用命名参数最稳妥Replace: Word.WdReplace.wdReplaceAll指定全部替换避免漏掉文档里其他位置出现的相同占位符。占位符替换有几个实际坑占位符不能跨多个文本段。如果模板里{姓名}这部分文字被批注、超链接或样式切换拆开了Find可能找不到。做模板时保持占位符文本连续、别夹空格、别做特殊格式。Find.Text不要超过 255 个字符超长文本建议拆成多个短占位符。替换完成后建议看一眼文档页数变化防止替换结果把排版撑乱。如果你只是想简单检查某个占位符是否存在可以先执行一遍不传 Replacement 的Execute看返回的 bool 值即可。4.2 书签替换与方案选型建议如果模板里用的是 Word 书签插入轨迹插入 - 书签替换代码会更简单。doc.Bookmarks[姓名].Range.Text 李四;书签的好处是定位精准不会误伤正文里刚好出现的同名文本。但它有一个反常识的坑替换文本长度较长时书签本身会被新内容覆盖掉一部分书签区域可能损坏。所以在替换前最好先判断书签是否存在替换后如果还要在同一位置继续用书签需要重新插入书签。书签和占位符怎么选我的经验是占位符适合程序统一生成的模板。模板里放几个{}记号代码无脑替换自动化程度高。书签适合业务人员手工维护模板、只改挖空字段的场景。它的定位语义更强但要求业务人员理解“书签”这个概念。功能上两条路都通选哪种完全看你模板是谁维护的。5. 无 Office 环境绕不过去OpenXML SDK 快速玩法我踩过一次大坑一个要部署在 Linux 服务端的生成报告服务用 Interop 写完代码后在本地跑得好好的一部署就彻底歇菜——Linux 上根本没有 COM 概念Word 都装不了。所以这一节讲 OpenXML SDK 的入门玩法给服务端场景留一条备选路线。5.1 创建 docx 的基本代码骨架在 NuGet 安装DocumentFormat.OpenXml然后看下面的代码。using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; string path D:\Temp\OpenXMLDemo.docx; using (WordprocessingDocument wordDoc WordprocessingDocument.Create( path, WordprocessingDocumentType.Document)) { MainDocumentPart mainPart wordDoc.AddMainDocumentPart(); Document document new Document(); Body body new Body(); Paragraph paragraph new Paragraph(); Run run new Run(new Text(用OpenXML创建的第一行)); run.AppendChild(new RunProperties( new Bold(), new FontSize { Val 28 } )); paragraph.Append(run); body.Append(paragraph); document.Append(body); mainPart.Document document; mainPart.Document.Save(); }OpenXML 的模型是层层嵌套的Document在最外层里面是BodyBody包含ParagraphParagraph包含RunRun包含真正的Text。你可以把Run理解成“一段连续相同格式的文字块”想另起一段就 new 一个新的Paragraph。第一个容易踩的坑就是字号单位。FontSize的Val是以“半磅”为单位的数字28表示 14 磅36表示 18 磅。很多人第一次写FontSize { Val 14 }结果是 7 磅的小字怎么看怎么不对。5.2 表格和单元格宽度怎么用 OpenXML 控制OpenXML 控制表格列宽比 Interop 要隐晦一些概念上需要理解TableWidth和TableGrid。看下面的示例。Table table new Table(); TableProperties tableProps new TableProperties(); tableProps.Append(new TableWidth { Width 5000 }); table.Append(tableProps); TableGrid grid new TableGrid(); grid.Append(new GridColumn { Width 2000 }); grid.Append(new GridColumn { Width 2000 }); table.Append(grid); for (int i 0; i 2; i) { TableRow row new TableRow(); for (int j 0; j 2; j) { TableCell cell new TableCell(); cell.Append(new Paragraph(new Run(new Text(单元格)))); row.Append(cell); } table.Append(row); } body.Append(table);列宽的单位是 twips1 英寸等于 1440 twips1 厘米大约等于 567 twips。上面例子两个GridColumn各 2000 twips整体大约 7 厘米。注意TableGrid中的列数必须和实际TableRow里的单元格数量一致否则 Word 打开时会提示表格损坏或自动修复。5.3 OpenXML 适合的场景和坑OpenXML 适合这样几个场景Linux 服务器上跑文档生成服务、高并发批量生成、需要对 XML 结构做精确控制。它的缺点是代码冗长逻辑稍微复杂一点就要面对大量嵌套对象另一个坑是需要对“Word 内部 XML 结构”有一定了解概念模型和 Interop 那种“操作 Word 进程”的直觉完全不同。但好处也很实际不依赖 Office 安装没有 COM 权限问题在容器里特别好部署。我现在的做法是本机工具用 Interop服务端高并发用 OpenXML两者并不冲突。6. 实战踩坑清单从进程残留到列宽失效最后把我在实战里遇到过的常见问题集中列出来附带排查思路。6.1 进程残留问题现象是程序跑完后任务管理器里 WinWord.exe 数量越来越多甚至想删掉刚生成的临时文档时提示文件被占用。大多数情况是 COM 对象没有正确释放异常中断导致 Application 没有执行Quit()。排查顺序按照下面几步走检查代码里所有return、throw的路径确认 finally 块是否真的会执行。确认 finally 里调用顺序是先doc.Close()再wordApp.Quit()最后Marshal.ReleaseComObject。如果程序是多线程并发生成文档要给生成动作加锁或使用信号量确保同一时间只有一个 Word 实例在工作。实在清不掉残留进程可以写一个诊断方法用Process.GetProcessesByName(WINWORD)枚举并强杀。这只适合测试环境生产环境还要从源头解决。我见过一个极端案例循环生成 200 份文档代码没释放 COM 对象跑完后服务器上挂了 40 多个 Word 进程最后整台机器内存告警。所以说释放这件事不是小细节是必须项。6.2 服务端 Interop 权限与安全用 Windows 服务或 IIS 调用 Interop 时经常会遇到两类报错一类是 COM 类工厂访问被拒绝另一类是“远程过程调用失败”或“由于安全设置被禁用”。这其实是 Word 的 DCOM 配置不允许服务账户直接调用。临时解法是在运行窗口输入dcomcnfg打开组件服务找到 “Microsoft Word 97-2003 Documents” 的属性在安全选项卡中给运行服务的账户授权。但这套配置在每台部署机器上都要手动搞一遍自动化部署时特别容易遗漏。而且 Word 本身是交互式程序在后台服务里高频创建、销毁进程很容易出现并发和稳定性问题。微软官方也不建议在服务端用 Office 自动化。所以如果项目是服务端场景强烈建议直接上 OpenXML 或者第三方库别在 Interop 权限问题上死磕。6.3 表格列宽失效和保存文件被占用表格列宽失效的排查顺序确认AllowAutoFit已经设为 false。确认使用了SetWidth并传入wdAdjustNone而不是简单的Column.Width 80f。检查表格里是否有合并单元格。合并过的列结构在 Word 内部是“网格跨度”逻辑某些列宽会由合并单元格控制。如果模板是既有文档里面可能残留原来的网格定义。最省事的方法是把原表格整体删除重新插入而不是在原表上改宽度。保存文件被占用的报错也很常见目标文件正好被用户用 Word 打开程序再写同一个路径就会抛共享冲突。稳妥做法是保存前先尝试删除旧文件删除失败就弹提示让用户关闭文件。另外SaveAs2保存成功后 doc 对象仍然持有旧文件状态如果还要继续修改并二次保存先执行刷新或重新打开避免出现覆盖混乱。就我个人来说现在最顺手的搭配是本机工具用 Interop 做模板替换追求效率服务端生成服务用 OpenXML避免 COM 权限和进程残留。这两条路各自都有学习成本但把它们的边界分开之后绝大多数文档生成需求都能稳稳落地。希望这篇能帮你少走一点我当初选型时走过的弯路。