做.NET办公自动化的人，几乎都会在某个阶段被Word的页眉页脚卡住。平时往文档里塞个表格、替换一段文字都算简单，难的是那些每页都要重复出现的内容——页眉上的公司名称、机密级别，页脚里的“第X页 共Y页”，一旦需求变成奇数页一个标题、偶数页另一个标题、首页什么都不放，手工在Word里点来点去，量一大必翻车。这篇文章记录的是我用Spire.Doc在.NET里操作Word页眉页脚的一整套做法，从对象模型到完整代码，再到那些说明书里不会写、实际百分之百会踩的坑。适合正在做文档生成、合同批量输出、公文排版自动化的同学参考。

1. 内容整体设计与思路拆解

1.1 为什么页眉页脚是文档自动化的硬骨头

页眉页脚在排版里很特殊：它不是正文，却跟着每一页跑；它不参与正文的阅读顺序，却往往是文档专业度的门面。合同上没盖公司标识、标书每页没有页码、论文首页重复出现页眉，这些都是客户和领导一眼就能挑出来的硬伤。以前手工处理三五十页的文档还能靠小心弥补，一旦进入批量生成场景，比如从数据库一次性导出一千份合同，每份合同都要求“首页无页眉、偶数页页眉显示客户名称、页脚含总页数”，手工就不是耗时问题，而是根本不可能完成的任务。

所以做办公自动化，页眉页脚恰恰是最能体现价值的地方：代码写得好，几千页文档格式完全一致；写得粗糙，几个小细节就能让整套文档被判定不合规。我的判断是，判断一套文档自动化的成熟度，就看它把页眉页脚这类“边角料”处理得干净不干净。这篇文章不谈生成Word的全局方案，只揪住页眉页脚这个具体环节深入讲，从设计思路到代码实现，全部基于我实实在在跑过的项目写法。

1.2 工具选型：为什么是Spire.Doc

.NET生态里做Word，方案其实不少，我把主流的几个列出来对比一下。

Open XML SDK是微软官方底层库，理论上什么都能做，但操作页眉页脚要直接面对OOXML里的header引用、footer引用这些概念，一个简单的“所有页面显示公司名”也要几十行XML级别的操作。NPOI偏Excel那一套，Word支持基本别指望。DocX这类轻量库日常文本替换够用，但遇到首页不同、奇偶页不同、页码域这些需求时，经常要自己去抠底层，效率并不高。

Spire.Doc的优势是API设计贴近Word界面操作：要设置页眉页脚，就直接拿Section下面的HeadersFooters对象来操作，添加段落、插入图片、插入域代码都是直观的方法调用，学习成本低，出活快。免费版对段落数量、文档容量有上限，用于中小型业务处理足够，大型商业项目要关注授权策略。.NET版本上它能同时兼容.NET Framework 4.x和.NET Core／.NET 5+，我用的是.NET 6，整体没有兼容问题。下面所有代码，都基于NuGet上最新的Spire.Doc包来写。

2. 核心细节解析与前置准备

2.1 Spire.Doc文档结构：页眉页脚挂在哪里

初次接触Spire.Doc的人，容易把页眉页脚理解成“文档级别的一个属性”，其实Word的数据模型里，页眉页脚是挂在节（Section）下面的。一个Word文档由多个Section组成，每个Section可以有自己的页面尺寸、页边距、纸张方向、分栏，也可以有自己的页眉页脚集合。这个设计必须先理解，否则后面做多节文档一定会出事。

Spire.Doc对这套结构的映射非常直接。Document下面有Sections集合，每个Section里有HeadersFooters属性；HeadersFooters里面再按类型拆成默认页眉、默认页脚、首页页眉、首页页脚、奇数页眉、偶数页眉等等。一个典型的页眉对象拿到手之后，它就是一段内容容器，往里面AddParagraph、AppendText、AppendPicture，和操作正文段落没有本质区别。整体关系可以用下面这个结构来看：

Document └── Sections └── Section ├── PageSetup ├── HeadersFooters │ ├── DefaultHeader / DefaultFooter │ ├── FirstPageHeader / FirstPageFooter │ ├── OddHeader / OddFooter │ └── EvenHeader / EvenFooter └── Body（正文段落等）

理解了这条链路：Document → Section → HeadersFooters → Paragraph → TextRange/Picture，后面的代码就能顺着写下来。很多初学者直接找document.Header这种入口，找不到就懵了，其实就是层级没摸清。

2.2 页眉页脚的类型：三种模式必须先想清楚

Word里的页眉页脚不是只有“默认”一种，做自动化的第一件事是明确需求属于哪种模式。默认模式所有页面共用一套页眉页脚，适合合同、内部报告这类简单场景；首页不同模式主要在论文、标书里出现，封面页不显示页眉，从第二页才开始；奇偶页不同模式是为了双面打印装订，奇数页显示章节标题，偶数页显示书名或公司名。三种模式不是互斥的，首页不同和奇偶页不同可以同时启用，这时候文档里的页眉页脚就有默认、首页、奇数、偶数四种类型。

在Spire.Doc里，控制两种模式的开关在Section.PageSetup上：DifferentFirstPageHeaderFooter控制首页是否独立，OddAndEvenPagesHeaderFooter控制奇偶是否独立。只有把开关打开，HeadersFooters里的FirstPageHeader、OddHeader、EvenHeader这些对象才是真正被渲染的那一个；开关没开，你写了也不会生效。这里特别提醒：很多人在这两个属性上翻车，以为创建了FirstPageHeader对象就一定能让首页页眉不同，实际必须先把对应开关设为true，否则Spire.Doc会忽略首页的独立内容。

3. 实操过程与核心环节实现

3.1 环境准备：NuGet安装与最小工程

首先创建一个控制台项目或类库项目，我习惯先建一个最小Demo验证组件行为，确认版本和API没有意外，再往业务代码里迁移。在包管理控制台执行：

Install-Package Spire.Doc

或者用.NET CLI：

dotnet add package Spire.Doc

引入需要的命名空间：

using Spire.Doc; using Spire.Doc.Documents; using Spire.Doc.Fields; using System.Drawing;

最小工程可以先创建一个空文档并保存，确认环境没问题：

Document document = new Document(); Section section = document.AddSection(); document.SaveToFile("output.docx", FileFormat.Docx2013); document.Close();

跑通之后，再往页眉页脚里加内容。FileFormat.Docx2013如果当前版本没有，可以直接用FileFormat.Docx，这是版本差异的常见提示。我的建议是每个小功能先单独验证一次，不要一下子写一大堆再调试，Spire.Doc的页眉页脚API一旦层级写错，排查起来比写起来痛苦得多。

3.2 文本页眉与页脚：第一个能用的Demo

现在给所有页面加一个公司名称页眉，页脚加版权说明。代码很直接：

Section section = document.AddSection(); // 默认页眉 HeaderFooter header = section.HeadersFooters.DefaultHeader; Paragraph headerParagraph = header.AddParagraph(); headerParagraph.AppendText("XX科技有限公司 内部资料"); headerParagraph.Format.HorizontalAlignment = HorizontalAlignment.Center; headerParagraph.Format.FontSize = 9f; headerParagraph.Format.FontName = "宋体"; // 默认页脚 HeaderFooter footer = section.HeadersFooters.DefaultFooter; Paragraph footerParagraph = footer.AddParagraph(); footerParagraph.AppendText("Copyright © 2025 XX科技 版权所有"); footerParagraph.Format.HorizontalAlignment = HorizontalAlignment.Center; footerParagraph.Format.FontSize = 9f;

跑完之后生成的文档，每一页顶端和底部都会出现对应文字。这里有个操作习惯：页眉页脚里的段落同样拥有Format属性，对齐方式、字号、字体都必须显式设置，因为页眉页脚的默认格式和正文不一定一致，如果不设置，最后出来的效果经常是偏的。另外，如果只想让部分文字使用特殊样式，可以拆成多个AppendText，每个返回的TextRange单独设置CharacterFormat，比如把“版权所有”四个字加粗，就再获取对应TextRange改字体。

3.3 页码域：第X页共Y页的正确写法

页脚里最常用的页码，很多人会写死“第1页”，但实际上文档没保存、分页没完成之前，页数是不确定的，必须用Word域代码。Word侧的PAGE和NUMPAGES是标准页码域，Spire.Doc插入域的方式不复杂：

Paragraph footerParagraph = footer.AddParagraph(); footerParagraph.AppendText("第 "); footerParagraph.AppendField("PAGE", ""); footerParagraph.AppendText(" 页 / 共 "); footerParagraph.AppendField("NUMPAGES", ""); footerParagraph.AppendText(" 页"); footerParagraph.Format.HorizontalAlignment = HorizontalAlignment.Center;

AppendField的第一个参数传Word域代码名，第二个参数在部分版本里可以传默认显示文本，“PAGE”和“NUMPAGES”就是Word原生域名字。这个写法生成的文件，在Word里打开通常会自动显示为“第 2 页 / 共 10 页”这样的动态值；如果打开后只看到PAGE这样的域代码字样，不用慌，全选后按Ctrl+A再按F9更新域即可，这是Excel里F9那套思路的Word版本。

这里多说一句，页码往往会伴随格式要求，比如“第P页”“- 1 -”，处理思路都一样，无非在PAGE域前后拼接固定文本和符号，按上面的模式组合就行。要是遇到页脚里要“左右两条横线中间夹页码”的排版，那就需要给页脚段落加边框，或者用表格布局，不要用空格硬凑。

3.4 图片Logo页眉：尺寸控制是重点

页眉里放Logo非常常见，尤其是公司对外文件、合同模板。Spire.Doc里追加图片很直接：

using (Image logo = Image.FromFile("logo.png")) { Picture picture = headerParagraph.AppendPicture(logo); picture.Width = 72f; // 单位：磅，72磅约等于1英寸 picture.Height = 36f; // 约0.5英寸 }

注意三点。第一，图片路径在运行环境里要能访问，生产环境建议把Logo放到固定目录或嵌入资源，别用“C:\Users\xxx\Desktop\logo.png”这种个人路径。第二，Picture.Width和Height的单位是磅（Point），1英寸对应72磅，从Web上拿的图片如果以像素为单位，要先换算再设置，否则显示的Logo会大得离谱。第三，图片和文本在同一个段落里是流式排布，如果想实现“左侧Logo右侧文字”，可以先用Tab位调整位置，或者把页眉段落拆成表格来布局，用空格对齐在不同字体下会崩。

我实际项目里经常要把Logo和公司名放在同一行，做法是图片追加之后，再AppendText一段文字，中间用制表符分隔。如果发现图片位置和文字不在一条视觉水平线上，可以给图片设置垂直偏移或者调整段前段后间距，具体以Word打开后的效果为准。

3.5 首页不同与奇偶页不同：完整示例

这个示例最接近论文或书籍排版需求，我单独拎出来。假设需求是：封面没有页眉页脚，从第二页开始，奇数页页眉显示章节名，偶数页页眉显示书名，页脚统一显示页码。实现代码：

// 开启两种模式 section.PageSetup.DifferentFirstPageHeaderFooter = true; section.PageSetup.OddAndEvenPagesHeaderFooter = true; // 首页页眉留空即可，不需要任何内容 HeaderFooter firstHeader = section.HeadersFooters.FirstPageHeader; firstHeader.AddParagraph(); // 首页页脚也可以留空 HeaderFooter firstFooter = section.HeadersFooters.FirstPageFooter; firstFooter.AddParagraph(); // 奇数页页眉 HeaderFooter oddHeader = section.HeadersFooters.OddHeader; Paragraph oddParagraph = oddHeader.AddParagraph(); oddParagraph.AppendText("第3章 页眉页脚自动化"); oddParagraph.Format.HorizontalAlignment = HorizontalAlignment.Right; // 偶数页页眉 HeaderFooter evenHeader = section.HeadersFooters.EvenHeader; Paragraph evenParagraph = evenHeader.AddParagraph(); evenParagraph.AppendText("《.NET办公自动化实战》"); evenParagraph.Format.HorizontalAlignment = HorizontalAlignment.Right; // 页脚页码，开奇偶模式后最好分别设置奇数页脚和偶数页脚 HeaderFooter oddFooter = section.HeadersFooters.OddFooter; Paragraph oddPageFooter = oddFooter.AddParagraph(); oddPageFooter.AppendField("PAGE", ""); oddPageFooter.Format.HorizontalAlignment = HorizontalAlignment.Center; HeaderFooter evenFooter = section.HeadersFooters.EvenFooter; Paragraph evenPageFooter = evenFooter.AddParagraph(); evenPageFooter.AppendField("PAGE", ""); evenPageFooter.Format.HorizontalAlignment = HorizontalAlignment.Center;

这段代码是最容易出问题的部分，坑点我在第4节统一讲。先简单提醒一个：当开启奇偶页不同之后，原先写在DefaultHeader里的内容不会自动复制到奇偶页眉里，必须分别设置。很多人先写了默认页眉，再开奇偶模式，发现一半页面的页眉丢了，就是这个原因。

3.6 去除页眉默认横线

每次生成页眉后，Word默认会在页眉下方给一条横线，这条横线本质上是段落的下边框。有的模板要求干净无横线的页眉，直接删是删不掉的，必须在代码里把段落下边框清掉：

headerParagraph.Format.Borders.Bottom.BorderType = BorderStyle.None; // 如果还有其他边框，也可以逐个清掉： headerParagraph.Format.Borders.Left.BorderType = BorderStyle.None; headerParagraph.Format.Borders.Right.BorderType = BorderStyle.None; headerParagraph.Format.Borders.Top.BorderType = BorderStyle.None;

如果页眉段落不止一个，可以遍历header.Paragraphs，把每个段落的下边框都清一遍。这个操作不能靠Word文档的“样式清除”来做，因为Spire.Doc生成时，段落样式里带着边框。我最初也以为页眉横线是某种默认样式，研究半天才发现是边框属性的问题，方向对了代码就好写。

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

4.1 高频问题与处理速查表

下面这些是我实际项目里被问过、自己也踩过的典型问题，整理成速查表：

排查思路也很重要。出现问题不要盯着代码猜，把生成出来的docx复制一份，用Word打开，进入“编辑页眉”，看当前页对应的页眉类型是Default、FirstPage还是Even/Odd，这一步能筛掉一半问题。因为页眉页脚是按页面类型动态选择的，代码里未必有bug，只是写错了对象。

4.2 多节文档与页眉页脚继承的实战心得

批量生成文档时，经常一个文档里有多个Section。比如一份报告前面是封面、目录，后面是正文章节，不同章节可能要重排页码或换页眉。Spire.Doc里每个Section的HeadersFooters都是独立的对象集，Word传统里的“链接到前一节”并不会自动生效。我实际操作中的做法是写一个统一方法，遍历文档所有Section，给需要的每个Section都显式设置页眉页脚，绝不依赖默认继承。

示例方法：

void ApplyHeaderToAllSections(Document doc, string headerText) { foreach (Section sec in doc.Sections) { HeaderFooter header = sec.HeadersFooters.DefaultHeader; header.Paragraphs.Clear(); Paragraph p = header.AddParagraph(); p.AppendText(headerText); p.Format.HorizontalAlignment = HorizontalAlignment.Center; } }

如果某些Section要用不同的页眉，就在循环里加条件判断。Paragraphs.Clear()会删除现有内容，如果你只是想覆盖文本，也可以先取第一个段落修改文字。我经常犯的错是忘记清空，结果页眉里叠加了旧文本，生成出来全是重复内容。

另外，如果你的业务要求不同Section之间真正“链接到前一条页眉”，在Spire.Doc里的最稳妥方式是只维护第一个Section的页眉，后续Section通过代码模拟Word行为并不轻松，绝大多数情况下每个Section独立设置反而更可控。页码格式“从第3页开始编号”这类需求，本质上也是节设置，需要在PageSetup里设置起始页码，具体属性名不同版本略有差异，用到了看智能提示即可，思路是“找到起始页码相关设置，再指定数字”。

4.3 避免撞上免费版限制与性能问题

Spire.Doc免费版适合学习和中小型文档，但如果你循环生成几百上千个文档，或者单个文档里图片很多，要注意限制。免费版常见的限制包括文档段落层级、容量等，触发后会直接抛异常或者生成内容截断。商业项目要么购买授权，要么评估开源方案。另外，生成大量文档时，建议循环内重用一个Document实例而不是频繁new，尤其在跑批任务里，会明显减少内存开销。

还有一个容易忽略的是字体问题。服务器上如果没装中文字体，生成的文档用Word打开中文可能变成乱码或者替换成默认字体。解决方法是开发机上验证好字体渲染，或者把字体文件一并部署，在代码里显式设置FontName，不要依赖系统默认。

结尾

按我的经验，页眉页脚自动化是办公自动化里最容易被低估、也最容易出成果的一块。手工处理的时候，它是那个“没人想做、做了也看不出多厉害”的杂活；代码写好之后，它是那个“一键生成一千份文件，每份页码页眉都严丝合缝”的亮点。实际操作中我的体会是先花十分钟把需求归类：默认模式、首页不同、奇偶不同还是混合模式，再动手写代码，比上来就调API省一半时间。这次分享的都是我在真实项目里跑过的写法，代码可以直接拿去做最小验证。如果你正在做批量合同、论文排版、标书生成，遇到页眉页脚相关的怪问题，希望这篇记录能让你少翻几个文档、少踩几个坑。