做合同批量生成那段时间，我被Word页眉页脚折腾得不轻。业务方的需求一句话就能说完——统一页眉，左边放公司Logo右边放合同编号，页脚中间显示“第X页，共Y页”，首页不显示页眉但页脚保留——可真到了代码层面，VBA跑不起来，COM组件装不上，我才意识到办公自动化里最不起眼的“页眉页脚”，其实是最容易翻车的功能。这篇文章完整复盘我用Spire.Doc操作Word页眉页脚的整个过程，包括为什么选这个库、对象模型长什么样、文本图片页码怎么塞进去、首页和奇偶页怎么处理，以及生产环境里那些不试不知道的坑。适合正在做.NET办公自动化的后端工程师，也适合给WinForms/WPF客户端加文档导出功能的人参考。

1. 为什么是Spire.Doc：页眉页脚编程的选型复盘

1.1 页眉页脚需求远比你想象的多

先说个现象。我刚入行那会儿觉得页眉页脚就是“在页面上方打一行字”，简单得很。真正做办公自动化项目后才发现，页眉页脚是所有Word生成需求里出现频率最高的功能之一。合同模板要有公司抬头，标书要在页眉放项目编号，财务对账单要在页眉盖“内部资料”警示，技术报告要在页脚放页码，制度文件要写版本号和使用范围。只要文档需要“见人”，几乎都离不开页眉页脚。

而这些需求一旦批量出现，人工处理就是灾难。一次生成两百份合同，每份要不同的合同编号页眉、连续的页码，靠人一张张改不仅慢，还容易漏改。你只能把页眉页脚变成程序能力。别看页眉页脚表面简单，它的背后牵扯分节、域字段、奇偶页规则、首页规则、与上一节联动等一堆概念。任何一个搞错，生成的文档打开后就是错版。

1.2 主流的几种实现方案对比

我看过很多团队的技术选型，也踩过其中的坑，这里把常见方案放一起对比：

这里我多说两句对比。VBA和COM不是不能用，我早期做客户端工具时就用COM写过Word内容替换，体验还行；但把任务放到后端服务里，这两条路基本走不通。生产环境的服务器，尤其是Linux容器里，根本没有Office，更不会有注册好的COM组件。OpenXML SDK是微软官方的，能力全面，但它的页眉页脚API是围绕WordprocessingML的XML结构展开的，你要自己处理headerReference、sectPr这些XML关系，开发速度慢，出错时排查也难。Spire.Doc的优势恰恰在于API对象模型足够贴近Word的UI逻辑，写起来直观，出了问题也好定位。

1.3 我的选型建议

如果你是做个给用户本机用的小工具，用户电脑上有Office，那用COM或VBA反而更快，毕竟微软原生支持。只要你的程序是在Web后端、定时任务、批量生产流水线里生成Word，或者你的部署环境是Docker、Linux、云函数，那请老老实实用Spire.Doc这类托管库。一个大原则：不要让业务代码依赖运行环境下是否安装了某款商业软件，这是生产事故的温床。

另外提一句，Java技术栈做Word生成常用POI，POI在XWPF模块上也能操作页眉页脚，但API层次偏底层，而且和.NET项目集成成本太高。这里不展开对比POI的细节，只说结论：在.NET里做文档生成，Spire.Doc是更顺手的那个。

2. 页眉页脚的对象模型拆解

2.1 从Document到HeaderFooter的层级关系

用Spire.Doc操作页眉页脚之前，一定要把对象层级搞清楚，不然你会纠结“到底给哪个节设置页眉”。整个文档模型是这样的：

• Document是整个Word文件。
• Document.Sections是文档包含的节集合，一个文档可以有一个或多个节。
• 每个Section都有独立的页面设置和独立的页眉页脚集合。
• 页眉页脚集合里包含不同类型的页眉、页脚对象，比如默认页眉、首页页眉、奇数页页眉、偶数页页眉等。
• 每个页眉页脚对象内部又是由一个或多个Paragraph组成的，段落里放文本、图片、域字段。

你可以把文档想象成一本书：节是章节，每个章节可以有自己的排版风格和顶部底部文字。页眉页脚就是章节顶部的书名和底部的页码。封面节可以不放页眉，正文节放页眉，这就是分节的意义。我见过不少新手把页眉页脚当成文档全局设置，结果一加封面就发现“封面也有页眉”，问题根源就是没理解“页眉页脚挂在节下面，不是文档下面”。

2.2 节下面的页眉页脚类型

Section.HeadersFooters这个集合里常见的有这么几种：

如果你没有开启任何特殊规则，默认情况下Word只会使用Header和Footer。一旦开启“首页不同”或“奇偶页不同”，Word就进入更复杂的分发逻辑。这套逻辑和你理解Word界面里的设置完全一致，所以用Spire.Doc时不需要记一套新概念，你只需要知道每个开关会激活哪个对象。

2.3 页眉页脚里的动态字段原理

页眉页脚里最典型的动态内容就是页码。页码在Word底层并不是普通静态文字，而是一个域（Field）。域相当于一个“占位符”，Word在渲染文档时根据当前页面的上下文动态计算出应该显示的文本。所以你在Word里删除中间一页，后面的页码会自动减一，就是这个机制在工作。

用Spire.Doc插入页码时，直接用AppendField(FieldType.FieldPage)这类方法。这会往docx的XML里写一个域代码，Word打开时看到指令就会动态求值渲染。常见域类型有两个：FieldType.FieldPage表示当前页码，FieldType.FieldNumPages表示总页数。明白这个原理，你就不会犯“把页码硬写成静态文本”的错误——页脚里写死“第1页”，文档一旦增删页码就全错了。还有一个容易误判的点：在Visual Studio里调试时，你只会看到Field对象和它的类型，看不到页码数字本身，这不要慌，直接用Word打开生成的文件验证即可。

3. 核心实操：给一个文档设置统一的页眉和页脚

3.1 准备工作与环境安装

先安装Spire.Doc。在Visual Studio里打开NuGet包管理器，搜索Spire.Doc，安装最新稳定版即可；或者用命令行：

dotnet add package Spire.Doc

项目建议使用 .NET 6 以上的LTS版本，我用 .NET 8 跑过常规项目，没有兼容性问题。如果你还在老项目上用 .NET Framework 4.7.2，Spire.Doc也有对应包版本，安装前注意看包的描述。装好后引入几个命名空间：

using Spire.Doc; using Spire.Doc.Documents; using Spire.Doc.Fields;

Spire.Doc.Documents里放着Section、HeaderFooter、Paragraph这些核心类型，Spire.Doc.Fields里放着Field、DocPicture这类字段和图形类型。日常写页眉页脚基本就靠这几个命名空间。

3.2 设置页眉文本与字体格式

最基础的操作：给整个文档的默认页眉写入公司名称。第一步创建文档对象，接着拿它的节，然后通过HeadersFooters.Header拿到默认页眉：

Document document = new Document(); Section section = document.AddSection(); HeaderFooter header = section.HeadersFooters.Header; if (header.Paragraphs.Count == 0) { header.AddParagraph(); } Paragraph p = header.Paragraphs[0]; TextRange range = p.AppendText("鑫诚科技有限公司 销售合同"); range.CharacterFormat.FontName = "微软雅黑"; range.CharacterFormat.FontSize = 10.5f; range.CharacterFormat.Bold = true; p.Format.Alignment = HorizontalAlignment.Left;

这里有个细节：页眉内容本质是段落的一部分，所以设置字体、字号、加粗、对齐方式，和你设置正文段落时完全一样。为什么我先判断header.Paragraphs.Count再决定要不要AddParagraph？因为页眉对象在被访问时可能自带一个空段落，如果无脑调用AddParagraph，可能多产生一个空段落，反而把排版弄乱。这种“先判断再添加”的习惯，写多了你就知道重要了。

3.3 页眉里插入Logo图片

页眉只放文字是常见场景，但更多时候还要放Logo。比如合同模板的页眉左侧放公司Logo，右侧放文件编号。用Spire.Doc插入图片也很直接：

HeaderFooter header = section.HeadersFooters.Header; if (header.Paragraphs.Count == 0) { header.AddParagraph(); } Paragraph p = header.Paragraphs[0]; Image logo = Image.FromFile("logo.png"); DocPicture picture = p.AppendPicture(logo); picture.Width = 60; picture.Height = 22; TextRange range = p.AppendText(" 销售合同");

这里要特别说明一个单位问题：DocPicture.Width和Height的单位是磅（point），不是像素。Word文档本身是流式排版布局，1磅约等于0.035厘米，一英寸等于72磅。所以如果你希望Logo显示宽度约2厘米，设置60磅就差不多。如果直接拿图片的Bitmap宽高赋值，图片在Word里会被撑大好几倍，这是第一次写的人最容易踩的坑。

另外，页眉一般离页面边缘比较近，图片高度不要超过页眉本身高度，否则Word会在页眉区域自动扩展尺寸，效果可能超出预期。常规Logo高度建议控制在20到40磅之间，具体根据Logo比例调整。

3.4 页脚插入“第X页，共Y页”

接下来是页脚页码。我见过不少初级做法是拼接一个静态文本“第 1 页，共 3 页”，结果文档一改动，页脚就全错了。正确做法是插入页码域。下面这段代码是往页脚里写“第 X 页，共 Y 页”的标准写法：

Footer footer = section.HeadersFooters.Footer; if (footer.Paragraphs.Count == 0) { footer.AddParagraph(); } Paragraph fp = footer.Paragraphs[0]; TextRange prefix = fp.AppendText("第 "); Field pageField = fp.AppendField(FieldType.FieldPage); TextRange separator = fp.AppendText(" 页，共 "); Field pagesField = fp.AppendField(FieldType.FieldNumPages); TextRange suffix = fp.AppendText(" 页");

生成的Word打开后，页脚会实时显示类似“第 1 页，共 12 页”的内容。之所以用AppendField而不是直接写文本，是因为字段是动态的，Word会随文档结构变化自动重算。如果你需要对页脚文本做字体设置，只需要拿TextRange设置CharacterFormat即可，和页眉操作一致。

3.5 给页眉加上分隔横线

页眉下面那条横线是很多公司的强制格式要求。从操作层面看，这条线不是“画一条线”，而是页眉段落的底部边框。在Spire.Doc里通过Paragraph.Format.Borders访问底部边框属性设置：

Border bottomBorder = p.Format.Borders.BottomBorder; bottomBorder.BorderType = BorderStyle.Single; bottomBorder.LineWidth = 0.75f; bottomBorder.Color = Color.Gray;

设置完生成的页眉下方会有一条贯穿页面的横线。需要注意，这条横线的宽度会跟页面正文区宽度一致，效果等同Word界面里的“页眉横线”。如果你的文档是多节的，每个节的页眉段落都需要单独设置一次，这条横线不会自动跨节继承。

4. 进阶实操：首页不同、奇偶页不同与多节页眉

4.1 首页不显示页眉但保留页脚

合同、报告、标书这类文档，通常封面页不显示页眉，或者使用单独版本。这个需求在Word里叫“首页不同”，Spire.Doc里用一行属性开关控制：

section.PageSetup.DifferentFirstPageHeaderFooter = true;

打开这个开关后，页眉页脚集合里的FirstPageHeader和FirstPageFooter对象就开始生效。技巧在于：如果你不给首页页眉写任何内容，首页就没有页眉；而首页页脚单独设置内容，就能做到“首页无页眉但有页脚”：

// 首页页眉留空，不写任何内容 HeaderFooter firstHeader = section.HeadersFooters.FirstPageHeader; // 首页页脚单独设置 Footer firstFooter = section.HeadersFooters.FirstPageFooter; if (firstFooter.Paragraphs.Count == 0) { firstFooter.AddParagraph(); } firstFooter.Paragraphs[0].AppendText("内部文件，请注意保密");

这里有个容易忽略的坑：开启了DifferentFirstPageHeaderFooter之后，Header对象只负责非首页的页面，首页的显示完全由FirstPageHeader控制。如果你只是把内容写在Header里，但没把首页页眉设置为空，往往会出现“首页也有页眉”的现象，原因就在这。

4.2 奇偶页页眉左右交替

书籍、手册、双面打印的文档需要奇偶页页眉不同。通常奇数页页眉靠右显示章节名，偶数页页眉靠左显示书名。开启奇偶页不同同样是PageSetup上的一个开关：

section.PageSetup.OddAndEvenPagesHeaderFooter = true; HeaderFooter oddHeader = section.HeadersFooters.OddHeader; HeaderFooter evenHeader = section.HeadersFooters.EvenHeader; // 奇数页页眉靠右 Paragraph oddP = oddHeader.Paragraphs[0]; oddP.Format.Alignment = HorizontalAlignment.Right; oddP.AppendText("第三章 项目实施"); // 偶数页页眉靠左 Paragraph evenP = evenHeader.Paragraphs[0]; evenP.Format.Alignment = HorizontalAlignment.Left; evenP.AppendText("XX公司内部技术手册");

注意，奇偶页规则会和首页规则叠加。也就是说，如果你同时开启DifferentFirstPageHeaderFooter和OddAndEvenPagesHeaderFooter，首页单独走一套，其余页面再分奇偶。设计文档时不要混，先在Word里用界面确认好排版逻辑，再写代码，能省很多返工时间。

4.3 不同节使用不同页眉并断开继承

复杂文档几乎都会用到分节。比如封面一节、目录一节、正文一节，每节可能有不同的页眉文字。在Word的界面逻辑里，默认情况下后一节的页眉是“链接到上一节”的，也就是说它会继承前一节的页眉。Spire.Doc里，这种继承关系体现在HeaderFooter.IsLinkedToPrevious属性上。

你创建第二个节后，需要先断开它和上一节的继承关系，再写入新内容：

// 添加新节 Section section2 = document.AddSection(); HeaderFooter header2 = section2.HeadersFooters.Header; header2.IsLinkedToPrevious = false; // 设置第二节自己的页眉 if (header2.Paragraphs.Count == 0) { header2.AddParagraph(); } header2.Paragraphs[0].AppendText("附录：部署说明");

一个小提醒：如果你不设置IsLinkedToPrevious = false，直接向第二节的页眉写入内容，运行时可能不报错，但生成的文档里第二节页眉会跟着第一节走，你写的内容也不会生效。这是最容易让人困惑的静默失败。每次操作新节页眉，第一反应都应该是先把IsLinkedToPrevious断了再说。

4.4 综合案例：封面无页眉，正文每页有页眉

把上面知识点串起来，就是一个典型的合同文档生成流程。我直接把项目中简化后的代码放出来，你照着用就能打通整个逻辑：

Document document = new Document(); // 封面节：开启首页不同，不写首页页眉 Section coverSection = document.AddSection(); coverSection.PageSetup.DifferentFirstPageHeaderFooter = true; coverSection.HeadersFooters.FirstPageHeader; // 正文节：开启首页不同，并断开与上一节继承 Section bodySection = document.AddSection(); bodySection.PageSetup.DifferentFirstPageHeaderFooter = true; bodySection.HeadersFooters.Header.IsLinkedToPrevious = false; // 正文页眉：放Logo和合同编号 HeaderFooter bodyHeader = bodySection.HeadersFooters.Header; Paragraph hp = bodyHeader.Paragraphs[0]; DocPicture pic = hp.AppendPicture(Image.FromFile("logo.png")); pic.Width = 50; pic.Height = 18; hp.AppendText(" 合同编号：HT-2025-0001"); // 正文页脚：放页码 Footer bodyFooter = bodySection.HeadersFooters.Footer; bodyFooter.IsLinkedToPrevious = false; Paragraph fp = bodyFooter.Paragraphs[0]; fp.AppendText("第 "); fp.AppendField(FieldType.FieldPage); fp.AppendText(" 页"); // 首页正文页脚留空或单独设置 bodySection.HeadersFooters.FirstPageFooter.IsLinkedToPrevious = false; document.SaveToFile("合同输出.docx", FileFormat.Docx2013);

这套代码成功的关键在于：封面节根本没写任何页眉内容，首页自然空白；正文节断开了链接，具备独立页眉；首页页脚被单独设置为空，所以正文首页也不显示页码。每个环节都有自己对应的对象和开关，逻辑非常清晰，比在Word里手动调整半天要可控得多。

5. 常见问题与排查技巧实录

5.1 设置了页眉但打开文档看不到内容

这个问题出现频率最高，通常有几种原因。

第一，目标页眉类型不对。你开启了“首页不同”或“奇偶页不同”后，如果只写了Header，却忘了首页页眉是独立对象，首页当然没内容。建议先检查PageSetup里那两个开关的状态。

第二，写错了节。多节文档里，你设置的是section[0]的页眉，但实际打开时内容在第二节，看起来就像“没生效”。可以用调试器逐个看document.Sections里每个节的HeadersFooters.Header.Paragraphs。

第三，内容被下一节覆盖。后一节页眉默认继承上一节，如果你设了上一节的页眉，下一节又没断开链接且有自己的内容，结果可能异常混乱。遇到这种情况，把所有IsLinkedToPrevious检查一遍，一节一节确认。

5.2 页码不是从1开始

页码不从1开始的常见原因有三个。一是文档前面有封面、目录这类前置节，页码被分节重排了，也就是第二节的页码继续累加；二是生成文档时把页码写成了静态文本，跟字段无关；三是页码字段格式中包含了“起始页码”设置，比如该节从第3页起算。

如果你希望正文从第1页开始编号，需要单独处理分节页码，让正文节从头计数。这里要提醒的是，页码重排和页眉页脚类型是两个独立维度。很多人在页眉页脚里折腾半天，却忘了去分节属性里查页码起始值。

5.3 页眉横线去不掉

页眉下面多出一条横线，这在用模板改生成时很常见。页眉横线的本质是页眉段落的底部边框，不是独立图形对象，所以你直接在内容里选择删除是删不掉的。正确做法是修改该段落的底部边框类型：

paragraph.Format.Borders.BottomBorder.BorderType = BorderStyle.None;

如果页眉段落里不止一个段落，需要把每个段落都检查一遍。有些模板生成的文档里，页眉横线挂在页眉第一段，有些挂在第二段，只改一段不改另一段，横线依然在。

5.4 免费版限制与部署避坑

Spire.Doc免费版确实能跑页眉页脚，但有不少限制，主要是生成的文档页数、段落数或水印方面的约束。小项目、内部工具用免费版没问题；如果是商用系统、生产环境批量生成，建议评估商业授权，买正规license，避免合规隐患。

生产环境部署还有几个坑值得单说。服务器上没有中文字体时，生成的页眉中文会显示方块，需要在部署环境里安装中文字体或指定可用字体；图片路径写死导致找不到Logo文件；多线程同时生成Word时，注意每个线程用独立的Document对象，不要在静态字段里共享同一份文档。这些都是我在实际运维中真实遇到过的。

5.5 快速排查清单

6. 写在最后：生产环境里我学到的三件事

最后讲一点真实项目里沉淀出来的经验，不算教程，算提醒。

第一件事，页眉页脚的问题八成不在代码，而在对Word模型的理解。你花10分钟搞懂DifferentFirstPageHeaderFooter和IsLinkedToPrevious是什么，比调试一下午“为什么页眉不生效”划算得多。我后来带团队时有个习惯，凡是涉及页眉页脚的开发任务，先让开发在Word界面里手工操作一遍，理解最终效果，再回到代码里对齐。这一步能省掉巨量的返工。

第二件事，模板比代码更能抗变化。页眉页脚本身是强视觉需求，如果公司经常改Logo、改页眉文案，与其在代码里反复改字符串，不如维护一个设计好的Word模板，程序只负责替换关键字段（比如合同编号）和写页码域。这样把“视觉排版”交给模板，把“数据填充”交给代码，各干各的活，后期维护轻松得多。我在很多项目里最后都是这个模式。

第三件事，生成完的Word一定要做二次校验。花几秒钟用Spire.Doc把生成的文件重新打开，遍历每个Section的页眉页脚，检查段落里是否包含预期的关键词和字段。虽然多一步处理时间，但能拦截九成以上的低级事故。别问我是怎么知道的，问就是半夜被业务人员电话叫起来处理过错版合同。

如果你正准备在.NET里做Word文档生成，这篇文章里的代码和思路可以直接抄作业。页眉页脚这个小切口里，装的是整个办公自动化的核心经验：懂文档模型、会选组件、敢在生产里反复验证。