前段时间接了个合同批量生成的需求其中一个排版要求是奇数页页眉放公司全称和客服电话偶数页页眉放项目编号页码一律“放在外侧”也就是奇数页右下、偶数页左下。Word 里就是页面设置里勾一个“奇偶页不同”的事两分钟能搞定但如果要在 .NET 文档自动化里用代码批量产出一百份 docx事情就没那么轻松了——Spire.Doc 这类库虽然封装得不错奇偶页页眉/页脚相关的 API 依然有一堆容易让人踩坑的细节。这篇就讲讲我在 .NET 里用 Spire.Doc 设置奇偶页页眉/页脚的最佳实践包括底层原理、完整代码、批量场景的工程化写法以及生成之后怎么验证才算靠谱。适合正在做合同、标书、报告、书籍排版类自动化功能的开发同学参考。1. 为什么偏偏是“奇偶页页眉/页脚”最容易在自动化里翻车1.1 这类需求大多来自哪里我接触到的奇偶页页眉/页脚需求基本集中在以下几类文档里合同和标书奇数页页眉放公司抬头、销售电话偶数页页眉放项目编号或文件密级页码统一在最外侧方便装订后翻阅。书籍、期刊、论文排版双面打印时奇数页页眉放章节名偶数页页眉放书名页码位置一左一右形成镜像效果。长型报告、白皮书封面、目录、正文、附录往往分属不同节封面不要页眉正文从某一节才开始出现奇偶页不同的页眉/页脚。这些场景有一个共同点一旦进入“批量生成”阶段就是要同时输出几十上百份文档人工在 Word 里一份份勾选设置根本不现实。所以只能靠代码把每个节的页面设置、页眉页脚对象、内容填充全部做对。问题在于手动在 Word 里操作只需要记住“页面设置 - 版式 - 奇偶页不同”这一个入口而用代码操作时你面对的是 Word 对象模型里一系列彼此关联的属性。很多人第一次做这个功能时翻车路径几乎一模一样开关开了、内容也填了但填错了对象或者只处理了第一节后面的章节打开全是第一节的页眉。1.2 手动两分钟 vs 自动化三天差在哪在 Word 里设置奇偶页页眉底层实际上改动了几个东西节的PageSetup上“奇偶页不同”的开关——也就是DifferentOddAndEven奇数页页眉的内容OddHeader偶数页页眉的内容EvenHeader多节文档中节与节之间页眉的继承关系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同一套 PrimaryHeader开启奇偶页不同OddHeaderEvenHeader开启奇偶页不同 开启首页不同OddHeaderEvenHeader FirstPageHeader这一点非常重要。很多人设置完发现“偶数页没有页眉”原因往往不是代码没执行而是往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.DocInstall-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 高频问题排查表下面是我在支持同事和社区朋友时见过的高频问题以及对应的处理方向症状可能原因处理办法奇数页页眉正确偶数页页眉空白只往PrimaryHeader里写了页眉开关打开后 Word 不读这个对象或EvenHeader内容为空显式获取并填充EvenHeader整篇文档页眉完全一致看不出奇偶页区分DifferentOddAndEven没有置为true或者设置成了false检查每个节的PageSetup.DifferentOddAndEven第 2 节、第 3 节页眉改不动一直显示第 1 节的内容当前节的LinkToPrevious为true继承上一节修改前设置LinkToPrevious false页脚里的页码始终是同一数字插入的是普通文本不是页码域用AppendField(PAGE, FieldType.FieldPage)插入动态页码页眉文字下方没有分隔线没设置段落下边框设置Format.Borders.Bottom的线型、颜色、线宽页眉文字位置不对要么太靠左要么太靠右段落水平对齐方式不对设置Format.HorizontalAlignment为Right或Left生成的文档在 WPS 里正常Word 里页眉窜位字体缺失导致文本宽度变化模板根因统一字体优先使用模板方案这些坑我都踩过尤其是LinkToPrevious它往往藏得最深因为代码不报错、文档也能打开只是页眉内容不对。遇到“改不动”的问题第一时间去查它通常能省下半天排查时间。最后说点个人经验。我现在做这类文档自动化功能已经很少从零开始用代码画页眉页脚了除非业务上确实没有模板可参考。更常用的路径是先让业务方在 Word 里把模板版式做出来包括奇偶页页眉、页眉线、页码域我再用 Spire.Doc 加载模板、替换数据、批量导出。这套组合无论在样式稳定性还是后期维护成本上都比纯代码绘制更省心。如果你也是刚开始接触这个功能我建议再留意一个细节上线前一定要在一台干净的、没有安装常规办公字体的环境里验证一次生成的文档。很多时候开发机一切正常到了客户机器上页眉突然变宽、换行就是因为字体回退。这类型问题不会每次都出现但出现一次就够你加班排查一整晚。 
长河君 · 2026/10/10 15:38:49 · 阅读 1.2k Spire.Doc 设置奇偶页页眉页脚：从原理到批量生成的完整指南
前段时间接了个合同批量生成的需求其中一个排版要求是奇数页页眉放公司全称和客服电话偶数页页眉放项目编号页码一律“放在外侧”也就是奇数页右下、偶数页左下。Word 里就是页面设置里勾一个“奇偶页不同”的事两分钟能搞定但如果要在 .NET 文档自动化里用代码批量产出一百份 docx事情就没那么轻松了——Spire.Doc 这类库虽然封装得不错奇偶页页眉/页脚相关的 API 依然有一堆容易让人踩坑的细节。这篇就讲讲我在 .NET 里用 Spire.Doc 设置奇偶页页眉/页脚的最佳实践包括底层原理、完整代码、批量场景的工程化写法以及生成之后怎么验证才算靠谱。适合正在做合同、标书、报告、书籍排版类自动化功能的开发同学参考。1. 为什么偏偏是“奇偶页页眉/页脚”最容易在自动化里翻车1.1 这类需求大多来自哪里我接触到的奇偶页页眉/页脚需求基本集中在以下几类文档里合同和标书奇数页页眉放公司抬头、销售电话偶数页页眉放项目编号或文件密级页码统一在最外侧方便装订后翻阅。书籍、期刊、论文排版双面打印时奇数页页眉放章节名偶数页页眉放书名页码位置一左一右形成镜像效果。长型报告、白皮书封面、目录、正文、附录往往分属不同节封面不要页眉正文从某一节才开始出现奇偶页不同的页眉/页脚。这些场景有一个共同点一旦进入“批量生成”阶段就是要同时输出几十上百份文档人工在 Word 里一份份勾选设置根本不现实。所以只能靠代码把每个节的页面设置、页眉页脚对象、内容填充全部做对。问题在于手动在 Word 里操作只需要记住“页面设置 - 版式 - 奇偶页不同”这一个入口而用代码操作时你面对的是 Word 对象模型里一系列彼此关联的属性。很多人第一次做这个功能时翻车路径几乎一模一样开关开了、内容也填了但填错了对象或者只处理了第一节后面的章节打开全是第一节的页眉。1.2 手动两分钟 vs 自动化三天差在哪在 Word 里设置奇偶页页眉底层实际上改动了几个东西节的PageSetup上“奇偶页不同”的开关——也就是DifferentOddAndEven奇数页页眉的内容OddHeader偶数页页眉的内容EvenHeader多节文档中节与节之间页眉的继承关系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同一套 PrimaryHeader开启奇偶页不同OddHeaderEvenHeader开启奇偶页不同 开启首页不同OddHeaderEvenHeader FirstPageHeader这一点非常重要。很多人设置完发现“偶数页没有页眉”原因往往不是代码没执行而是往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.DocInstall-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 高频问题排查表下面是我在支持同事和社区朋友时见过的高频问题以及对应的处理方向症状可能原因处理办法奇数页页眉正确偶数页页眉空白只往PrimaryHeader里写了页眉开关打开后 Word 不读这个对象或EvenHeader内容为空显式获取并填充EvenHeader整篇文档页眉完全一致看不出奇偶页区分DifferentOddAndEven没有置为true或者设置成了false检查每个节的PageSetup.DifferentOddAndEven第 2 节、第 3 节页眉改不动一直显示第 1 节的内容当前节的LinkToPrevious为true继承上一节修改前设置LinkToPrevious false页脚里的页码始终是同一数字插入的是普通文本不是页码域用AppendField(PAGE, FieldType.FieldPage)插入动态页码页眉文字下方没有分隔线没设置段落下边框设置Format.Borders.Bottom的线型、颜色、线宽页眉文字位置不对要么太靠左要么太靠右段落水平对齐方式不对设置Format.HorizontalAlignment为Right或Left生成的文档在 WPS 里正常Word 里页眉窜位字体缺失导致文本宽度变化模板根因统一字体优先使用模板方案这些坑我都踩过尤其是LinkToPrevious它往往藏得最深因为代码不报错、文档也能打开只是页眉内容不对。遇到“改不动”的问题第一时间去查它通常能省下半天排查时间。最后说点个人经验。我现在做这类文档自动化功能已经很少从零开始用代码画页眉页脚了除非业务上确实没有模板可参考。更常用的路径是先让业务方在 Word 里把模板版式做出来包括奇偶页页眉、页眉线、页码域我再用 Spire.Doc 加载模板、替换数据、批量导出。这套组合无论在样式稳定性还是后期维护成本上都比纯代码绘制更省心。如果你也是刚开始接触这个功能我建议再留意一个细节上线前一定要在一台干净的、没有安装常规办公字体的环境里验证一次生成的文档。很多时候开发机一切正常到了客户机器上页眉突然变宽、换行就是因为字体回退。这类型问题不会每次都出现但出现一次就够你加班排查一整晚。