Ubuntu 22.04 安装 Apache FOP 2.11 指南

在 Ubuntu 22.04.5 上从官方二进制包安装 Apache FOP 2.11，覆盖下载校验、断点续传、目录结构、首次渲染验证、FOP_OPTS 与 locale 配置，含 10 个常见问题排障

Apache FOPFOPApacheJava安装部署Ubuntu 22.042026/10/14

Ubuntu 22.04 安装 Apache FOP 2.11 指南

一、环境信息

本文所有命令与回显均在以下环境实测采集，读者在其他环境操作时输出可能略有差异。

项目值
操作系统Ubuntu 22.04.5 LTS（GNU/Linux x86_64）
内核5.15.0
主机名node1.fop.example
IP172.17.0.7
登录账号root / q1w2e3r4
JavaOpenJDK 11.0.32.1（openjdk-11-jre-headless）
目标版本Apache FOP 2.11
安装目录/opt/fop-2.11（软链 /opt/fop）

Apache FOP（Formatting Objects Processor）是 Apache XMLGraphics 旗下的 XSL-FO 排版处理器，把 XSL-FO 文档渲染成 PDF、PostScript、PCL、PNG、TIFF 等格式。它是纯 Java 命令行工具，不是常驻服务，安装本质就是「装 JDK + 解压发行包」。

二、前置条件

2.1 更新软件源并安装基础工具

apt-get update

实测输出（节选）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
Get:2 http://archive.ubuntu.com/ubuntu jammy-updates InRelease [128 kB]
...
Reading package lists... Done
Building dependency tree... Done

DEBIAN_FRONTEND=noninteractive apt-get install -y curl wget openjdk-11-jre-headless

实测输出（节选）：

Setting up openjdk-11-jre-headless:amd64 (11.0.32.1+1-0ubuntu1~22.04) ...
Setting up curl (7.81.0-1ubuntu1.21) ...
Setting up wget (1.21.2-2ubuntu1.1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.14) ...

2.2 验证 Java

java -version

实测输出：

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

FOP 2.11 需要 Java 8 及以上，实测 OpenJDK 11 运行正常。只需 JRE，无需 JDK 编译组件。

2.3 规划磁盘目录

目录用途
/opt/downloads发行包存放
/opt/fop-2.11程序目录（解压生成）
/opt/fop软链接（便于升级与脚本引用）
/work/src自建 XSL-FO / XML / XSL 源文件
/work/out渲染产物输出
/work/conf自定义 fop.xconf 配置

三、版本选型与下载

3.1 版本说明

FOP 发行包挂在 dlcdn.apache.org/xmlgraphics/fop/（注意不是 /fop/ 顶层目录），子目录 binaries/ 存放二进制包，source/ 存放源码包。2026-10 查询时 binaries 目录仅提供 2.11 一个版本：

文件说明
fop-2.11-bin.tar.gzLinux/macOS 二进制包（17,198,578 字节）
fop-2.11-bin.zipWindows 二进制包
fop-2.11-bin.tar.gz.sha512SHA-512 校验文件
fop-2.11-bin.tar.gz.ascGPG 签名

更早版本（2.9、2.10 等）已从 dlcdn 移除，需要时到 archive.apache.org 查询。

3.2 下载发行包

mkdir -p /opt/downloads && cd /opt/downloads
curl -sS -O https://dlcdn.apache.org/xmlgraphics/fop/binaries/fop-2.11-bin.tar.gz \
     -O https://dlcdn.apache.org/xmlgraphics/fop/binaries/fop-2.11-bin.tar.gz.sha512
ls -l

实测输出（完整下载后）：

-rw-r--r-- 1 root root 17198578 Oct 14 14:00 fop-2.11-bin.tar.gz
-rw-r--r-- 1 root root     139 Oct 14 13:40 fop-2.11-bin.tar.gz.sha512

注意 content-length 应为 17,198,578 字节。实测环境到 dlcdn 的链路速度只有约 60 KB/s，首次下载曾被中断在 5.6 MB，可以用 curl -I 先确认期望大小、下载后核对实际字节数：

curl -sSI https://dlcdn.apache.org/xmlgraphics/fop/binaries/fop-2.11-bin.tar.gz | grep -i content-length

实测输出：

content-length: 17198578

3.3 下载中断的断点续传

如果下载意外中断（tar tzf 会报 unexpected end of file），用 -C - 从断点续传：

curl -sS -C - -O https://dlcdn.apache.org/xmlgraphics/fop/binaries/fop-2.11-bin.tar.gz

国内网络也可以改用清华 TUNA 镜像（实测速度远快于 dlcdn，文件内容与官方完全一致，SHA-512 校验值相同）：

curl -sS -o fop-2.11-bin.tar.gz \
  https://mirrors.tuna.tsinghua.edu.cn/apache/xmlgraphics/fop/binaries/fop-2.11-bin.tar.gz

3.4 校验 SHA-512

官方 .sha512 文件是 BSD 风格格式（摘要 + 两个空格 + 文件名）：

cat fop-2.11-bin.tar.gz.sha512

实测输出：

47f26517cdb514415e584a804763a5b81b8f178279d921c73b9c0a6a179f3cfc13ac2071a2085277158b336ad9c84e40a86358aa235da82a8f7ef4e83b994b16  fop-2.11-bin.tar.gz

本地计算比对：

sha512sum fop-2.11-bin.tar.gz

实测输出：

47f26517cdb514415e584a804763a5b81b8f178279d921c73b9c0a6a179f3cfc13ac2071a2085277158b336ad9c84e40a86358aa235da82a8f7ef4e83b994b16  fop-2.11-bin.tar.gz

两端摘要一致，文件完整。注意 FtpServer 那种「8 位分组大写」格式在这里不适用——FOP 的校验文件就是普通小写十六进制串，awk '{print $1}' 取第一列直接比较即可。

四、安装步骤

4.1 解压并建立软链接

cd /opt
tar xzf downloads/fop-2.11-bin.tar.gz
ln -s /opt/fop-2.11 /opt/fop
ls -l /opt/fop

实测输出：

lrwxrwxrwx 1 root root 27 Oct 14 14:01 /opt/fop -> /opt/fop-2.11

tar 包解出的顶层目录名是 fop（不带版本号），实际会得到 /opt/fop，因此把它改名为带版本号的目录再软链回去，便于多版本共存：

cd /opt
mv fop fop-2.11
ln -s /opt/fop-2.11 /opt/fop

4.2 发行包目录结构

ls /opt/fop/fop

实测输出：

build  conf  examples  fop  fop.bat  fop.cmd  fop.js  lib
目录/文件说明
fopLinux/macOS 启动脚本（本文主角）
fop.bat / fop.cmd / fop.jsWindows 批处理 / JS 启动器
build/FOP 本体 jar：fop.jar、fop-core-2.11.jar、fop-util-2.11.jar、fop-events-2.11.jar、fop-sandbox.jar、fop-hyph.jar
conf/fop.xconf示例配置文件（内容即内置默认值，见配置篇）
examples/官方示例：fo/（XSL-FO 样例）、embedding/（Java API）、hyphenation/、mathml/、plan/
lib/26 个第三方依赖 jar

依赖 jar 里值得认识的几个：

ls /opt/fop/fop/lib | grep -E "xmlgraphics|batik-basic|fontbox|commons-io"

实测输出：

fontbox-3.0.3.jar
commons-io-2.17.0.jar
xmlgraphics-commons-2.11.jar
依赖作用
xmlgraphics-commons-2.11FOP 图像与 IO 基础库
batik-*（1.19 系列 19 个 jar）SVG 解析与光栅化（fo 内嵌 SVG 时用）
fontbox-3.0.3 / pdfbox-io-3.0.3字体解析（TTF/OTF/PFB）
xml-apis / xml-apis-extXML 标准 API
commons-io / commons-logging通用工具

4.3 examples 目录速览

ls /opt/fop/fop/examples/fo/basic

实测输出：

alignment.fo    extensive.fo  leader.fo    normalex.fo  table.fo
blockcontainer.fo  fonts.fo   link.fo      pdfoutline.fo  tableunits.fo
border.fo       hyphen.fo     list.fo      readme.fo     textdeko.fo
bordershorthand.fo  images.fo   newlinktest.fo  simple.fo
character.fo    inhprop.fo    normal.fo    simple.fo.orig
corresprop.fo   instream.fo   ...

basic 目录共 24 个示例文件，覆盖对齐、边框、列表、表格、链接、字体等常见排版特性，是学习 XSL-FO 语法的最佳材料，也是验证安装是否可用的现成输入。

五、首次运行验证

5.1 查看版本号

cd /opt/fop/fop
./fop -version

实测输出：

FOP Version 2.11

5.2 查看帮助

./fop -h

实测输出（节选，完整解读见 CLI 篇）：

USAGE
fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
 [OPTIONS]
  -version          print FOP version and exit
  -c cfg.xml        use additional configuration file cfg.xml
  ...

5.3 渲染官方示例

用 examples 自带的 simple.fo 做第一次渲染：

mkdir -p /work/out
./fop examples/fo/basic/simple.fo /work/out/simple.pdf

实测输出：

Oct 14, 2026 1:59:54 PM org.apache.fop.apps.FOUserAgent processEvent
INFO: Rendered page #1.

确认产物：

ls -l /work/out/simple.pdf

实测输出：

-rw-r--r-- 1 root root 5663 Oct 14 13:59 simple.pdf

渲染日志打到 stderr，格式是 java.util.logging 的两行一条：时间戳 + 事件源，下面 INFO: 事件内容。Rendered page #1. 表示第 1 页已渲染完成；多页文档会逐页输出。如果装了 poppler-utils，可以用 pdfinfo /work/out/simple.pdf 查看页数与页面尺寸。

5.4 缺字警告是正常现象

直接渲染含中文的 .fo（字体未配置时），会出现：

WARNING: Glyph "?" (0x67d3) not available in font "Times-Roman".

PDF 仍会生成，但中文字符全部丢失（0x67d3 是「染」的 Unicode 码点，其余中文字符同理逐个告警）。这不是安装问题——FOP 的 Base-14 内置字体只覆盖拉丁字符，中文渲染必须注册 TTF 字体，解决方案见《Apache FOP 2.11 配置参数详解》第三章。

六、命令全局可用与运行环境

6.1 加入 PATH

FOP 没有安装器，把启动脚本软链到 /usr/local/bin 即可全局调用：

ln -s /opt/fop/fop/fop /usr/local/bin/fop
cd /tmp
fop -version

实测输出：

FOP Version 2.11

注意软链的是脚本本身，脚本内部按自身位置反查 lib 目录，因此从任何工作目录执行都能找到依赖 jar。

6.2 FOP_OPTS：给 JVM 传参

fop 脚本通过环境变量 FOP_OPTS 向 JVM 传递参数（如堆大小、系统属性）：

FOP_OPTS="-Xmx512m" fop -version

实测输出：

FOP Version 2.11

用脚本自带的 --execdebug 可以看到实际拼出来的 java 命令行，验证 FOP_OPTS 是否生效：

FOP_OPTS="-Xmx64m" fop --execdebug -version 2>&1 | head -1 | grep -o '\-Xmx64m'

实测输出：

-Xmx64m

--execdebug 输出的 exec 行里可以看到完整的 -classpath 串（lib 下所有 jar + build 下的 fop 系列 jar），主类是 org.apache.fop.cli.Main。

6.3 启动脚本自动加载的配置文件

fop -h 的 Script Options 段写明：

  --noconfig             suppress sourcing of /etc/fop.conf,
                         $HOME/.fop/fop.conf, and $HOME/.foprc
                         configuration files

即脚本启动前会依次加载 /etc/fop.conf、$HOME/.fop/fop.conf、$HOME/.foprc 三个文件（内容会并进 FOP_OPTS）。多用户服务器上可以用 $HOME/.fop/fop.conf 给每个用户定制 JVM 参数，不需要改发行包脚本。

6.4 设置 UTF-8 locale（强烈建议）

实测当系统 locale 为 POSIX 时，命令行参数里的中文会被替换成问号（例如 -param title "季度" 传进 XSLT 后变成乱码）。设置 UTF-8 locale 可避免：

export LANG=C.UTF-8
locale | head -3

实测输出：

LANG=C.UTF-8
LANGUAGE=
LC_CTYPE="C.UTF-8"

建议把 export LANG=C.UTF-8 写进 /root/.bashrc 或 systemd 定时任务的环境里。

七、常见问题排障

7.1 tar 解压报 unexpected end of file

发行包下载被截断。用 ls -l 对比 content-length（17,198,578），然后 curl -C - 续传或换 TUNA 镜像重下（见 3.3）。

7.2 sha512 校验对不上

先确认拿到的是完整文件（截断文件的摘要必然不同）；再确认对比方法——官方 .sha512 是小写摘要 + 双空格 + 文件名，直接 sha512sum 输出比对即可，不要手工去空格后比错列。

7.3 ./fop 提示 No such file or directory

多见于两处：一是脚本没有可执行位（chmod +x /opt/fop/fop/fop，发行包默认已带 x 位）；二是用 Windows 的 fop.bat 在 Linux 下执行。

7.4 运行报 UnsupportedClassVersionError

JDK 版本低于 8。java -version 确认版本；Ubuntu 22.04 用 apt-get install openjdk-11-jre-headless 安装。

7.5 中文渲染出来是空白或问号

未注册 CJK 字体，属于预期行为（见 5.4）。注册方法见配置篇第三章；注意 fonts-noto-cjk 是 CFF 轮廓的 OTF 集合，FOP 无法加载（报 'loca' table not found），应改用 TrueType 轮廓的字体（如文泉驿正黑 wqy-zenhei.ttc、Droid Sans Fallback）。

7.6 命令行传中文参数变乱码

POSIX locale 下 JVM 用 ASCII 解码 argv。export LANG=C.UTF-8 后重试（见 6.4）。

7.7 fop 命令找不到，但 /opt/fop 存在

软链没建或建错位置。ln -s /opt/fop/fop/fop /usr/local/bin/fop（6.1）。

7.8 大文档渲染 OOM 或很慢

默认堆不一定够。用 FOP_OPTS 调堆，如 FOP_OPTS="-Xmx1024m"；再配合 CLI 的 -conserve 内存保守策略（实测 300 页 A4 纯文本文档默认堆约 235 MB RSS、2 秒渲染完成，详见 CLI 篇第七章）。

7.9 Hudson/Jenkins 等环境无法写 /root/.fop

FOP 会往 $HOME/.fop/fop-fonts.cache 写字体缓存。账号无家目录时可用 -cache /var/cache/fop/fop-fonts.cache 显式指定缓存路径，或 -noflush/-flush 控制刷新。

7.10 只想转 XSL 不渲染

用 -foout 参数，把 XML+XSL 的中间 XSL-FO 结果保存下来排查样式表问题（详见 CLI 篇 2.5）。

八、参考链接

资源地址
FOP 官网https://xmlgraphics.apache.org/fop/
2.11 发行说明https://xmlgraphics.apache.org/fop/2.11/releaseNotes_2.11.html
下载目录https://dlcdn.apache.org/xmlgraphics/fop/binaries/
运行（CLI）文档https://xmlgraphics.apache.org/fop/2.11/running.html
配置文档https://xmlgraphics.apache.org/fop/2.11/configuration.html
字体文档https://xmlgraphics.apache.org/fop/2.11/fonts.html
官方示例包发行包内 examples/fo/ 目录