Spire.Doc 设置奇偶页页眉页脚：从原理到批量生成的完整指南

前段时间接了个合同批量生成的需求，其中一个排版要求是：奇数页页眉放公司全称和客服电话，偶数页页眉放项目编号，页码一律“放在外侧”，也就是奇数页右下、偶数页左下。Word 里就是页面设置里勾一个“奇偶页不同”的事，两分钟能搞定；但如果要在 .NET 文档自动化里用代码批量产出一百份 docx，事情就没那么轻松了——Spire.Doc 这类库虽然封装得不错，奇偶页页眉/页脚相关的 API 依然有一堆容易让人踩坑的细节。这篇就讲讲我在 .NET 里用 Spire.Doc 设置奇偶页页眉/页脚的最佳实践，包括底层原理、完整代码、批量场景的工程化写法，以及生成之后怎么验证才算靠谱。适合正在做合同、标书、报告、书籍排版类自动化功能的开发同学参考。

1. 为什么偏偏是“奇偶页页眉/页脚”最容易在自动化里翻车

1.1 这类需求大多来自哪里

我接触到的奇偶页页眉/页脚需求，基本集中在以下几类文档里：

• 合同和标书：奇数页页眉放公司抬头、销售电话，偶数页页眉放项目编号或文件密级，页码统一在最外侧，方便装订后翻阅。
• 书籍、期刊、论文排版：双面打印时，奇数页页眉放章节名，偶数页页眉放书名；页码位置一左一右，形成镜像效果。
• 长型报告、白皮书：封面、目录、正文、附录往往分属不同节，封面不要页眉，正文从某一节才开始出现奇偶页不同的页眉/页脚。

这些场景有一个共同点：一旦进入“批量生成”阶段，就是要同时输出几十上百份文档，人工在 Word 里一份份勾选设置根本不现实。所以只能靠代码，把每个节的页面设置、页眉页脚对象、内容填充全部做对。

问题在于，手动在 Word 里操作只需要记住“页面设置 -> 版式 -> 奇偶页不同”这一个入口，而用代码操作时，你面对的是 Word 对象模型里一系列彼此关联的属性。很多人第一次做这个功能时，翻车路径几乎一模一样：开关开了、内容也填了，但填错了对象；或者只处理了第一节，后面的章节打开全是第一节的页眉。

1.2 手动两分钟 vs 自动化三天：差在哪

在 Word 里设置奇偶页页眉，底层实际上改动了几个东西：

1. 节的PageSetup上“奇偶页不同”的开关——也就是DifferentOddAndEven；
2. 奇数页页眉的内容（OddHeader）；
3. 偶数页页眉的内容（EvenHeader）；
4. 多节文档中，节与节之间页眉的继承关系（LinkToPrevious）。

用 Spire.Doc 生成文档时，这些要素缺一不可。最容易踩的坑是：直接把内容填到一个名为PrimaryHeader之类的对象里，殊不知开关打开之后，Word 默认页眉就不再参与显示了，它要求你去分别填写奇偶页各自的页眉对象。第二个高发坑是：只给首个节设置了开关和内容，后续章节因为“继承上一节”的原因，要么沿用旧内容，要么你改了当前节却不生效。这些都不是 API 难，而是没把 Word 的页眉模型吃透。

所以，在贴代码之前，我建议先花几分钟把三个底层概念搞清楚。否则你只是照着代码抄一遍，换个场景还是会翻车。

2. 动手前先把三个底层概念吃透：开关、对象类型、继承关系

2.1 DifferentOddAndEven：它不是“文档设置”，是“节的设置”

Word 排版的最小单位不是文档，而是“节”（Section）。一个文档可以由多个节组成，每一节可以有自己的页面大小、页边距、页眉页脚规则。奇偶页不同这个功能，在对象模型里就挂在Section.PageSetup下，而不是挂在Document上：

section.PageSetup.DifferentOddAndEven = true;

这行代码的作用范围，只有当前这一个节。如果你有一个 5 节的文档，只对第 1 节执行了这句话，后面 4 节的页面设置仍然是“不区分奇偶页”的状态。

为什么 Word 要把这个开关设计在“节”这个层级？因为一本书的前言、正文、附录往往有不同的版面规则：前言可能不需要页眉，正文需要奇偶页交替页眉，附录又换一种页码格式。用节隔离这些规则是最合理的做法。Spire.Doc 完整地保留了这个模型，所以你在代码里也应该按照“一个节一个节处理”的思路来设计，而不是妄想设置一次全局生效。

在多节文档里，标准的批量设置方式就是遍历：

foreach (Section sec in doc.Sections) { sec.PageSetup.DifferentOddAndEven = true; }

这里有个容易被忽略的先后顺序问题：我建议先打开所有节的开关，再统一填充页眉页脚内容，避免边设置边填充导致某些对象状态不一致。

2.2 HeaderFooterType：一旦打开开关，默认页眉就“让位”

DifferentOddAndEven = true之后，页眉页脚对象的分工立即发生变化。

未开启开关时，文档里所有页面都使用同一套页眉页脚，Spire.Doc 里对应的是PrimaryHeader和PrimaryFooter（部分版本叫HeaderPrimary，命名随版本略有差异）。开启奇偶页不同后，这套“默认页眉页脚”就退居二线，奇数页和偶数页各自使用独立对象：

这一点非常重要。很多人设置完发现“偶数页没有页眉”，原因往往不是代码没执行，而是往PrimaryHeader里写了内容。开关打开后，Word 渲染时根本不去读这个对象，偶数页自然就是空白页眉。

反过来还有一个对称的坑：如果开关没打开，但你往OddHeader、EvenHeader里塞了内容，Word 同样不会显示——因为此时文档读取的是PrimaryHeader。

所以写代码前，先确认你到底需要哪几个对象。最常见的组合是：

• 奇数页页眉：公司名称，右对齐；
• 偶数页页眉：文档名称/项目编号，左对齐；
• 奇数页页脚：页码，右对齐；
• 偶数页页脚：页码，左对齐。

这就是书籍和正式文档里最典型的“页码在外侧”布局。

2.3 LinkToPrevious：节与节之间的继承关系，坑中之王

前面讲的是单节文档的情况。一旦文档有多个节，LinkToPrevious就会成为最大的隐性变量。

Word 里的页眉页脚默认具备“链接到前一节”的特性：当前节的页眉如果设置了继承，它会沿用上一节的页眉内容和格式。这样设计是为了方便“全书统一页眉”的场景——你只要在第一节设置好，后面所有节的页眉自动保持相同，不需要每节重复劳动。

但这个特性在自动化场景里是个双刃剑。你满心以为给第 3 节写了一套新页眉，打开文档一看，第 3 节显示的仍然是第 1 节的内容。原因就是第 3 节的LinkToPrevious没有关掉，你写的内容被“上一节的继承”覆盖了。

在 Spire.Doc 中，处理方式很直接：

HeaderFooter oddHeader = sec.HeadersFooters[HeaderFooterType.OddHeader]; oddHeader.LinkToPrevious = false;

把LinkToPrevious设为false之后，当前节才真正拥有独立的页眉页脚内容，你往里面写的东西才会显示出来。

反过来，如果你的业务需求是“所有章节使用同一套奇偶页页眉”，那最佳策略反而是什么都不做，让后续节保持默认的LinkToPrevious = true，只在第一节配置奇偶页页眉内容即可。这比每个节都重复写一遍内容更可靠，因为后续节哪怕你想统一修改，也只需要改这一处。

3. Spire.Doc 设置奇偶页页眉/页脚：一个能跑的完整代码

3.1 环境准备：包、版本与前置注意点

我用的是 .NET 6 控制台项目，通过 NuGet 安装 Spire.Doc：

Install-Package Spire.Doc

建议直接拉取最新稳定版，不要用太老的版本，因为早期版本对.docx的兼容性和页面对象的支持都不如新版完整。

这里要提一下授权问题：Spire.Doc Free 版本可以免费使用，但对生成文档的篇幅有限制（段落数、表格数等），页眉页脚里如果有复杂内容，也不建议依赖免费版做生产级大批量输出。商业项目里要么购买授权，要么评估一下是否在免费限制范围内。代码层面可以通过doc.SetLicense(...)加载授权文件，消除评估限制。

另外，如果目标环境是 Linux 容器，需要确认 Spire.Doc 依赖的字体可用。页眉里如果指定了“微软雅黑”而容器里没有这个字体，最终产出的文档打开会出现字体回退，页眉的宽度、高度都可能受影响。我一般会在文档生成前统一检查一遍字体策略。

3.2 单节文档的核心代码

下面这段代码，是单节文档里设置奇偶页页眉/页脚的完整示例，我在实际项目里跑过：

using Spire.Doc; using Spire.Doc.Documents; using Spire.Doc.Fields; using System.Drawing; public void BuildDocumentWithOddEvenHeaders() { // 1. 创建文档并添加节 Document doc = new Document(); Section section = doc.AddSection(); // 2. 打开“奇偶页不同”开关 section.PageSetup.DifferentOddAndEven = true; section.PageSetup.HeaderDistance = 55f; // 3. 取出奇数页/偶数页的页眉页脚对象 // 注意：不同版本 Spire.Doc 的 HeaderFooterType 枚举命名可能略有差异， // 常见写法是 OddHeader / EvenHeader。 HeaderFooter oddHeader = section.HeadersFooters[HeaderFooterType.OddHeader]; HeaderFooter evenHeader = section.HeadersFooters[HeaderFooterType.EvenHeader]; HeaderFooter oddFooter = section.HeadersFooters[HeaderFooterType.OddFooter]; HeaderFooter evenFooter = section.HeadersFooters[HeaderFooterType.EvenFooter]; // 4. 奇数页页眉：公司名称，右侧对齐，带下边框线 Paragraph oddHeaderPara = oddHeader.Paragraphs.Count > 0 ? oddHeader.Paragraphs[0] : oddHeader.AddParagraph(); oddHeaderPara.Clear(); TextRange company = oddHeaderPara.AppendText("某某科技有限公司 ｜ 客服热线 400-800-8888"); company.CharacterFormat.FontName = "微软雅黑"; company.CharacterFormat.FontSize = 10f; oddHeaderPara.Format.HorizontalAlignment = HorizontalAlignment.Right; SetHeaderBottomLine(oddHeaderPara); // 5. 偶数页页眉：文档名称，左侧对齐，带下边框线 Paragraph evenHeaderPara = evenHeader.Paragraphs.Count > 0 ? evenHeader.Paragraphs[0] : evenHeader.AddParagraph(); evenHeaderPara.Clear(); TextRange docName = evenHeaderPara.AppendText("2025年产品技术白皮书"); docName.CharacterFormat.FontName = "微软雅黑"; docName.CharacterFormat.FontSize = 10f; evenHeaderPara.Format.HorizontalAlignment = HorizontalAlignment.Left; SetHeaderBottomLine(evenHeaderPara); // 6. 奇数页页脚：页码右对齐 Paragraph oddFooterPara = oddFooter.Paragraphs.Count > 0 ? oddFooter.Paragraphs[0] : oddFooter.AddParagraph(); oddFooterPara.Clear(); oddFooterPara.AppendText("第 "); oddFooterPara.AppendField("PAGE", FieldType.FieldPage); oddFooterPara.AppendText(" 页"); oddFooterPara.Format.HorizontalAlignment = HorizontalAlignment.Right; // 7. 偶数页页脚：页码左对齐 Paragraph evenFooterPara = evenFooter.Paragraphs.Count > 0 ? evenFooter.Paragraphs[0] : evenFooter.AddParagraph(); evenFooterPara.Clear(); evenFooterPara.AppendText("第 "); evenFooterPara.AppendField("PAGE", FieldType.FieldPage); evenFooterPara.AppendText(" 页"); evenFooterPara.Format.HorizontalAlignment = HorizontalAlignment.Left; // 8. 让 Word 打开文档时自动刷新页眉页脚里的页码域 doc.IsUpdateFields = true; doc.SaveToFile("output.docx", FileFormat.Docx2013); doc.Close(); } private void SetHeaderBottomLine(Paragraph paragraph) { paragraph.Format.Borders.Bottom.BorderType = BorderStyle.Single; paragraph.Format.Borders.Bottom.Color = Color.Gray; paragraph.Format.Borders.Bottom.LineWidth = 0.75f; }

代码的关键点只有几个，但每个都值得单独拎出来说。

3.3 页码域：为什么必须是 Field，而不是普通文本

很多人第一次写页脚时，图省事直接在页脚里写一个“第 1 页”，结果文档翻到第 10 页，页脚还是“第 1 页”。因为那只是普通文本，不会跟着页码变化。

正确做法是用 Word 域（Field）。上面代码里的AppendField("PAGE", FieldType.FieldPage)插入的就是页码域。这个域的本质是告诉 Word：“这里显示当前页的页码，不要写死。”同样的方式也可以插入总页数域，只要把FieldType.FieldPage换成FieldType.FieldNumPages即可。

域有个特性：它需要一个“刷新”动作才会计算并显示最新值。在 Word 里手动刷新是按Ctrl + A全选、再按F9。在 Spire.Doc 里，保存前设置：

doc.IsUpdateFields = true;

指示生成器在保存文档时主动刷新一次域，这样生成出来的 docx，用户直接用 Word 打开就能看到正确的页码，而不是看到一个空白域或缓存值。

3.4 页眉线：默认没有线，想要线必须自己加

Word 里新建文档的页眉默认不带竖线或横线，通常大家看到的是页眉文字下面一条细线，那是段落的下边框，不是页眉自带的。

用 Spire.Doc 生成时，如果你希望页眉下方有那条标准细线，需要手动给页眉段落设置底部边框。对应到代码就是SetHeaderBottomLine方法里那三行：

paragraph.Format.Borders.Bottom.BorderType = BorderStyle.Single; paragraph.Format.Borders.Bottom.Color = Color.Gray; paragraph.Format.Borders.Bottom.LineWidth = 0.75f;

如果你发现生成的页眉“光秃秃”的，没有分隔线，多半就是漏了这一步。想要更粗的线，把LineWidth调大即可；想换成双线、虚线，改BorderStyle枚举就行。

4. 把“单节演示”变成“生产级批量自动化”

4.1 多节场景：统一遍历，规则一致

现实中的长篇文档很少只有一节：封面一个节、目录一个节、正文可能再拆出几个节。每个节都需要正确处理奇偶页设置，否则就会出现“前面几页正常，中间某章突然没有页眉了”的诡异现象。

我的做法是封装一个统一的方法，接收Document对象，在内部遍历所有节，逐个打开DifferentOddAndEven开关，并按照统一的样式填充页眉页脚：

public void ApplyOddEvenHeaders(Document doc) { foreach (Section sec in doc.Sections) { sec.PageSetup.DifferentOddAndEven = true; var oddHeader = sec.HeadersFooters[HeaderFooterType.OddHeader]; var evenHeader = sec.HeadersFooters[HeaderFooterType.EvenHeader]; var oddFooter = sec.HeadersFooters[HeaderFooterType.OddFooter]; var evenFooter = sec.HeadersFooters[HeaderFooterType.EvenFooter]; FillHeader(oddHeader, "公司名称及联系方式", HorizontalAlignment.Right); FillHeader(evenHeader, "项目编号 / 文档密级", HorizontalAlignment.Left); FillPageNumber(oddFooter, HorizontalAlignment.Right); FillPageNumber(evenFooter, HorizontalAlignment.Left); } }

如果某个节需要不一样的页眉内容，比如“附录”章节的页眉要换成附录名称，不要在这个统一方法里死写内容，而是在调用完统一方法之后，单独对特殊节做覆盖处理。覆盖前记得先把LinkToPrevious设为false，否则你改的内容不会生效。

这里有一个我在项目里踩过的坑：你在统一方法里把每一节的页眉内容都填了一遍，但后续节默认LinkToPrevious是true，你填的内容根本没被渲染。所以要么你像我一样在统一方法里显式把LinkToPrevious设为false（代价是每节内容独立存储），要么只改第一节并保持后续节继承。两种思路都行，但别混着用，否则排查起来非常痛苦。

4.2 更推荐的路线：模板 + 内容替换，而不是全代码画

讲完纯代码方案，我再分享一个更稳妥的路线：先做一个带好奇偶页页眉/页脚的模板 docx，再用 Spire.Doc 加载模板、用内容替换的方式生成最终文档。

为什么推荐模板？因为 Word 模板里的页眉页脚是“所见即所得”的，排版细节可以交给 Word 完成，代码只负责把动态内容填进去。比如模板的奇数页页眉里放了一个占位符{{CompanyName}}，代码里只需要：

doc.Replace("{{CompanyName}}", "某某科技有限公司", true, true);

这种方案的优点非常明显：

• 样式稳定：页眉线的粗细、字体、间距在模板里定好，代码不会破坏；
• 多节继承关系天然正确：Word 里做模板时，后续节的继承关系已经是正常状态；
• 后期维护方便：业务方想调整页眉文字，直接在模板里改，不需要改代码重新发布。

什么时候必须用全代码方案？比如模板本身需要根据接口数据动态生成，或者用户上传的文件没有固定结构，必须程序化重建版式。除此之外，我个人的经验是优先上模板。

4.3 批量生成合同的工程化细节

批量场景下，除了页眉页脚本身的设置，还有几个细节容易被忽视：

• 资源释放：每份文档生成完，记得doc.Close()，或者用using语句包裹Document。批量循环里如果把Document对象堆积在内存里，跑几百份合同就可能内存报警。
• 字体一致性：页眉里用了目标机器没有的字体，Word 打开时会自动替换，可能让页眉文字变宽变窄，影响页眉线位置。尽可能用宋体、微软雅黑这类常见字体。
• 页眉距离：Section.PageSetup.HeaderDistance控制页眉顶部边距。合同模板通常要求页眉离页边距有一定距离，设置之前先量一下模板的数值，别凭感觉填。
• License 与规模限制：免费版生成大文档受限，批量生产环境务必确认授权，否则用户打开时可能出现不可预期的问题。

5. 生成之后：怎么确认“奇偶页页眉”真的对了

5.1 三档验证手段，从快到慢

代码写完、文档生成后，千万不要只信任控制台打印的“生成成功”。我见过太多“代码没报错，打开全毁了”的情况。建议按下面三档验证：

第一档：Word 打开烟雾测试。翻文档前三页和中间任意一页，确认奇数页和偶数页的页眉内容是否分别正确，页码位置是否一右一左。速度快，适合开发期自测。

第二档：Spire.Doc 回读校验。把生成好的 docx 重新用 Spire.Doc 打开，遍历每个节，检查DifferentOddAndEven开关和HeadersFooters里奇数页/偶数页对象的内容是否非空：

using Document doc = new Document(); doc.LoadFromFile("output.docx"); foreach (Section sec in doc.Sections) { Console.WriteLine($"DifferentOddAndEven: {sec.PageSetup.DifferentOddAndEven}"); Console.WriteLine($"OddHeader text: {sec.HeadersFooters[HeaderFooterType.OddHeader]?.Paragraphs[0]?.GetText()}"); Console.WriteLine($"EvenHeader text: {sec.HeadersFooters[HeaderFooterType.EvenHeader]?.Paragraphs[0]?.GetText()}"); }

第三档：OpenXML 层面检查。如果你想把校验自动化程度提到最高，可以直接把.docx后缀改成.zip解压，检查word/目录下的页眉文件。一个开启奇偶页不同的文档，通常会有独立的header1.xml、header2.xml（分别对应奇数页和偶数页页眉），对应关系记录在document.xml.rels里。这一档适合做 CI 里的自动化断言，精确到文件级别。

5.2 高频问题排查表

下面是我在支持同事和社区朋友时见过的高频问题，以及对应的处理方向：

这些坑我都踩过，尤其是LinkToPrevious，它往往藏得最深，因为代码不报错、文档也能打开，只是页眉内容不对。遇到“改不动”的问题，第一时间去查它，通常能省下半天排查时间。

最后说点个人经验。我现在做这类文档自动化功能，已经很少从零开始用代码画页眉页脚了，除非业务上确实没有模板可参考。更常用的路径是：先让业务方在 Word 里把模板版式做出来，包括奇偶页页眉、页眉线、页码域，我再用 Spire.Doc 加载模板、替换数据、批量导出。这套组合无论在样式稳定性还是后期维护成本上，都比纯代码绘制更省心。

如果你也是刚开始接触这个功能，我建议再留意一个细节：上线前一定要在一台干净的、没有安装常规办公字体的环境里验证一次生成的文档。很多时候开发机一切正常，到了客户机器上页眉突然变宽、换行，就是因为字体回退。这类型问题不会每次都出现，但出现一次就够你加班排查一整晚。