PrinceXML 16.2 安装与依赖踩坑：Ubuntu 26.04 实战

你在 VS Code 写 Markdown 写得正顺，Ctrl+Shift+P → “Markdown Preview Enhanced: Export to PDF”，弹窗告诉你：”princexml is required to be installed.”

这个报错说的是 PrinceXML，一款能把 HTML+CSS 精确渲染成 PDF 的商业引擎。Markdown Preview Enhanced 插件导出 PDF 时默认用它做后端，如果你没装 Prince，插件就甩出这行提示就走不下去了。

我去 Prince 官网下载了 Ubuntu 26.04 对应的 deb 包，原以为十分钟能搞定的事，实际走了三个弯。

下载环节：/tmp 空间满导致静默失败

习惯性地用 curl 下载到 /tmp/：

curl -sL "https://www.princexml.com/download/prince_16.2-1_ubuntu26.04_amd64.deb" \
  -o /tmp/prince.deb

退出码 23，文件没写进去。原因是 /tmp 挂载为 tmpfs，只有 1.6G 且已经满了。curl 的写入错误在这种静默模式（-sL）下一声不吭。换成下载到家目录就通过了：

curl -sL "https://www.princexml.com/download/prince_16.2-1_ubuntu26.04_amd64.deb" \
  -o ~/prince.deb

原理很简单：/tmp 在很多 Linux 发行版上是独立的 tmpfs，大小受物理内存约束，不是磁盘剩余空间。容器环境更常见——系统盘还有 100 多 G 空闲，但 /tmp 已经撑满了。下载前先看一眼 df -h /tmp 就能避掉这个坑。

dpkg 装了一半：libavif16 缺失

deb 包只有 8.9MB，下载没问题了，直接安装：

sudo dpkg -i ~/prince.deb

dpkg 解包成功，二进制已经落到系统里了。但配置阶段报依赖错误：

dpkg: dependency problems prevent configuration of prince:
 prince depends on libavif16 (>= 1.3.0); however:
  Package libavif16 is not installed.

Prince 16.x 开始支持 AVIF 格式图片渲染，新增了对 libavif16 的依赖。Ubuntu 26.04 基础安装里没有这个包。此时 prince --version 是静默退出的——dpkg 解包成功不等于安装完成。

依赖修复死锁：apt 也装不上

按常规思路让 apt 补上缺失的依赖：

sudo apt-get install -y libavif16

遇到报错：

E: Write error - write (28: No space left on device)
E: The package lists or status file could not be parsed or opened.

apt 在下载包列表时需要写入 /var/lib/apt/lists/，而这个操作也间接受 /tmp 空间不足的影响。死锁状态如下：

1. dpkg 卡在 libavif16 上无法完成配置
2. apt 需要磁盘空间才能下载包
3. /tmp 空间不足导致 apt 缓存写不进去

要跳出这个环，先清理 apt 缓存再重试：

sudo apt-get clean
sudo rm -rf /var/cache/apt/archives/*.deb
sudo apt-get update -qq
sudo apt-get install -y libavif16
sudo dpkg --configure -a

清理后 apt 能正常下载 libavif16，然后 dpkg --configure -a 补上之前卡住的配置步骤，Prince 就能用了。

说个额外提醒：在 cron 或自动化脚本里跑 sudo rm -rf /tmp/* 可能会被安全扫描器拦截挂起。尽量精确到具体文件，避免大范围删除系统目录的操作。

替代方案

如果 PrinceXML 的安装流程在你的环境里实在太折腾，或者你不想用商业软件（Prince 个人用免费，商用需购买许可），还有几条路：

• weasyprint — 开源免费，pip install weasyprint 直接装。CSS 支持接近 Prince，渲染速度稍慢。Markdown Preview Enhanced 插件在设置里可以切换 PDF 后端
• wkhtmltopdf — 基于 WebKit，apt install wkhtmltopdf 就能搞定。项目已停止维护，新项目不推荐
• pandoc + weasyprint — 灵活但配置稍复杂，适合文档自动化流水线

这几个在 Markdown Preview Enhanced 的设置里都能配置，不一定要绑死 Prince。

总结

这次安装耗时不多，但每一步都有可能卡住的地方：下载前不看 /tmp 空间会静默失败，dpkg 解包成功不等于装完，依赖修复遇到磁盘空间不足会死锁。这几个点了解之后，下一次装 Prince 十分钟就够了。