最近在搞一个 Java 后端导出 Word 文档的功能，需求清单里明明白白写着：默认 A4 纸、上下边距 2.54 厘米、左右边距 3.18 厘米。刚开始我寻思这不就是页面设置嘛，Word 里点两下的事。但换到用 Apache POI 5.2.2 在代码里操作，水就深了——新的 XWPF 文档一创建，连个基本的 sectPr 节点都没有，得自己往 XML 里补节点、设属性，单位还是 twips（缇），一个 1/1440 英寸的玩意儿。搞明白这套逻辑后其实一点都不复杂，但第一次接触的人确实容易在单位换算和节点位置上栽跟头。这篇文章就聊聊我用 POI 5.2.2 操作 Word 纸张和边距的完整思路和踩坑记录，给同样在做文档生成、模板导出、批量出报告的朋友做个参考。

1. 项目需求与底层逻辑：页面设置到底改的是什么

1.1 需求拆解：纸张和边距的本质

要说清楚这个需求，得先回到 OpenXML 的底层。Word 文档（.docx）本质是一堆 XML 包，页面设置信息不在代码里随便设个变量，而是写进固定的 XML 节点里。纸张大小对应pgSz节点，边距对应pgMar节点，这俩都挂在sectPr（section properties）下面。理解这个层级关系是第一步，不然你会在 POI 的茫茫 API 里迷路。

我接手的需求很简单：动态生成一个 Word，要求每一页都是 A4 尺寸，四周边距固定，页眉页脚距离边界也要合适，方便打印归档。这种需求在项目里太常见了，尤其是做企业报表、合同、公文导出的场景。页面设置没有做好，后面打印出来要么纸张不对，要么内容跑到版心外面，翻车现场那叫一个惨。

1.2 POI 5.2.2 中操作页面设置的核心 API

POI 5.2.2 处理的是新版 .docx 格式，对应的包是org.apache.poi.xwpf.usermodel。但页面设置藏在底层 XML schema 里，需要用到org.openxmlformats.schemas.wordprocessingml.x2006.main包下的类。核心就三样：

• XWPFDocument：文档对象，操作入口。
• CTBody/CTSectPr：文档 body 和节属性对象，页面设置的容器。
• CTPageSz/CTPageMar：分别代表纸张和边距。

用代码拿节点很直接：

XWPFDocument doc = new XWPFDocument(); CTBody body = doc.getDocument().getBody(); CTSectPr sectPr = body.isSetSectPr() ? body.getSectPr() : body.addNewSectPr();

这里有个细节很多人没注意：新创建的文档，body 下不一定有 sectPr。你光调用getSectPr()返回 null 就直接addNewSectPr()创建，安全。这是第一个容易踩的坑。

1.3 单位换算：twips（缇）到底是什么，为什么是 11906 而不是 210

接下来说单位。Word 的 XML 里长度单位不是厘米，也不是像素，而是twips（缇）。1 缇等于 1/20 磅，1 英寸等于 1440 缇，1 厘米约等于 567 缇。为什么要用这么小的单位？因为页面排版要求精度高，整数的磅值不够精细，缇这种派生单位可以精确到 1/1440 英寸，打印机输出时才不会产生累计误差。

A4 纸的宽高是 210mm × 297mm，换算成缇：

210mm ÷ 25.4mm × 1440 = 11905.5 ≈ 11906 297mm ÷ 25.4mm × 1440 = 16837.8 ≈ 16838

所以代码里你看到的setW(11906)、setH(16838)，就是这个算出来的。如果以后要自定义纸张尺寸，比如做名片或者标签纸，套用公式：毫米数 ÷ 25.4 × 1440，四舍五入取整数即可。

2. 纸张大小设置：从 A4 到自定义尺寸

2.1 A4 纸的标准参数与计算过程

A4 是最常用的打印纸规格。在 POI 里设置 A4，直接给pgSz节点设w和h。完整代码长这样：

import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPageSz; import org.openxmlformats.schemas.wordprocessingml.x2006.main.STPageOrientation; CTPageSz pageSize = sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(11906); pageSize.setH(16838); pageSize.setOrient(STPageOrientation.PORTRAIT); // 纵向

注意orient属性，枚举值有两种：PORTRAIT（纵向）和LANDSCAPE（横向）。默认不设置其实就是纵向，但既然手动设置了纸张，建议把方向也一起写进去，避免某些 Office 版本或第三方阅读器在解析时出现方向不明确的情况。

2.2 常见纸张的尺寸速查表

如果你不只做 A4，后面改需求要做 A3、B5，甚至美国 Letter，直接查表抄数字就行。我按实际经验整理了一份常用纸张换算表：

这个表是我挨个用公式算过再验证的。有些地方你可能会看到 A4 宽度写 11905，差一两个 twips 都属于正常。Word 官方生成的 docx 里就是 11906/16838 这组数，所以按这个抄最稳。

2.3 横向与纵向的切换细节

说完纵向，横向是另一个高频需求。很多人一开始以为把orient设为LANDSCAPE就完事了，实际不然。OpenXML 的规范里，pgSz的w和h应该表示当前纸张方向的宽和高。如果你只是改了方向但没换宽高，有些解析器会乱套，打印出来方向和版式对不上。

正确的做法是：设置横向的同时，把宽和高的值对调。

CTPageSz pageSize = sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(16838); // 横向 A4：宽对应原高度 pageSize.setH(11906); // 高对应原宽度 pageSize.setOrient(STPageOrientation.LANDSCAPE);

我试过的结论是，这样生成的文档在 Word 里打开直接就是横向，页面预览也正常，不会出现那种“方向显示横向但实际尺寸还是纵向”的诡异情况。

2.4 代码实现与验证方法

写完代码怎么验证？最直接的方式是生成文件后用 Word 打开看页面设置，但这不适合自动化。我习惯用更硬核的办法：解压 docx，直接看word/document.xml里的sectPr节点。

生成的 XML 大概是这样的结构：

<w:sectPr> <w:pgSz w:w="11906" w:h="16838" w:orient="portrait"/> <w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800" w:header="851" w:footer="992" w:gutter="0"/> </w:sectPr>

如果看到这个，说明设置写进去了。这个方法对排查问题特别有用，POI 设置没生效或属性值错乱时，看一眼 XML 就能定位问题。

3. 页边距设置：Word 页面排版的核心

3.1 四周边距与页眉页脚距离的参数解读

页边距在pgMar节点里设置，一共有七个属性：top、right、bottom、left、header、footer、gutter。前四个好理解，就是上下左右四边留白；header和footer是页眉页脚区域距离页面边缘的距离；gutter是装订线，双面打印时用来预留装订位置的额外边距。

代码设置同样简洁：

CTPageMar pageMargin = sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar(); pageMargin.setTop(1440); // 上边距 2.54cm pageMargin.setBottom(1440); // 下边距 2.54cm pageMargin.setLeft(1800); // 左边距 3.17cm pageMargin.setRight(1800); // 右边距 3.17cm pageMargin.setHeader(851); // 页眉距边界 1.5cm pageMargin.setFooter(992); // 页脚距边界 1.75cm pageMargin.setGutter(0); // 装订线 0

注意这个顺序，我见过有人把 top 和 header 搞混。top是正文区域离纸张上边缘的距离，header是页眉内容（比如页码、公司名）离纸张上边缘的距离。正常情况下header必须小于top，否则页眉会压到正文上。Word 里默认页眉是 1.5 厘米，正文上边距 2.54 厘米，所以header(851) < top(1440)是合理的。

3.2 常见边距规范：论文、公文、商业文档的边距参考

不同场景对边距的要求差异很大，这是做文档导出时必须面对的“需求多样性”。我列几个实际项目中经常碰到的规范：

党政公文那个规格，我记得是上边缘 3.7cm、下边缘 3.5cm、左边缘 2.8cm、右边缘 2.6cm，换算成缇分别约等于 2098、1985、1587、1474。做政务系统对接的人应该会用到。你手头若是接的合同导出或论文导出，直接按上面表格抄，或者问需求方要版式文件更稳。

3.3 代码实现与常见误区

写代码时最大的误区有两处。第一，单位没换算，直接把厘米数填进去，生成出来的文档边距会小到离谱。第二，setGutter(0)漏了，某些模板从别处复制过来可能带了装订线设置，导致页面的可排版宽度和预想的不一样。

再说一个容易忽略的点：新文档和模板文档的处理方式不同。如果是new XWPFDocument()直接创建的文档，sectPr是空白的，你 addNew 就完了；但如果是从模板复制的文档，原来的sectPr可能已经带了一堆默认值，这时改节点的值就行，千万别再addNew一个，否则会把旧的覆盖掉或者产生重复节点。

// 推荐写法：先判断再复用，避免覆盖已有设置 CTPageMar pageMargin = sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar();

这个模式我在整个项目里一直复用，稳妥不出问题。

4. 实战：一个完整页面配置的落地过程

4.1 完整代码实现（含注释）

纸上谈兵没意思，直接上一个我实际项目里用的完整片段，生成一份 A4 纵向、标准边距、带标题内容的文档：

import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; import org.apache.poi.xwpf.usermodel.XWPFRun; import org.openxmlformats.schemas.wordprocessingml.x2006.main.*; import java.io.FileOutputStream; public class WordPageSetupDemo { public static void main(String[] args) throws Exception { XWPFDocument doc = new XWPFDocument(); // 1. 获取或创建 body 级的 sectPr 节点 CTBody body = doc.getDocument().getBody(); CTSectPr sectPr = body.isSetSectPr() ? body.getSectPr() : body.addNewSectPr(); // 2. 纸张设置：A4 纵向 CTPageSz pageSize = sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(11906); pageSize.setH(16838); pageSize.setOrient(STPageOrientation.PORTRAIT); // 3. 页边距设置：上下 2.54cm，左右 3.18cm，页眉 1.5cm，页脚 1.75cm CTPageMar pageMargin = sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar(); pageMargin.setTop(1440); pageMargin.setBottom(1440); pageMargin.setLeft(1800); pageMargin.setRight(1800); pageMargin.setHeader(851); pageMargin.setFooter(992); pageMargin.setGutter(0); // 4. 写入一段测试内容 XWPFParagraph paragraph = doc.createParagraph(); XWPFRun run = paragraph.createRun(); run.setText("页面设置测试：A4纵向，标准边距。"); run.setFontSize(12); // 5. 输出 try (FileOutputStream out = new FileOutputStream("page_setup_demo.docx")) { doc.write(out); } doc.close(); System.out.println("生成完成"); } }

这段代码放到项目里能直接跑。注意一点：POI 的doc.close()一定要调用，否则文件流可能没有完全 flush，生成出来的文件会损坏，这也是很多人“导出后打不开”的原因之一。

4.2 动态参数设计思路（面向业务场景）

实际业务里，页面设置经常是用户可选的。比如后台管理系统里有个“导出设置”弹窗，让用户选纸张大小、方向、边距。这时页面设置的代码就不要写死，而是封装成方法。

我一般这样设计一个参数类：

public class PageConfig { private int pageWidth; // twips private int pageHeight; // twips private STPageOrientation.Enum orientation; private int topMargin; private int bottomMargin; private int leftMargin; private int rightMargin; // getter/setter 省略 }

然后把 apply 方法写成一个工具：

public static void applyPageConfig(XWPFDocument doc, PageConfig config) { CTBody body = doc.getDocument().getBody(); CTSectPr sectPr = body.isSetSectPr() ? body.getSectPr() : body.addNewSectPr(); CTPageSz pageSize = sectPr.isSetPgSz() ? sectPr.getPgSz() : sectPr.addNewPgSz(); pageSize.setW(config.getPageWidth()); pageSize.setH(config.getPageHeight()); pageSize.setOrient(config.getOrientation()); CTPageMar margin = sectPr.isSetPgMar() ? sectPr.getPgMar() : sectPr.addNewPgMar(); margin.setTop(config.getTopMargin()); margin.setBottom(config.getBottomMargin()); margin.setLeft(config.getLeftMargin()); margin.setRight(config.getRightMargin()); }

前端传规格，后端算缇值，应用层只调工具方法，这样代码结构清晰，后面加新纸张类型也不至于改逻辑。

4.3 批量生成多章节文档时的节属性处理

批量生成的时候，有个大坑躲不开：一个 Word 文档可以有多个节，每一节都有自己的页面设置。比如前面几页是纵向的正文，中间插一张横向的宽表格，最后又回到纵向。Word 文档的节属性并不是只存在 body 的 sectPr 里，而是存在每一节的最后一个段落属性中，body 级的 sectPr 只代表最后一节。

POI 里遍历所有节的代码如下：

for (XWPFParagraph paragraph : doc.getParagraphs()) { CTPPr ppr = paragraph.getCTP().getPPr(); if (ppr != null && ppr.isSetSectPr()) { CTSectPr sectPr = ppr.getSectPr(); // 修改这一节的页面设置 } }

这个方法我在生成混合版式文档时验证过。如果项目只需要全文档统一页面设置，操作 body 的 sectPr 就够；但一旦有分节需求，只改 body 级就覆盖不全。区分这两层的关系，可以省下不少排查时间。干脆说透：你可以把 body 级 sectPr 理解为“兜底设置”，所有节属性加载不出来时用它，而段落里存的节属性是“专用设置”，优先级更高。

5. 常见问题与避坑实录

5.1 问题速查表

我把自己和别人踩过的坑整理成了表格，方便你直接对照排查：

5.2 设置不生效的三种典型原因

页面设置不生效，绝大多数逃不出这三种情况。

第一种是节点层级找错。比如你在段落里改了那个段落自己的 section 属性，但目标页面实际由另一个节控制。说白了，一个文档 5 个分节符，你只改了第 1 节，后面 4 节还是原来的样子。这种情况下“设置没生效”其实只是“没改到该改的地方”。

第二种是属性重复。模板文档里已经有一份 sectPr，代码又addNewSectPr()创建了一个新的，两个节点互相打架，哪个生效全看解析器心情。我之前就遇到过，模板里本身带着 A4 设置，代码一看 body 没有？其实有，只是藏得深。用isSetSectPr()判断后再决定取值还是新建，就不会出这种问题。

第三种是单位混淆。把毫米当成缇传入，一页能塞下几百行内容；把缇当成厘米，又会出现惊人的大边距。我建议在项目里写一个统一的单位换算常量类，避免每个人各写各的。

public final class UnitUtils { private UnitUtils() {} /** 厘米转 twips */ public static int cmToTwips(double cm) { return (int) Math.round(cm / 2.54 * 1440); } /** 毫米转 twips */ public static int mmToTwips(double mm) { return (int) Math.round(mm / 25.4 * 1440); } /** 磅转 twips */ public static int pointToTwips(double pt) { return (int) Math.round(pt * 20); } }

5.3 版本兼容与依赖问题

POI 版本升级带来的 API 变化也要注意。5.2.2 之前的 4.x 时代，操作 OOXML 底层类需要单独引入ooxml-schemas或者poi-ooxml-schemas。到了 5.x，这货变成了poi-ooxml-lite和poi-ooxml-full，缺类时就换 full。5.2.2 默认传递的是 lite 包，常规的 CTPageSz、CTPageMar 都有，但你要是想操作某些冷门节点，比如CTDocGrid、CTTextDirection，lite 包没有就得换成 full 或者直接加依赖。

<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml-full</artifactId> <version>5.2.2</version> </dependency>

还有一个小概率问题：项目里同时存在 poi 的多个版本，互相冲突，导致某些类实际加载的是老版本。排查方法很简单，看报错堆栈里的包名，是ooxml-schemas还是poi-ooxml-lite，就能判断实际加载的是哪一套依赖。

6. 扩展：POI 操作 Word 的其他高频场景补充

6.1 表格与页面设置的关系

页面设置搞定之后，紧跟着的几个高频需求都和表格有关。比如设置 Word 表格的单元格宽度，很多人搞了半天发现列宽拖动不了，其实根源在于表格的tblLayout属性是固定布局，还可能有tblW和单元格的tcW值冲突。

页面边距直接决定表格最大可用宽度：可用宽度 = 纸张宽度 - 左边距 - 右边距。比如 A4 纵向，页面宽 11906 twips，左右边距各 1800 twips，表格最大宽度就是 8306 twips。设计表格时，如果列宽总和超过了这个值，打印出来表格边缘就会被裁掉或自动换行，表现得很奇怪。

6.2 生成 Word 时与页眉页脚、样式的联动

页面设置除了纸张和边距，还关联页眉页脚的距离和奇偶页不同设置。POI 里通过XWPFHeaderFooterPolicy操作页眉页脚内容，但要保证页眉页脚不盖住正文，核心还是把header和top的距离搭配好。如果页眉距边界设置得比上边距还大，页眉内容就会掉进正文区，打印出来叠字，这个问题肉眼很难发现，只能靠计算提前规避。

6.3 与其他工具链的结合

最近很多人在做 Markdown 转 Word 的工作流，核心步骤其实也是页面设置的初始化。工具先用代码生成一份标准模板 docx，把纸张边距调好，再把 Markdown 转换出来的内容按顺序追加进去。我实操下来发现，用 POI 做底层生成，配合前端预览组件，可以做到“所见即所得”的效果。比如设置好页面后，用 pdf 渲染服务把 docx 转成 PDF 预览，用户看到的就是最终打印效果，再也不用等打印出来才发现问题。

还有一点值得提醒：有些在线文档工具导出的 docx 并不规范，sectPr 可能缺失或者只有很简陋的配置。拿这些文件当模板时，一定要先检查节点结构，别直接拿过来跑。稳妥的做法是在代码里统一走一遍“模板清洗 + 页面设置覆盖”的逻辑，确保最终文档的样式是可控的。

我个人在实际操作中的体会是，POI 操作 Word 页面设置这件事，难度不在 API 本身，而在对 OpenXML 结构的理解和对单位换算的敏感度。这两个点一旦打通，后面无论是做批量导出、模板填充还是复杂版式，都会顺手很多。另外还是要再强调一下，每次生成完文件，最好解压看一眼 document.xml 的 sectPr 节点，确认数据真的写对了再交付——这个习惯帮我避免了至少五次返工。