1. 为什么“导出带目录的Word”是个技术活
很多人觉得Word加目录不就是点一下“引用→目录”的事吗？但真正在项目里做过文档自动化导出的人都知道，这里面的坑远比想象中多。我做过不下二十个涉及Word导出的项目，从最简单的报告生成到几百页的技术手册批量输出，几乎每一次都会在目录这个环节卡上一阵。原因很简单：目录的本质是“域”，而域的行为依赖于样式、分页、更新时机和导出格式，任何一个环节没对齐，导出的文件要么目录空白，要么页码错乱，要么在PDF里变成一堆死链接。
先把概念理清楚。所谓“带目录的Word导出”，通常包含两层含义：第一层是在Word文档内部生成一个可点击、可更新的目录结构；第二层是把这份带目录的文档导出为PDF或XPS等固定版式格式，且目录的页码和链接在导出后依然正确。这两层需求经常被混在一起讨论，但它们的实现路径完全不同。Word内部目录靠的是标题样式加TOC域，而导出PDF时目录能否保留，取决于导出工具对书签和域的解析能力。
热搜词里出现的“目录结构”“设置好多级标题的word”“目录深度”这些词，其实都指向同一个核心问题：目录的层级和内容来源于标题样式，而不是你手动敲的文字。我见过太多人用加粗加大字号来“假装”标题，然后困惑为什么目录生成出来是空的。这个认知门槛必须先跨过去，后面的操作才有意义。
这篇文章适合三类人看：一是需要用代码批量生成Word报告的后端开发者，二是经常手动整理长文档的办公人员，三是需要把Word转成PDF交付给客户的实施人员。我会从原理讲到实操，从手动操作讲到代码实现，把目录导出这件事彻底拆开。
2. 目录生成的底层逻辑与核心概念拆解
2.1 标题样式才是目录的“数据源”
Word的目录不是独立存在的东西，它是一个域代码，本质上是一段指令，告诉Word“去文档里找所有应用了标题1到标题N样式的段落，把它们提取出来，按层级排列，再配上页码”。你看到的目录文字，是Word执行这段指令后的渲染结果。
这就解释了一个常见现象：你手动输入一行“第一章 概述”并加粗，它不会出现在目录里；但你把同样的文字应用“标题1”样式，它就会自动进入目录。样式是身份标识，格式只是外观。很多人把这两者搞混，是因为Word默认的标题样式恰好也带了加粗和放大，视觉上看起来差不多，但语义完全不同。
在代码生成Word的场景下，这个逻辑更加关键。以Java的Apache POI为例，你创建一个段落时，如果不显式设置样式为Heading 1，即使你把字号设成22磅、加粗、居中，POI也不会把它当作标题处理，生成的目录域自然抓不到内容。POI本身不会自动生成目录内容，它只能插入一个TOC域，真正的目录内容需要Word打开时更新域才能显示。
2.2 TOC域的组成与更新机制
一个完整的TOC域包含三个部分：域开始标记、域指令和域结果。域指令里写着类似TOC \o "1-3" \h \z \u这样的参数，含义分别是：
\o "1-3"：提取标题1到标题3的内容\h：生成超链接，目录项可点击跳转\z：在Web版式中隐藏页码\u：使用大纲级别而非样式来识别标题
这些参数决定了目录的形态。比如你把\o "1-3"改成\o "1-5"，目录就会多出两级。热搜词里的“目录深度”说的就是这个参数的控制。
域结果就是你在Word里看到的那些目录行。关键点在于：域结果是可以过期的。当你修改了文档内容、增删了标题、页码发生变化后，域结果不会自动刷新，需要手动按F9或右键选择“更新域”。在代码生成的场景下，POI插入的TOC域初始状态是空的，必须由Word打开后触发更新，或者用其他工具在导出前强制刷新。
2.3 导出PDF/XPS时目录为什么容易出问题
Word内部显示正常的目录，导出PDF后出问题，通常有三个原因：
第一，导出工具不执行域更新。很多第三方库在转换时直接读取域的缓存结果，如果缓存是空的或者过期的，PDF里的目录就是错的。Word自身的“另存为PDF”功能会先更新域再导出，但代码调用时未必走了这条路径。
第二，书签和链接的映射丢失。目录项在Word里是超链接，指向文档内的锚点。导出PDF时，如果工具不支持书签转换，目录就变成了纯文本，点击无法跳转。热搜词里的“pdf编辑器”“pdf解析”之所以被关联，就是因为很多人导出后发现目录不能点，只能回头用PDF工具补救。
第三，页码偏移。Word的分页和PDF的分页计算方式不同，尤其是涉及分节符、页眉页脚、封面不编页码等情况时，目录里写的页码和PDF实际页码可能差好几页。这个问题在手动操作时容易被忽略，因为Word里看着是对的，导出后才暴露。
2.4 手动操作与代码生成的路径差异
手动操作Word加目录，流程是：设置标题样式→插入TOC域→更新域→导出PDF。这条路径依赖Word客户端，适合单次操作。
代码生成的路径则分两种：一种是用POI等库生成docx，插入TOC域，然后交给Word或LibreOffice更新域并导出；另一种是直接用PDF生成库（如iText）从头构建带书签的PDF，跳过Word环节。两种路径各有适用场景，前者适合需要保留Word可编辑性的需求，后者适合纯PDF交付且对格式控制要求高的场景。
热搜词里“java poi word能生成图表吗”和“markdown转word工作流coze”反映的正是这种代码生成需求的多样性。POI能生成图表，但图表和目录一样，都属于“生成容易、更新难”的范畴。
3. 手动操作：从零生成带目录的Word并导出PDF
3.1 标题样式的规范设置
打开Word，先别急着写内容。第一步是确认“开始”选项卡里的样式面板中，标题1、标题2、标题3的样式符合你的预期。右键点击“标题1”，选择“修改”，可以调整字体、字号、颜色、段落间距等。这里有个经验：标题样式的格式改动会同步影响目录的显示格式，因为目录默认继承标题样式的字符格式。如果你希望目录里的文字比正文标题小一号，不要直接改标题样式，而是在目录生成后单独调整目录样式。
设置多级标题时，建议用“多级列表”功能把标题1、标题2、标题3和编号（如1.1、1.1.1）绑定起来。这样你应用标题样式时，编号会自动出现，而且编号会正确反映在目录里。热搜词“设置好多级标题的word”说的就是这个操作。具体路径是：开始→段落→多级列表→定义新的多级列表→把级别1链接到标题1样式，级别2链接到标题2样式，以此类推。
注意：如果你手动输入编号而不是用多级列表，目录里的编号可能和正文不一致，尤其是增删章节后需要手动改编号，非常容易出错。
3.2 插入TOC域的正确姿势
内容写完后，把光标放在要放目录的位置（通常是封面之后、正文之前）。点击“引用→目录→自动目录”，Word会插入一个默认的TOC域。如果你需要更精细的控制，选择“自定义目录”，在弹出的对话框里可以设置：
- 显示页码：勾选
- 页码右对齐：勾选
- 制表符前导符：选省略号或点线
- 格式：选“来自模板”或“正式”
- 显示级别：默认3级，可以改成1到9级
点击确定后，目录就生成了。此时如果你修改了正文标题，目录不会自动变，需要右键点击目录→更新域→更新整个目录。
3.3 导出PDF时的关键设置
Word里目录显示正常后，点“文件→另存为→PDF”。在保存对话框里点“选项”，确认勾选了“创建书签时使用：标题”和“文档结构标记”。这两个选项决定了PDF里是否保留目录的书签结构。如果不勾，导出的PDF虽然能看到目录文字，但左侧的书签面板是空的，点击目录项也无法跳转。
另外，如果文档有封面和目录页本身不编页码的需求，需要提前用分节符把文档分成三节：封面节、目录节、正文节。然后在正文节的页脚里设置页码起始为1，并断开与前一节的链接。这样目录里显示的页码才是正文的实际页码，而不是从封面算起的物理页码。
3.4 导出XPS的差异说明
XPS是微软的固定版式格式，操作路径和PDF类似，但兼容性差很多。XPS在非Windows系统上几乎没人用，而且很多PDF工具不支持XPS转换。热搜词里“rpt和xps是什么文件”说明有人遇到过这种格式但不清楚用途。我的建议是：除非甲方明确要求XPS，否则一律导出PDF。如果已经拿到了XPS文件需要转PDF，可以用Windows自带的XPS Viewer打印成PDF，但目录书签大概率会丢失，需要后期用PDF工具补。
4. 代码实现：用Java POI生成带目录的Word文档
4.1 POI生成目录的技术限制
Apache POI是Java生态里操作Word文档最常用的库，但它对目录的支持有个根本性限制：POI可以插入TOC域，但不能计算目录内容。也就是说，你用POI生成的docx文件里，目录位置只有一个空的域标记，打开Word时会提示“此文档包含的域可能未更新”，需要手动按F9或全选后更新域才能看到目录。
这个限制来自Word的域更新机制——域的计算是Word客户端的职责，POI作为服务端库没有实现这套排版引擎。所以如果你的需求是“生成后直接交付，用户打开就能看到目录”，纯POI方案不够，需要配合LibreOffice或Word自动化来刷新域。
4.2 插入TOC域的代码实现
下面是一个用POI插入TOC域的核心代码片段。关键点是使用XWPFParagraph的createRun()和底层的CTSimpleField来构造域指令：
import org.apache.poi.xwpf.usermodel.*; import org.openxmlformats.schemas.wordprocessingml.x2006.main.*; public void insertTOC(XWPFDocument document) { XWPFParagraph paragraph = document.createParagraph(); XWPFRun run = paragraph.createRun(); // 构造TOC域指令 CTSimpleField tocField = paragraph.getCTP().addNewFldSimple(); tocField.setInstr("TOC \\o \"1-3\" \\h \\z \\u"); // 设置域结果占位文本 CTText text = CTText.Factory.newInstance(); text.setStringValue("右键此处选择“更新域”以生成目录"); CTR ctr = CTR.Factory.newInstance(); ctr.setTArray(new CTText[]{text}); tocField.setRArray(new CTR[]{ctr}); }这段代码插入的域在Word打开后是空的，需要用户手动更新。如果你希望自动更新，可以在生成后用LibreOffice的命令行工具做一次转换，LibreOffice在转换时会执行域更新。
4.3 标题样式的代码设置
要让TOC域能抓到内容，每个标题段落必须设置正确的样式。POI里设置样式的方式是：
XWPFParagraph heading = document.createParagraph(); heading.setStyle("Heading1"); // 对应Word里的“标题1” XWPFRun run = heading.createRun(); run.setText("第一章 项目概述");注意样式名称是“Heading1”而不是“标题1”，这是POI内部使用的英文样式ID。如果你用的是自定义模板，样式ID可能不同，需要用document.getStyles()来确认。
4.4 导出PDF的两种方案对比
POI生成的docx要转PDF，常见方案有两种：
| 方案 | 原理 | 优点 | 缺点 |
|---|---|---|---|
| LibreOffice命令行 | 调用soffice转换 | 免费、跨平台、能更新域 | 排版还原度约90%，复杂表格可能错位 |
| Word自动化 | 调用COM接口 | 还原度最高、域更新完整 | 仅Windows、需要装Word、并发差 |
| 第三方库 | 如Aspose.Words | 还原度高、API完善 | 商业授权费用高 |
如果项目对排版要求不苛刻，LibreOffice方案性价比最高。命令示例：
soffice --headless --convert-to pdf --outdir /output /input/document.docx实测下来，LibreOffice在转换时会自动更新TOC域，生成的PDF目录页码基本正确，书签也能保留。但要注意中文字体问题，如果服务器上没有安装文档使用的字体，转换后可能变成方框，需要提前把字体文件放到LibreOffice的字体目录。
5. 常见问题与排查技巧实录
5.1 目录空白或显示“错误！未找到目录项”
这是最高频的问题。原因通常有三个：一是标题没有应用标题样式，二是TOC域的级别参数设置不对（比如标题用了标题4但域只抓1-3级），三是域没有更新。
排查顺序：先检查正文标题是否真的应用了“标题1/2/3”样式，而不是手动格式；再右键目录→编辑域→检查\o "1-3"的范围是否覆盖了所有标题级别；最后按Ctrl+A全选后按F9强制更新所有域。
5.2 导出PDF后目录页码和实际页码不一致
这个问题多半是分节符和页码设置导致的。检查方法：在Word里切换到“草稿”视图，看分节符的位置是否正确；然后双击正文页脚，确认“链接到前一节”是断开状态，且页码起始值设为1。如果目录页本身也被编了页码，需要在目录节的页脚里设置“不显示页码”或把起始值设为其他数字。
另一个隐蔽原因是：目录域更新时，Word可能还没有完成分页计算。解决方法是先按Ctrl+End跳到文档末尾，再按Ctrl+Home回到开头，然后更新目录。这样Word已经完成了全文档分页，页码计算更准确。
5.3 POI生成的文档打开时提示域未更新
这是POI方案的固有行为，不是bug。如果不想让用户看到这个提示，可以在生成后用LibreOffice做一次“打开-保存”操作，域会被更新并缓存。或者用POI的XWPFDocument在写入前手动设置w:updateFields属性为true，这样Word打开时会自动提示更新域：
document.getDocument().getSettings().setUpdateFields(true);设置后，Word打开文档时会弹窗询问“是否更新域”，用户点“是”即可看到目录。
5.4 目录里的文字格式和预期不符
目录默认继承标题样式的字符格式。如果你希望目录文字统一用宋体小四，而标题是黑体三号，需要修改“目录1”“目录2”等样式，而不是改标题样式。路径是：引用→目录→自定义目录→修改，在弹出的样式列表里选“目录1”进行修改。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 解决方向 |
|---|---|---|
| 目录完全空白 | 标题未用样式或域未更新 | 检查样式、更新域 |
| 目录缺某些章节 | 级别参数范围不够 | 调整\o参数 |
| PDF目录不能点击 | 导出时未保留书签 | 勾选书签选项或换工具 |
| 页码差几页 | 分节符或页码起始值错误 | 检查分节和页脚设置 |
| POI生成后无目录 | 域未更新 | 设置updateFields或用LibreOffice刷新 |
| 中文变方框 | 服务器缺字体 | 安装对应字体文件 |
6. 进阶场景：批量导出与自动化流水线
6.1 批量生成报告时的目录处理策略
当你要为几十个客户各生成一份带目录的报告时，手动操作完全不现实。我的做法是：先用POI按模板生成docx，模板里预置好TOC域和标题样式；然后调用LibreOffice批量转PDF；最后用一个PDF校验脚本检查每份PDF的书签数量和页码是否正确。
校验脚本可以用Python的PyPDF2库读取PDF书签：
from PyPDF2 import PdfReader reader = PdfReader("output.pdf") outline = reader.outline print(f"书签数量: {len(outline)}")如果书签数量为0，说明转换时书签丢失，需要回头检查LibreOffice的转换参数或模板设置。
6.2 与Markdown工作流的结合
热搜词里“markdown转word工作流coze”反映了一种流行做法：用Markdown写内容，再转成Word。Pandoc是这个场景的利器，命令如下：
pandoc input.md -o output.docx --toc --toc-depth=3 --reference-doc=template.docx--toc自动生成目录，--toc-depth=3控制目录深度，--reference-doc指定样式模板。Pandoc生成的docx里目录是静态文本还是域，取决于版本和参数。较新版本的Pandoc会生成真正的TOC域，但同样需要Word打开后更新。
如果后续要转PDF，可以接一条LibreOffice命令，形成完整流水线。这套方案我在多个文档自动化项目里用过，稳定性不错，前提是模板样式要提前调好。
6.3 目录深度与文档结构的权衡
目录不是越深越好。我见过一份技术手册的目录深到四级，结果目录本身占了六页，读者翻半天才到正文。一般建议：正文超过50页的文档，目录深度控制在3级；50页以内的，2级足够。如果某些四级标题确实重要，可以在正文里用加粗或单独列表突出，而不是塞进目录。
在代码层面，控制深度就是调整TOC域的\o参数和Pandoc的--toc-depth参数。这个决策应该在模板设计阶段就定好，而不是生成后再改。
6.4 导出格式的选择：PDF还是XPS
回到热搜词里的“rpt和xps是什么文件”。XPS本质上是微软版的PDF，设计初衷是替代PDF在Windows生态里的地位，但实际市场接受度很低。除非你的交付环境明确要求XPS，否则一律选PDF。PDF的兼容性、工具链成熟度、书签支持都远好于XPS。如果甲方给了XPS模板要求填充后导出，可以用Word打开XPS（Windows上支持），另存为docx后再走正常流程。
7. 我踩过的坑与实操心得
第一个坑是样式名称的本地化问题。POI里设置样式用“Heading1”，但如果你的Word是中文版且模板里样式被重命名过，这个ID可能对不上。我遇到过一次，代码里写“Heading1”，生成的文档标题完全没有样式，目录自然是空的。后来改成从模板文件里读取实际样式ID才解决。建议在代码里加一段日志，打印document.getStyles().getStyleXWPFStyles()里所有样式的ID，确认后再用。
第二个坑是LibreOffice的字体缓存。服务器上装了字体文件后，LibreOffice不会立即识别，需要删除~/.config/libreoffice目录下的缓存并重启服务。这个坑我排查了大半天，最后在LibreOffice的日志里看到“font not found”才定位到。
第三个坑是目录更新时机。用Word自动化（COM接口）导出PDF时，如果代码里先更新目录再导出，但更新操作是异步的，导出时域还没算完，PDF里的目录就是旧的。解决方法是更新后加一个短暂的等待，或者用Fields.Update()的同步方法。这个细节在微软的文档里没有明确写，是我反复测试后总结出来的。
最后一个心得：永远在模板里预置好目录域和样式，而不是在代码里从零构造。模板文件可以用Word手动做好，包含封面、目录页、页眉页脚、样式定义，代码只负责往里面填内容和插入标题段落。这样目录的格式、页码规则、书签设置都在模板里固化，代码的复杂度大幅降低，出问题的概率也小得多。我现在做任何Word导出项目，第一步都是先花半小时做一个合格的模板，后面省下的调试时间远超这半小时。
