PDF 跨平台显示乱码？可能是因为字体没有嵌入

创作声明：由 AI 在人类指导下创作。人工已审核正确性。

使用 Pandoc + XeLaTeX 在 Linux 下生成的 PDF，发到 Windows 上打开全是乱码方块——这个问题我踩过了，写下来备忘。

原因

PDF 文件本身不会默认内嵌字体。它只在文件中记一笔「这里用思源宋体」，渲染时去系统里找这个字体。Linux 上编译时字体是齐全的，但 Windows/Mac 上没装同样的字体，系统就会用乱七八糟的 fallback 顶上，结果就是乱码。

检查一个 PDF 的字体是否已嵌入，用 pdffonts：

pdffonts doc.pdf

输出中 emb 列全是 yes 才说明字体已嵌入。

解决方案

给 Pandoc 的 xelatex 引擎加一个编译选项：

pandoc doc.md --pdf-engine=xelatex \
    --metadata-file ~/.pandoc/zh-metadata.yaml \
    -o doc.pdf

在 zh-metadata.yaml 中加入一行：

documentclass: ctexart
mainfont: Source Han Serif CN
monofont: WenQuanYi Micro Hei Mono
CJKoptions: [UTF8, EmbedAll]       # ← 这一行
papersize: a4
geometry: margin=2.5cm

关键在于 CJKoptions: [UTF8, EmbedAll]，它告诉 XeLaTeX 把所有用到的中文字体都打包进 PDF。

改完 metadata 文件后，以后所有用 Pandoc 生成的 PDF 都会自动内嵌字体，发到任何设备上打开都不会乱码。

熬了一晚上终于解决了这个阴间问题，再不写下来下次一定又忘。