XSL-FO从入门到落地：XML数据如何自动排版生成专业PDF

面向电子出版的老兵和新手：我把XSL-FO从入门到落地一次讲透。

先自我介绍下背景，我在排版和文档自动化这条线上干了十多年，早期做书刊排版系统，后来转到数据驱动的文档生成。这些年折腾过HTML转PDF、Word模板批量出稿、LaTeX排版，最后项目里大量用到XSL-FO的场景，慢慢地从“这玩意儿是不是过时了”到“原来这才是批量排版的正道”。如果你经常需要把XML数据变成漂亮的PDF，或者做的项目涉及大量文档自动排版、电子出版、可变数据印刷，那这篇内容应该能帮你省掉不少弯路。

XSL-FO，全称XSL Formatting Objects，是W3C制定的一套面向打印和页面布局的XML标记语言。简单说，它做的就是一件事：把结构化的内容变成“带页码、带页眉页脚、分栏、带目录索引、保证版面精确”的成品PDF。和HTML+CSS的思路不同，XSL-FO从诞生那天起就不是给屏幕浏览用的，它是为“页面”而生的。

要理解XSL-FO为什么能扛起大规模排版的重任，得先纠正一个常见的误解：很多人以为XSL-FO是一个软件，其实它是一个规范。规范的实现者是一大堆商业和开源工具，而“XSL-FO软件”这个名字，更像是在指代整个生态里那些能把FO文档渲染成PDF的引擎和配套工具链。这篇文章我就围绕“软件”展开，聊聊这些工具之间的差异、选型逻辑，以及我实际跑项目时踩过的各种怪坑。

1. 为什么到今天还要用XSL-FO：它解决的不是“好看”而是“可控”

现在做PDF的方法很多，最常见的是Chrome打开HTML然后打印成PDF，或者用Puppeteer、wkhtmltopdf这类无头浏览器工具。说实话，我自己早期也这么干过，省事，页面效果所见即所得。但搞过几十上百页的标书、手册、产品目录之后，你会发现这条路走不通。问题集中在几个点上：页码和页眉页脚的精细控制、目录页码的动态计算、跨页表格的重复表头、页面左右页不同的边距设置。这些需求不是“能不能实现”的问题，而是“批量生产时能不能稳定复现”的问题。HTML+CSS在屏幕上的弹性布局思路，到了分页媒体上，总有各种微妙的差异。Chrome的打印引擎确实做了不少支持，但遇到严格的PDF/A归档要求、专业印刷厂对出血位和标记的要求时，它仍然不够专业。

XSL-FO的路子完全不同。它从设计上就把内容流（flow）和页面模板（page master）分开。你把一段文本丢进一个区域，引擎会自动决定哪些内容落到第几页，哪个位置使用哪套页眉。整个过程不是“模拟打印”，而是“原生印刷级排版”。这就像一个电视节目录制和电影拍摄的区别。前者镜头跟着内容走，后者所有镜头都要按照剧本和分镜表来执行，不允许临场发挥。对于需要精确到毫米级的版面，XSL-FO这种严格规划的模型才是稳妥的。

另一个容易忽略的点是“内容与样式分离”的工程意义。在XSL-FO项目里，内容通常在XML里维护，样式由XSLT样式表控制，页面模板和布局属性被封装成FO片段。三者解耦后，内容编辑改稿子时不需要碰代码，排版同事调整样式时也不会误伤正文。这种分工在团队协作里价值极大，尤其是内容生产方和技术提供方不是一个团队的时候。

所以哪些项目还在用XSL-FO？据我观察，行业里主要集中在：出版社的图书自动排版系统、标准化组织（比如各种行业标准的PDF生成）、制造业的产品手册和多语言文档、金融和法律行业的合规文件归档、票务账单等可变数据印刷。这些领域有一个共同特征：量大、格式要求严格、数据源是结构化内容而不是人手工排好的Word。如果你也是这类场景，XSL-FO是绕不开的选项。

2. 主流XSL-FO引擎的家族图谱与选型逻辑

XSL-FO不是只有一个软件，市面上主流的渲染引擎有好几个，各有各的脾气。我梳理了一个直观的对比表，方便你先建立整体认知。

2.1 Apache FOP：免费绕不开的首选项，但边界要心里有数

FOP是ASF旗下的开源项目，也是绝大多数人接触XSL-FO的第一站。它的优势是零成本、跨平台、文档多、社区活跃。我最初在项目里用的就是FOP 2.x系列。它对XSL-FO 1.1规范的支持足够覆盖大约八成的常规需求：页码、页眉、简单的目录、表格、页脚、静态内容，都能顺畅处理。

但是FOP的短板也很明显。它不支持一些XSL-FO 1.1里“建议实现”的高级特性，比如某些复杂的float布局、更为高级的text-decoration标准兼容细节、以及部分FO元素在个别场景下的边距合并行为。另外，它对于“中文排版”的很多细节，例如标点挤压、避头尾、强调点、混排对齐，基本不会自动处理。你必须通过设置标点相关的属性或者手动加空格来缓解。这意味着如果你的项目是图书级别的中文排版，FOP只能作为原型验证工具，不太可能直接扛起成品书生产。

还有一个容易踩的性能坑。FOP是Java编写的，默认配置下对大文档（超过几百页）的内存占用偏高。我有个跑标书生成的项目，一个FO文件就有将近百兆，默认JVM参数直接OutOfMemory，后面调整了堆内存和FOP的缓存策略才稳定下来。所以用FOP之前，先把JVM的-Xmx参数和对应用法想清楚，别等上生产了再临时抱佛脚。

2.2 RenderX XEP：性价比很高的商业备选

XEP是老牌的商业XSL-FO引擎，很多XML出版解决方案的后端都集成它。我接触它是因为一个客户要求生成PDF/A-1a级别的归档文件，FOP对PDF/A的支持总差那么一点火候，于是换成了XEP。体验下来，XEP对FO规范的实现相当完整，很多FOP处理不了的高级格式，它基本都能渲染，而且输出PDF的速度很快——同样一百多兆的FO文件，FOP可能要十几秒，XEP跑下来差不多只要一半时间。

许可费用上XEP不算便宜，不过相比它节省的人工调整和能应付的客户要求，性价比还是不错的。XEP还提供调用接口，支持Java、.NET环境下嵌入。如果你的团队主语言不是Java但又想集成渲染，XEP比FOP更友好，因为它在.NET侧也有原生接口。

2.3 Antenna House Formatter：处理中日韩排版的高手

Antenna House Formatter（简称AH Formatter）在专业的出版业界口碑极高。它的一个突出长处是CJK（中日韩）排版能力。内置了非常细致的标点压缩、禁则处理、行距调整规则，这一块是FOP无论怎么配置都很难追平的。日本很多电子书和PDF出版流水线就是以AH Formatter为核心，加上配套的XSLT样式表构成。

如果你不需要精细的中日韩排版，AH Formatter可能显得大材小用，价格也会让你肉疼。但反过来，如果你的团队做的是东亚语言的多语言文档项目，那么为这个需求多花的预算完全值得。

2.4 我在选型时实际考虑的三个维度

选引擎时我通常不会只盯“功能列表”，而是把这三个因素放在一起权衡：

第一，是“FO规范的贴合程度”，这在一些国际标准出版项目里是硬性要求。客户会拿规范的某个条款来验收，你用的引擎如果那一条不支持，整个项目就要推翻，这种风险要比性能问题严重得多。

第二，是“多语言支持”，尤其是中文和日文的排版细节。英文排版引擎基本跟着西方排版规则走，用词间距和连字符处理那一套逻辑处理东方文字，很容易出现标点悬挂到行首、全角字符间距异常这类问题。所以只要是内销中文内容的项目，我都会把CJK支持放在评估权重最靠前的位置。

第三，是“批量生产的性能和稳定性”。有些引擎单文档渲染很漂亮，但文档一多或者尺寸一大就出现内存泄漏、死锁，这种隐患在项目交付前往往测试不出来。我的经验是，选型前一定要拿三倍于常规体量的真实数据压测一次，别用那种只有五页纸的demo数据。

3. 从XML到PDF完整跑通：FO流水线里的每一步是怎么配合的

聊完引擎，接着讲整个链路。一个标准的XSL-FO生产流水线包含四个环节：准备XML数据、编写XSLT把XML转换成FO文档、调用FO引擎渲染为PDF、检查验证输出结果。这四个环节不是可有可无的顺序，而是环环相扣的依赖关系。

3.1 数据层：源XML的规范程度直接决定后面省不省心

很多项目最后夭折，不是XSL-FO不行，而是上游XML太乱。XML里的标签不规范、嵌套结构混乱、甚至同一份文档里中英文标签混用，到了写XSLT的时候就是灾难。做XSL-FO项目前，一定要先确定数据规范。我的实践是：列表用统一的item标签、段落不要往里面塞一堆自定义属性、时间日期一律用ISO格式等等。XML数据越干净，后面写模板效率就越高。

这里多说一点，源XML不应该只有内容，最好还带上一些“语义标签”。比如你有一段是摘要、有一段是关键词，不要都用“段落”表达，而应该用专门的语义标签。XSLT拿到带着语义标签的XML，才有可能生成一个结构清晰、带书签目录的PDF。没有语义标签的话，所有内容平铺，后期想自动生成书签和导航就无从下手。

3.2 模板层：用XSLT做“数据到版式”的翻译官

XSLT是整个流水线里最考验人的环节。它不只是一个简单的标签替换器，而是一个完备的树形结构转换语言。实际工作中，我经常用XSLT来回处理这些事：

• 按条件筛选数据。比如只把满足publication-status=‘final’的内容输出到PDF。
• 重组内容顺序。比如把XML里分散的参考文献统一收集到一起，再在正文引用位置插入对应的编号。
• 自动编号。章节序号、图表序号、公式编号，都可以在XSLT里通过position()这类函数实现。
• 把混合内容拆分到不同的FO区域。比如XML里的meta信息，一份同时输出成PDF页眉里的文档编号和metadata里的DOI。

XSLT版本方面，我的建议是能用XSLT 2.0就别死守1.0。2.0的group-by、正则、多文档处理能力能省掉大量绕路功夫。Saxon在XSLT 2.0/3.0上的支持度是标杆级的，很多场景里我会用Saxon把XML转成FO，再交由渲染引擎处理，分工非常清晰。

3.3 渲染层：FO文档里的页面对模板不再是闹着玩

FO文档本身是一个XML实例，它的根元素是fo:root。里面要声明一堆页面模板，然后定义内容流把这些模板填满。我意识到新手最容易晕的地方在于“页面模板”不是指一个具体的页面，而是一套“版式规则”。比如你可以定义“第一章首页”用A版式，没有页眉；定义“正文页”用B版式，带外侧页码；“空白页”用C版式，完全不加任何内容。引擎渲染时根据内容流程自动匹配这些版式。

实际写FO时，还有个高频操作是数据分页。FO里的分页不是靠插入分页符实现的，而是靠定义block的break-before属性：某个标题被指定break-before=“page”，它前面的内容就会被推到下一页。目录和页码也是FO特别强大的地方。你要在右侧栏放“第3章…12”这种点线引导，只需定义带leader和page-number-citation的块，页码由引擎自动计算。你可以想象成word里面的“自动目录域”，但FO模型里这项能力是标准和所有引擎的底层原生支持，不会一刷新就错乱。

3.4 FO引擎执行的产物：交付文件前至少检查这些点

PDF生成出来了不代表交付完成。我给自己定了一个固定检查清单：

1. 目录页码对不对。自动生成的目录页码在内容调整后可能错位，需要二次确认。
2. 书签层级是否完整。输出PDF的书签结构如果不一致，读者体验会受影响。
3. 嵌入字体是否正确。尤其是中文字体，没嵌入会导致其他设备显示错乱。
4. 超链接是否可用。交叉引用、URL跳转都要抽查一次。
5. PDF标签和可访问性属性是否保留。归档类的PDF通常有PDF/UA要求。

4. 我实际排错时最常遇到的FO坑位和解决策略

在这个领域待久了，很多问题我都碰到过不止一次。这里挑几个有代表性的，分享下这类问题的完整根因和分析方式，而不是只给结论。这些坑未必每个都叫“XSL-FO软件”的问题，更多是软件和业务之间的磨合问题。

4.1 莫名其妙的整页空白

有一次生成培训教材，隔几页就会出现一页空白。把FO片段导出来看，正文内容没有任何问题。后来逐行排查发现，某个章节的标题设了keep-with-next=“always”属性，意思是标题要和下一段保持同页；但下一页剩余空间不够放一个完整段落，所以标题被迫和自己一起挪到了再下一页，刚才那一页自然空出来一块。这个问题的根源是“完整的段落长度+标题长度”超过了页面剩余空间，导致一整个段落被推到下一页后，上一页末尾只剩下一个标题高度以内的空隙。看似是多了一个空白页，其实那一页并非完全空，而是底部有一小块无法利用的空白区域。类似问题的解法很简单：给标题加一个keep-together属性，或者调整页面底部空间，让剩余区域能多容纳几行字。别一碰到空白就怀疑引擎bug，大部分情况是keep约束和页面模板之间出现了“死锁”。

4.2 目录页码对不上，但FO里写的确实是“自动页码”

自动页码在FO里是很可靠的能力，但和真实场景结合时，坑常出在XSLT的阶段。我遇到的一次情况是：用的XSLT里做了两遍内容过滤，第一遍生成正文，第二遍生成目录。结果目录里的页码引用文本用的是第一遍FO里的id锚点，但那个锚点在第二次输出时id生成规则变了，导致引擎找不到目标，页码全部变成0。排查时打开PDF发现正文每个章节开头其实都有锚点，只是id是“chapter1”，而目录里引用的却是“sec_Chapter_001”，自然匹配不上。这类问题通用解法是让目录生成和正文生成使用同一套数据源、同一个id分配逻辑。最稳妥的做法是先归并XSLT输出，让目录和正文在同一次转换中完成。

4.3 中文长文档输出后标点悬挂难看到爆炸

这也是中文出版场景里最常见的吐槽。FOP在没有额外配置时，中文标点（句号、逗号、引号等）在行尾的处理方式往往不符合中文排版习惯，结果出现一行结尾是半个引号撇出去，或者下一行开头是句号，视觉上非常难受。解决思路分三层。

第一层，在FO样式表里给相关块设置“text-align: justify”之外启用中文排版属性，如果引擎支持的话。AH Formatter有很多专用的中文排版属性，FOP则需要你检查版本和扩展实现。

第二层，可以在XSLT处理时预先做标点保护，比如用零宽不换行字符，把不该断行的标点和前一个字符绑在一起。

第三层，从源内容上规避，对于脚注序号和冒号这类容易单飞的符号，尽量把它们作为前一个文本节点的内部内容来存储，这样模板不会把它们当成独立对象来处理。

4.4 打印出来的PDF总被Acrobat提示字体未嵌入

字体嵌入是很要命的一个审核点，合规文件打印阶段如果发现某个字体是未嵌入的，全流程都得返工。根因往往是字体文件的合法嵌入许可问题。排版时用了某个办公软件自带的字体，这个字体文件里可能带上了禁止嵌入的标志位。FOP渲染时会绕过嵌入了，但绕过后可能输出的是一个带警告的PDF。真正排查时要关注两件事：第一，确认字体文件的许可标志允许嵌入；第二，用“预处理字体“的工具检查源字体子集化是否正常。我的习惯是项目启动前就把需要用到的字体文件统一收拢到排版服务器上，注册一遍，再让XSLT里引用的字体名跟实际字体全名保持完全一致。很多字体嵌不上的奇怪问题是字体名不一致造成的：Windows显示的字体“中文名称”在Java的字体登记表里是英文名，最后FO里怎么写都匹配不上。

5. 哪些项目类型最适合引入XSL-FO：我的实际判断标准

正因为XSL-FO的上手曲线比HTML模板高，我经常要帮团队判断“这个项目到底该不该上XSL-FO”。如果只是为了每周生成几份报告，用HTML转PDF效率更高，真没必要费劲。但如果命中下面几条，我通常认为XSL-FO会是更合适的方向。

• 数据量很大，每份文档几十页甚至几百页，同时超过几十上百份。
• 交付文件不是给人看的临时文档，而是要归档、打印、甚至走法律流程。
• 排版规则几十年不变，比如行业标准、法律法规、学术期刊的版式。
• 输出格式不仅是PDF，未来还可能同一份XML内容同时转成PDF、打印流、电子书等不同媒介。
• 对页码、目录、页眉页脚的精细度要求达到了出版级。

在这些条件下，XSL-FO把“格式控制”这种最烦琐的事收编进了像样模板，不需要靠人力在桌面上逐份调整。

我曾经给某单位做过一个标准文件生成系统，源数据是历年的法规条文XML，模板按“发布稿版式”来做，XSLT里管理章条款式和公文页眉。运行了三年，每次产生新版标准，只需要替换XML数据就行，版式永远保持一致。但如果用普通方式生成，每份标准可能都需要排版人员重新对一次样式。这里的收益用一句话概括就是：把“不可重复的手工排版”变成了“可重复的自动化流水线生产”。

6. 直接可用的模板套路：搭建一个最小XSL-FO渲染框架

空谈半天不如直接给一套能落地的东西。这里我分享一个我已经用在多个项目里的最小骨架，你在本机下载一个FOP或者配置好一个XML工具就能跑通。

6.1 准备一份最简FO文件

下面这个FO文件生成了一个A4页面，带页眉文本和一个正文段落。它虽然简单，但知识点覆盖了：页面模板、区域主体、块级元素、内容流。你可以把它存成sample.fo，然后用FOP的相关命令行渲染成PDF。

<?xml version="1.0" encoding="UTF-8"?> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="first" page-height="297mm" page-width="210mm" margin-top="25mm" margin-bottom="25mm" margin-left="20mm" margin-right="20mm"> <fo:region-before extent="15mm"/> <fo:region-body margin-top="15mm"/> <fo:region-after extent="15mm"/> </fo:simple-page-master> </fo:layout-master-set> <fo:page-sequence master-reference="first"> <fo:static-content flow-name="xsl-region-before"> <fo:block text-align="center" font-size="9pt" color="#666666">季度业务报告</fo:block> </fo:static-content> <fo:static-content flow-name="xsl-region-after"> <fo:block text-align="center" font-size="9pt" color="#666666"> 第 <fo:page-number/> 页 </fo:block> </fo:static-content> <fo:flow flow-name="xsl-region-body"> <fo:block font-size="16pt" font-weight="bold" space-after="12pt">第一章 项目综述</fo:block> <fo:block font-size="11pt" line-height="1.6"> 这里填你的正文内容。XSL-FO 会按区域自动分页， 页脚的页码也会自动生成。</fo:block> </fo:flow> </fo:page-sequence> </fo:root>

这一小段代码跑通之后，你已经掌握了XSL-FO的两个最基础阶段：layout-master-set定义页面规格和区域，page-sequence承载内容流。接下来任何复杂版式都是在这个根结构上扩枝叶。

6.2 通过XSLT把基础XML接入FO

刚才那个FO文件是手写的，真实项目里FO通常由XSLT转换得到。这里我给出一个极简XSLT模板，源XML只包含一个标题段落，XSLT把它映射为FO。不要小看这一步，它把“源数据”和“版式”分开了。

<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format"> <xsl:output method="xml" encoding="UTF-8"/> <xsl:template match="/"> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="A4" page-height="297mm" page-width="210mm" margin="20mm"> <fo:region-body/> </fo:simple-page-master> </fo:layout-master-set> <fo:page-sequence master-reference="A4"> <fo:flow flow-name="xsl-region-body"> <xsl:apply-templates select="report/title"/> </fo:flow> </fo:page-sequence> </fo:root> </xsl:template> <xsl:template match="title"> <fo:block font-size="18pt" font-weight="bold"> <xsl:apply-templates/> </fo:block> </xsl:template> </xsl:stylesheet>

对应的最小XML文件可能是这样：

<?xml version="1.0" encoding="UTF-8"?> <report> <title>东北区域销售简报</title> </report>

使用Saxon或FOP内置的XSLT能力将这XML转换为FO后，再把FO交给渲染引擎输出PDF。整个过程可以由命令行脚本编排，也可以嵌入Java、.NET、Python应用定时自动执行。

6.3 调试这条链路时我用到的辅助工具

写XSL-FO阶段最容易出问题的其实不是FO语法，而是XML命名空间不匹配、标签闭合这类低级错误。我通常会先用XML编辑器打开FO文件检查格式良好性，再用引擎输出日志定位样式表问题。Oxygen这类工具能在编写XSLT同时预览FO结果，对调整样式相当高效。如果你不想花这个钱，也可以直接在IntelliJ IDEA或VS Code里装XML插件，写好FO后用命令行FOP渲染查看，效果差不多，只是预览实时性差一些。

真到了要把这条链路接到生产环境时，建议把渲染服务独立封装，不要和业务应用耦合在同一个进程里。开一个独立渲染接口，接收XML文件和模板标识，返回PDF。这样无论是定时任务批量生成还是用户按需下载，都能复用同一套排版能力，排查问题时也只需要盯一个服务的日志，不用从前端到数据库一路捞。

7. 进阶玩法：在FO里搞动态目录、页眉规则和跨页表格

跑通了最小项目之后，下面的高级能力能大幅拉升你交付PDF的“专业感”。这也是我每次给团队做技术分享时的保留内容，今天一块放在这里。

7.1 动态目录：目录不只是列表，而是可跳转导航

XSL-FO生成目录的核心是fo:page-number-citation。你先在正文中给每个需要出现在目录里的标题元素加上id，然后在目录区放置一个fo:block，它引用那个id，FOP会自动把它渲染为目标所在页的页码。

<fo:block> <fo:inline font-weight="bold"> <fo:basic-link internal-destination="chapter1"> 第一章 项目背景 </fo:basic-link> </fo:inline> <fo:leader leader-pattern="dots"/> <fo:page-number-citation ref-id="chapter1"/> </fo:block>

这里的关键在于fo:leader配合leader-pattern=“dots”填充点线，右侧自动生成页码。如果引用目标缺失，很多引擎的默认行为是生成一个0页，并不会立刻报错，所以交付前必须人工或半自动抽查一下目录页码。我通常会在最终输出PDF后写一段PDF解析脚本，逐个检查书签目的地的页码与实际页面的对应关系。

7.2 页眉规则：奇数页和偶数页的差异控制

做正式出版物时，页眉通常要“左页放书名、右页放章节名”，甚至奇偶页的页眉内容都不一样。在FO里靠page-master的odd-or-even来定义奇偶页的不同版式。通过这种方式可以做到真正的左右页对照排版，专业感一目了然。

<fo:simple-page-master master-name="left-page" odd-or-even="even" ...> <fo:region-before extent="12mm"> <fo:block>左侧页眉——书名</fo:block> </fo:region-before> </fo:simple-page-master> <fo:simple-page-master master-name="right-page" odd-or-even="odd" ...> <fo:region-before extent="12mm"> <fo:block>右侧页眉——当前章节名</fo:block> </fo:region-before> </fo:simple-page-master>

此外，你还能通过fo:marker把正文中动态的章节标题“推”到页眉区。正文每章开头设置marker，页眉静态区域引用这个marker的最新值，这样页眉就跟随内容自动变化，不需要人为写死在模板上。

7.3 跨页大表格：表头自动重复

产品规格书、财务报表里经常有超过一页的大表格。HTML转PDF时最恼人的就是表头不能自动重复，XSL-FO则天然支持。你只要把表头那些行放到fo:table-header里，引擎遇到跨页时自动在下一页顶部重复输出表头。这个能力从W3C规范到各引擎实现都非常稳定，实际体验下来比绝大多数桌面排版工具的表头重复逻辑还可靠。

<fo:table table-layout="fixed" width="100%"> <fo:table-column column-width="20%"/> <fo:table-column column-width="30%"/> <fo:table-column column-width="50%"/> <fo:table-header> <fo:table-cell border="solid 0.5pt black"> <fo:block font-weight="bold">编号</fo:block> </fo:table-cell> <fo:table-cell border="solid 0.5pt black"> <fo:block font-weight="bold">名称</fo:block> </fo:table-cell> <fo:table-cell border="solid 0.5pt black"> <fo:block font-weight="bold">备注</fo:block> </fo:table-cell> </fo:table-header> <fo:table-body> <xsl:apply-templates select="row"/> </fo:table-body> </fo:table>

跨页表格保持行不拆开的属性是keep-together=“within-column”，真正实现时可以先让整行作为最小单位，防止在行中间断开导致数据割裂。

8. 从一个人折腾到标准流水线：我遇到的那些“工具之外”的问题

最后聊点工具之外、但会在真实场景中影响成败的事情。

8.1 选型时先确认上游数据格式，而不是先定工具

不少人在引入XSL-FO时一上来就盯着引擎讨论，结果项目做着做着发现源数据是存在数据库里的大文本，甚至是由某个老系统导出的TXT，根本没法轻易转成XML。这种情况不是XSL-FO本身能解决的，而是数据治理问题。真正驱动的流程应该是：先梳理源数据是否能提供结构化XML，或者通过中间层把关系型数据表查询成XML视图。数据稳定了，引擎才谈得上排版效果。我在项目评估阶段通常会给客户发一份“XML数据审计清单”，列出必须补齐的字段和标签。别小看这个步骤，它拦下了后续至少一半的扯皮。

8.2 学会接受XSL-FO生态“给不了”的东西

XSL-FO有它极强的领地，但也有明确不擅长的部分。它不适合做复杂交互式电子文档，不适合做需要与用户动态交互的填写式PDF表单，也不适合做需要大量代码进行自定义绘制和图形动画的文件。还有一点容易被忽略的是，它在处理复杂的“版式自动避让”上比InDesign之类的桌面排版工具笨不少，后者可以由人拖拽微调，FO引擎则是按规则逐行往下排。如果你今天的需求是“把一百个海报文稿做成风格统一、构图灵活的PDF”，前端渲染会爽，FO反而痛苦。所以使用建议其实是：重要的大规模长文档交给FO，短小精致的创意文稿还是用适合它的工具更合适。

8.3 为这条技术线准备长线维护文档

每个引入XSL-FO的团队，最后都会沉淀一套自己的样式表和模板库。这部分资产我认为需要像代码库一样维护。我见过一些项目，模板写好后只有一个人能改，那位同事一旦换岗，模板就变成“负资产”。避免的办法是在项目初期就把模板目录、命名规范、公共变量、版本管理方法定清楚。XSLT和FO都是文本格式，可以纳入Git管理。每次改版要记录变更内容和影响范围，最好能配一套包含基准文本的自动回归测试，每次模板变更后渲染一遍关键样例，对比指定页面像素或文本内容是否意外变化。做了这个机制后，模板维护就不再是走钢丝，而是可控的迭代。

个人在实际操作中还有一个小习惯：每次更新模板后，把成品PDF的关键页面截图放进变更报告里，和上一版做视觉对比。别小看这个动作，很多属性改动表面上看没什么问题，到了印刷阶段才会暴露出边距、字号这类肉眼不易察觉的潜在错误。有对比图在手，和内容部门沟通也顺畅得多，少一点“我觉得看起来不一样了”这样难以复现的口头反馈。

希望这篇内容能帮你少走一些弯路。XSL-FO乍看起来确实是一门比较“老派”的技术，但它在文档自动化和电子出版上的底气至今没有多少后来者能完全替代。如果你正在做类似的项目选型或者已经在这条路上摸索，欢迎带着你的具体问题来交流，这东西光看概念真的不如实际跑通一个文档来得直观。