简介：这份 paged.js 教程资料包面向具备一定 JavaScript 基础的前端开发者，以及需要把 HTML 内容稳定输出为 PDF 的技术人员，重点解决浏览器端分页排版、打印样式适配和文档生成流程中的实际问题。教程围绕 CSS Paged Media 展开，涉及核心概念、安装引入、基础示例、页面尺寸与边距设置、复杂布局处理、PDF 输出、框架集成及调试优化等主题，并关注分页断点、打印媒体查询等细节，适合作为理解分页机制和定制打印样式的参考，也可为文档导出工具选型做技术预研。压缩包共 32401 个文件，整体约 40.16MB，包含大量 png 图示、js 脚本、otf/eot/woff/ttf 字体资源，以及 html、svg、txt、md、json 等配套文件，可用于对照阅读、查看示例结构和本地运行验证。目录组织清晰，便于按主题检索。已有 586 人学习，可作为前端文档导出、在线报告生成与 PDF 分页排版的实用资料。

1. 把 HTML 排成带页码的书：这份 Paged.js 教程卡在哪个位置

手上有一批结构规整的 HTML 文档，要输出成带页码、页眉、目录、脚注的 PDF。第一反应通常是开 Word，改版式改到怀疑人生；或者上 LaTeX，学习成本够写两个项目。这份以 PDF 形式整理的 Paged.js 教程给的是中间路线：用 CSS Paged Media 那套声明式规则描述版面，由一段 JavaScript 在浏览器里把长文档真正切成一张张页面盒，再从浏览器打印成 PDF。

它适合已经在用 Web 技术栈产出文档、又不想把排版交给桌面软件的人；也适合想搞清楚“分页到底发生在哪一层”的前端。看完能拿到的最小闭环是：一页 A4、页码正确、目录页码能自动回填、导出不跑版。

2. 分页发生在哪一层：Polisher、Chunker 与页面盒的三角关系

2.1 浏览器不实现的 CSS Paged Media，被谁补上了

浏览器对 CSS Paged Media 的支持少得可怜。@page里的size和margin在打印时大致能生效，但@top-center、@bottom-right这些 margin box，以及counter(pages)、target-counter()、float: footnote，主流浏览器基本一个都没实现。Paged.js 是补这一层的库：它不是把页面截图，而是真的操作 DOM，把源内容按渲染高度切成若干.pagedjs_page，每个页面盒里再挂.pagedjs_sheet、内容区.pagedjs_page_content、以及一圈 margin box 容器。

内部有三个环节值得记住名字，因为排错时全靠它们定位。Polisher 负责处理样式表，把@page规则抽出来，转成能作用在页面盒上的 CSS；Chunker 负责切分，它测量每个块级元素的实际高度，累加到超过版心高度就断开，生成 breakToken 继续下一页；Previewer 串起整个流程并在不同阶段抛出事件钩子。样式明明写了却没生效，先去 Polisher 处理后的 CSS 里找；切页位置莫名其妙，去看 Chunker 量到的高度；页码是空的，那是 margin box 填充阶段的事。三层分开看，比在一堆.pagedjs_*类名里瞎猜快得多。

这套做法有一个明确的天花板：DOM 是真的被切开了。任何依赖“整体连续”的视觉效果，在切口处都会断，比如带圆角和阴影的卡片被劈成两半、跨页的竖线断掉、box-shadow在下半页被裁掉。这不是 bug，是这套方案的物理边界。接受不了就只能改写内容结构，把不可分割的东西包进break-inside: avoid的容器里。

2.2 最小工程：装包、引 polyfill、写出第一个 @page

先把依赖装上。pagedjs这个包会带出dist/paged.polyfill.js，把它引到页面里就会自动接管分页，不需要写任何初始化代码。

# 只做本地排版验证的话，一个静态服务就够，不用上构建工具 npm init -y npm install pagedjs npx serve .

然后是页面骨架。下面这份可以直接跑，注意@page的写法和普通 CSS 是同一套语法，只是规则名不同。

<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <!-- polyfill 必须在样式之前引，它会在 DOM 就绪后接管分页 --> <script src="./node_modules/pagedjs/dist/paged.polyfill.js"></script> <style> /* 纸张尺寸与版心，印刷场景一律用 mm，别用 px */ @page { size: A4; margin: 22mm 18mm 20mm 18mm; /* 上 右 下 左 */ } /* 同一个 @page 可以重复声明，规则会合并 */ @page { @bottom-center { content: counter(page) " / " counter(pages); font-size: 9pt; color: #666; } } body { font-family: "Noto Serif CJK SC", "Songti SC", serif; font-size: 11pt; line-height: 1.75; } h1 { font-size: 20pt; margin: 0 0 6mm; } p { margin: 0 0 3mm; text-align: justify; } /* 屏幕预览时给页面盒一点间隔，方便肉眼确认切页位置； 写进 @media screen，避免影响打印 */ @media screen { body { background: #f2f2f2; margin: 0; } .pagedjs_page { margin: 12px auto; box-shadow: 0 1px 4px rgba(0,0,0,.18); } } </style> </head> <body> <article> <h1 id="cover">模拟项目X 技术手册</h1> <p>第一段正文。把要做成书的 HTML 直接放进来就行，不需要额外的包装层。</p> <p>第二段正文。分页由 polyfill 自动完成，屏幕上会看到一张张独立的纸。</p> </article> </body> </html>

这里有几个参数必须说清楚。size: A4决定页面盒的宽高，如果打印对话框里又选了别的纸型，两边会打架，导出必翻车，所以后面接自动化时要用preferCSSPageSize把它固定住。margin是版心位置，顺序是上右下左，页眉页脚就长在这块留白里，所以想要页眉不挤正文，靠的是调margin-top，不是在正文里加 padding。counter(page)是当前页码，counter(pages)是总页数，后者由 Paged.js 统计完所有页面盒之后回填，屏幕上第一眼看到的可能是空值，等它排完就有了。

提示：@page规则写在任意<style>或外链 CSS 里都行，但要保证它和正文样式在同一份文档里，跨 iframe 引入的样式表的@page不一定被 Polisher 抓到。

2.3 目录页码回填：target-counter 与 leader 的组合

目录页码是这类工具最容易让人眼前一亮的功能，写法却很简单：给目录项一个指向目标的锚点，然后用target-counter把目标所在页码取出来当伪元素内容。

/* 目录项：不要下划线，右侧自动补点线再跟页码 */ .toc a { text-decoration: none; color: inherit; } .toc a::after { /* leader() 生成填充点线，target-counter 取目标元素所在页码 */ content: leader('.') target-counter(attr(href), page); font-variant-numeric: tabular-nums; /* 页码等宽，右侧才对齐 */ } /* 目录单独占页，别和正文挤在一起 */ .toc { break-after: page; }

对应的 HTML 只需要保证href是同文档锚点、目标元素有id：

<nav class="toc"> <ul> <li><a href="#ch1">第 1 章 环境与依赖</a></li> <li><a href="#ch2">第 2 章 版式参数</a></li> </ul> </nav> <article> <h1 id="ch1">第 1 章 环境与依赖</h1> <!-- ... --> <h1 id="ch2">第 2 章 版式参数</h1> <!-- ... --> </article>

参数上要注意两点。attr(href)拿到的是完整字符串（含#），target-counter内部会自己解析成元素引用，所以href="#ch1"就够了，别写成绝对 URL。如果你还想让目录里显示标题文字而不是手写，把content换成target-text(attr(href))就能取到目标元素的文本，代价是层级和样式全靠::before/::after拼，多级目录反而更麻烦，我一般还是手写标题、只让页码自动回填。

target-counter取不到值的时候不会报错，只会静默留空。第一次用很容易以为自己写错了选择器，其实是锚点没对上。排查顺序固定成三步：href和id是否严格一致、目标元素是否在分页流里（被display: none藏掉的内容不算）、::after是否被更高优先级的选择器覆盖。

3. 版式参数怎么设：@page 规则、命名页面与页眉页脚

3.1 @page 里真正会影响成品的六个参数

@page能写的东西不少，但决定成品长相的就那么几个。下面这张表是我反复改样式之后沉淀下来的，左边是参数，右边是容易写错的地方。

关于bleed和裁切线，说句实话：走浏览器打印这条链路时，出血很难做干净，因为打印对话框本身还会缩放。需要严格出血的项目，通常的做法是先用 Paged.js 排出内容页，再交给专业的拼版工具加出血和爬升。这不是 Paged.js 的短板，是浏览器打印模型的限制。

3.2 命名页面：封面、正文、附录各用一套版心

一本书里不同部分的版式往往不同：封面满版不留白，正文双栏带页眉，附录单栏不要页码。做法是定义多个命名@page，再用元素上的page属性去绑定。

/* 封面：零边距，满版 */ @page cover { margin: 0; @bottom-center { content: none; } /* 封面不要页码 */ } /* 每章起始页：不显示页眉，让标题更醒目 */ @page chapterStart { @top-center { content: none; } } /* 附录：页码改罗马数字 */ @page appendix { @bottom-center { content: counter(page, lower-roman); } } /* 绑定：page 属性写在容器上 */ .cover { page: cover; break-after: page; } .chapter { page: chapterStart; break-before: page; } .appendix { page: appendix; break-before: right; }

这里有个语义细节经常被误解：page属性影响的是元素起始的那一页。一个章节容器如果跨了 6 页，只有第一页套用chapterStart，后面 5 页回落到默认@page。很多人以为会一路继承下去，然后发现“第二章的页眉怎么又冒出来了”，其实行为一直是对的。要让整章都不显示页眉，得把页眉的开关做到@page级别而不是单页级别，或者接受“章首页特殊、正文页统一”这个更常见的排版惯例。

break-before: right也值得单独说。它要求新内容从右手页开始，如果当前正好停在右手页，就会插入一张空白页。双面印刷这是标准做法，但在屏幕上翻 PDF 时看到空白页别急着当 bug 修，先确认是不是right在起作用。

3.3 页眉内容从哪来：string-set 取文本，running element 取整块

页眉最常见需求是“显示当前章节标题”。两种实现路线，差别不小。

第一种用string-set，它从元素里取文本，存成一个命名字符串，margin box 再用string()取出来。

/* 把每个 h1 的文本存进 chaptertitle 这个字符串变量 */ h1 { string-set: chaptertitle content(text); } @page { @top-right { content: string(chaptertitle); font-size: 9pt; color: #555; } }

第二种用 running element，把一整块 DOM 搬到页眉里，能带 logo、能带双色文字。

<div class="running-head"> 模拟项目X 技术手册 <span class="ver">内部版</span> </div>

.running-head { position: running(dochead); /* 从正文流里移除，交给页眉引用 */ } @page { @top-left { content: element(dochead); font-size: 9pt; } }

怎么选？页眉只有一行纯文字，用string-set，它有“当前页对应的章节”这个语义，跨页时取哪一页的值由第二个参数控制；页眉需要排版自由度（图标、分隔线、左右分区），用 running element，但它本质是把同一个 DOM 节点搬来搬去，同一个 running element 被多处引用时行为会变得难以预测。

string()的第二个参数，CSS 规范里给了first、start、last几种取法，用来解决“标题落在上一页底部、正文在下一页，页眉该显示谁”的问题。实际用的时候，先在目标版本上把几种取法都跑一遍，看哪个符合你的排版习惯，别默认它们全都实现得一样。我吃过这个亏：本地看着对，换一个渲染环境页眉就变成了上一章的标题，最后靠start才稳住。

4. 长文档的四件硬活：目录、脚注、交叉引用、断页控制

4.1 多级目录：层级、点线与章节起始页

单级目录用 2.3 的写法就够了，真正做手册时目录一般有三级。层级不要靠缩进硬撑，用类名控制，样式和结构分开。

.toc ul { list-style: none; padding: 0; margin: 0; } .toc li { margin: 0 0 1.6mm; font-size: 10.5pt; } /* 三级缩进，用 em 跟着字号走，换字号不用改数值 */ .toc .lv2 { padding-left: 1.6em; font-size: 10pt; } .toc .lv3 { padding-left: 3.2em; font-size: 9.5pt; } /* 只有一级目录加粗，二级三级保持克制 */ .toc .lv1 { font-weight: 600; margin-top: 3mm; } /* 点线和页码对所有层级统一 */ .toc a::after { content: leader('.') target-counter(attr(href), page); }

<nav class="toc"> <ul> <li class="lv1"><a href="#ch1">第 1 章 环境与依赖</a></li> <li class="lv2"><a href="#sec11">1.1 依赖安装</a></li> <li class="lv2"><a href="#sec12">1.2 目录结构</a></li> <li class="lv1"><a href="#ch2">第 2 章 版式参数</a></li> </ul> </nav>

leader('.')的行为是把剩余空间用点填满，所以目录项本身必须是块级或 flex 撑满宽度，否则点线会挤在文字后面。如果发现点线长度忽长忽短，八成是某个li被设成了inline-block。

还有一个隐藏问题：目录本身页数不定。三页的目录如果只留了一页的位置，后面会挤掉正文的第一页，页码全部错位。给目录容器加break-after: page是必须的，同时目录项不要用break-inside: avoid，否则一页放不下时会推走一大块，中间留白。

4.2 脚注：float: footnote 和 @footnote 区域

脚注是 Paged.js 相对亮眼的功能。写法是把脚注内容直接放在正文引用处，用float: footnote抽走。

<p> 这段正文里有一个需要说明的点<span class="fn">这里的数值来自模拟项目X 的内部测试记录，仅作示例。</span>，后面继续。 </p>

/* 脚注本体：从正文流里抽走，落到本页的脚注区 */ .fn { float: footnote; font-size: 8.5pt; line-height: 1.5; } /* 正文里的上标编号 */ ::footnote-call { content: counter(footnote); vertical-align: super; font-size: 70%; line-height: 0; } /* 脚注区里的编号，注意带了点号 */ ::footnote-marker { content: counter(footnote) ". "; } /* 脚注区与正文之间的分隔线，写在页面级 */ @page { @footnote { border-top: 0.5pt solid #999; padding-top: 3mm; margin-top: 6mm; } }

参数上有三点。counter(footnote)是 Paged.js 自己维护的，不用手动编号，但要注意它默认整篇连续编号；想要每页重编，得在页面上重置计数器，这块各版本行为不完全一致，改之前先小样本验证。脚注内容必须写在正文流的引用位置，不要用 JS 事后插入，因为切页是在 DOM 就绪后立刻发生的，后插入的节点赶不上这一轮布局。脚注区高度是参与版心计算的，一条长脚注会挤掉正文行数，所以脚注尽量控制在两行以内，超过就改成尾注。

还有一个现实约束：脚注挤不下时，Paged.js 会把整段正文推到下一页，而不是把脚注截断。这意味着一个段落如果特别长（比如一整页不分段），脚注永远找不到落点。正文块保持正常分段，这个问题基本不会出现。

4.3 断页控制：break-* 与 orphans/widows 的实际效果

排版质量的差距，八成在断页控制上。默认行为是“能塞就塞”，标题孤零零留在页底、段落最后一行单独跑到下一页，都是常见画面。

/* 标题后面不许断，避免标题落在页底 */ h1, h2, h3 { break-after: avoid; } /* 标题前面也不许断，避免标题跑到新页第一行却和上文割裂 */ h1, h2, h3 { break-before: avoid; } /* 段落：至少留 3 行在页底，至少 3 行带到下一页 */ p { orphans: 3; widows: 3; } /* 图表、代码块、引用块整体不拆 */ figure, pre, blockquote, .callout { break-inside: avoid; } /* 表格允许跨页，但单行不许劈开，表头每页重复 */ table { break-inside: auto; } tr { break-inside: avoid; } thead { display: table-header-group; } /* 章节从新页开始，附录从右手页开始 */ .chapter { break-before: page; } .appendix { break-before: right; }

orphans和widows是最容易被忽略的两个属性，因为它们在其他地方几乎用不到。前者控制页底最少留几行，后者控制页顶最少带几行，值一般设 2 到 3。设成 1 等于关掉保护，设成 4 以上在中文字号下会导致大量半空页，得不偿失。

break-inside: avoid不能滥用。给一个 800px 高的卡片加这条，它会整个被推到下一页，上一页留下大片空白；给嵌套容器同时加，可能出现“谁都不让谁”，最终整块溢出。经验做法是只在高度可控的元素上加（图、代码块、提示框），并且加之前先想清楚：这块东西如果真的有 1.5 页高，避断反而是灾难。

5. 五个翻车现场：空白页、页码错位、字体竞态、表头丢失、二次分页

5.1 章节之间凭空多出一张空白页

现象：导出的 PDF 里，某些章节之间夹着一张完全空白的页，屏幕上也能看到。

原因基本是两个。一是断页在两侧同时声明：上一章的容器写了break-after: page，下一章的容器又写了break-before: page，两次强制断页叠加，中间那张就是产物。二是元素高度刚好等于或略大于版心高度，浮点误差让 Chunker 判定“放不下”，于是推到下一页，而它本身几乎没有内容，看起来就是空白。

解决：断页只在一侧声明，统一写在章节容器的break-before上，把break-after全删掉。定位时打开控制台数一下document.querySelectorAll('.pagedjs_page').length，跟预期页数对不上，再逐段二分注释掉break-*规则，通常十分钟内能锁定。我现在的习惯是所有断页规则集中写在一个区块里，注释标明“只允许单侧声明”，就是被这个坑教育出来的。

5.2 正文第一页显示成第 2 页

现象：封面不显示页码，但正文第一页的页脚写着“2 / 48”，全篇页码整体偏移一位。

原因：封面也在分页流里，占用了counter(page) = 1。你只是把封面的页码隐藏了（content: none），计数器并没有归零。

解决：两个方向。CSS 方向是在正文起始元素上加counter-reset: page 1，让计数器从这里重算，但这是 Paged.js 的扩展行为，不是所有环境都稳，上生产前必须实测。工程方向更保险：封面单独渲染一次，正文单独渲染一次，最后在 PDF 层合并，页码天然从 1 开始。项目里做正式交付物时我倾向后者，虽然多一步，但不用赌渲染器的实现细节。

顺带一提，前言用罗马数字、正文用阿拉伯数字这种需求，做法是把前言和正文拆成两个命名页面，各自counter(page, lower-roman)和counter(page)，再把counter-reset放在两段的交界处。复杂归复杂，但这是唯一能同时满足两种编号体系的路子。

5.3 字体和图片没加载完就开始切页

现象：导出的 PDF 和屏幕上看到的完全是两份东西，行高变了、每行字数变了、末尾多出好几页；或者图片位置全错，后面内容整体上移。

原因：Paged.js 在 DOM 就绪后立刻开始切页，此时 Web 字体还在下载，浏览器先用 fallback 字体渲染，Chunker 量到的高度是错的。字体替换完成之后每行能塞的字数变化，整篇需要重排，但分页已经结束。图片同理，没写死尺寸的<img>初始高度接近 0，加载完撑开，后面的分页全废。

解决：给所有图片写死width/height或aspect-ratio，让它在加载前就占好位置；把分页推迟到字体和图片都就绪之后，具体做法在 6.1 给代码。字体这块还有一个隐性成本：中文字体动辄几 MB，用font-display: swap会让首屏更快但排版更不稳，做 PDF 输出时反而应该用font-display: block，宁可等一会儿也别让它换字。

5.4 长表格翻页后表头不见了

现象：跨页的表格，第二页开始只有数据行，读者对不上哪列是什么。

原因：thead没有声明为table-header-group。默认的table-header-group是浏览器给的，但在分页场景下需要显式写出来，让切页逻辑知道“这一段每页都要重复”。另一种情况是表格上加了break-inside: avoid，整块被推到下一页，虽然表头在，但上一页留下半页空白，视觉上更难看。

解决：thead { display: table-header-group; }，tr { break-inside: avoid; }保证单行不被劈开，把表格上的break-inside: avoid去掉。如果表格有tfoot做合计行，同样处理。另外表格列宽尽量用table-layout: fixed加百分比，自动列宽在跨页时可能因为内容分布变化而重算，导致前后两页列宽不一致。

5.5 打印预览比屏幕多出几页

现象：屏幕上数出来 40 页，Ctrl+P 预览变成 43 页，或者每页底部内容被裁掉一截。

原因：二次分页。Paged.js 已经把内容切成了固定高度的页面盒，浏览器打印时又按自己的@page规则分了一次，两套规则打架。另一种是page.pdf()里还带着 margin，和 CSS 里的margin叠加，版心被压小。

解决：打印媒介下把@page的margin归零，因为版心边距已经由页面盒自己承担了；headless 打印时用preferCSSPageSize: true让渲染器服从 CSS 里的size，同时把margin全部设成 0；printBackground: true一定要开，否则页眉线、底纹、边框全部消失，看起来像样式丢了。

注意：不要用浏览器的“另存为 PDF”做最终交付，它受用户本机纸型、缩放比例、页眉页脚开关影响，同一份文件在不同机器上能出不同结果。要么走 headless，要么在页面里显式提示用户把页边距选“无”、缩放选“默认”。

6. 接进自动化：等对完成信号，再做版式回归

6.1 headless 打印：auto:false 加一个显式完成标记

自动分页最大的问题是“什么时候算排完了”没有标准答案。稳妥做法是关掉自动执行，手动触发，并在after回调里打一个标记，外部等这个标记。

// print.js —— 用 Playwright 驱动已经接好 Paged.js 的页面 const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const page = await browser.newPage(); // 关键：关掉 auto，改成手动触发，否则拿不到"排完"这个时刻 await page.addInitScript(() => { window.PagedConfig = { auto: false, after: (flow) => { window.__pagedReady = true; window.__pagedTotal = flow.total; // 总页数，后面做回归断言用 }, }; }); await page.goto('http://localhost:8080/manual.html', { waitUntil: 'load' }); // 字体是异步的，等它落地再切页，否则行高全错 await page.evaluate(async () => { await document.fonts.ready; await window.PagedPolyfill.preview(); }); await page.waitForFunction(() => window.__pagedReady === true, { timeout: 60000 }); await page.pdf({ path: 'out.pdf', preferCSSPageSize: true, // 服从 CSS 的 @page size，别让渲染器再猜 printBackground: true, // 页眉线、底纹、边框全靠它 margin: { top: '0', right: '0', bottom: '0', left: '0' }, // 版心边距已在 CSS 里，别叠加 }); await browser.close(); })();

document.fonts.ready是这一段的重点，它返回一个 Promise，字体全部就绪才 resolve。waitForFunction的超时要给足，中文长文档加上几 MB 字体，一分钟并不夸张。flow.total来自after回调，是 Paged.js 统计出的总页数，比自己去数 DOM 节点可靠。

6.2 把页数和关键页文本变成断言

版式回归不需要图像比对，太脆。页数加关键页文本这两条断言，能挡住 90% 的样式事故。

// 改完样式跑一遍，页数或关键页内容变了就先看 diff const total = await page.evaluate(() => window.__pagedTotal); const page5 = await page.evaluate(() => document.querySelectorAll('.pagedjs_page')[4].innerText.slice(0, 40) ); if (total !== 42) { throw new Error(`页数从 42 变成 ${total}，先查字体加载和 break 规则`); } if (!page5.includes('第 3 章')) { throw new Error(`第 5 页内容异常：${page5}`); }

页数变了不一定是坏事，但一定意味着有东西动了，可能是字体换了、可能是断页规则改了、也可能是某个图片没加载出来。把它当红灯，逼自己每次改完样式都跑一遍，比事后发现交付物错版强太多。

我现在的固定动作是：改完任何一条@page或break-*规则，先跑 6.1 的脚本出一份 PDF，肉眼扫一遍页眉页脚，再跑 6.2 的断言，两条都过才算完。这套流程是从一次交付前夜发现全篇页码偏移一位开始养成的，那次通宵重排的教训太贵。那份 PDF 教程我一般不开着通读，当成属性索引放在手边，遇到string()的取值或者@footnote的写法再翻，效率比从头看高得多。希望帮到你。

本文还有配套的精品资源，点击获取