CentOS / Alibaba Cloud Linux 使用 LibreOffice 将 Excel 导出 PDF 中文乱码问题排查与解决实践

在 Linux 服务器环境中，经常会使用 LibreOffice 的 Headless 模式实现 Excel 自动转换 PDF 功能，例如在 Node.js、Egg.js、Java、Python 等后台服务中批量生成 PDF 文件。

实际部署过程中，经常会遇到这样的问题：

• Excel 文件中的中文显示正常
• LibreOffice 转换过程执行成功
• 导出的 PDF 文件出现中文乱码、方框、空白字符或缺失文字

本文记录一次在 CentOS / Alibaba Cloud Linux 环境中排查和解决 LibreOffice 导出 PDF 中文乱码问题的完整过程。

问题现象

服务器通过 LibreOffice 命令将 Excel 转换为 PDF：

soffice \
  --headless \
  --convert-to pdf \
  test.xlsx

转换过程无报错：

convert /data/test.xlsx -> /data/test.pdf using filter : calc_pdf_Export

打开生成的 PDF 后发现：

□□□□□□
??????

或者部分中文内容直接消失。

而同一个 Excel 文件在 Windows 本地打开和导出均正常。

系统环境

查看系统字体包：

yum search noto

输出：

google-noto-cjk-fonts-common.noarch
google-noto-sans-cjk-ttc-fonts.noarch
google-noto-serif-cjk-ttc-fonts.noarch

说明系统仓库中已经提供了 Google Noto CJK 中文字体。

原因分析

LibreOffice 在导出 PDF 时需要调用系统字体。

Excel 文件通常使用以下字体：

• 微软雅黑（Microsoft YaHei）
• 宋体（SimSun）
• 黑体（SimHei）
• 仿宋（FangSong）
• 楷体（KaiTi）

这些字体默认存在于 Windows 系统中。

Linux 服务器通常不包含上述字体，因此 LibreOffice 无法找到对应字体，最终导致：

• 字体替换失败
• 字体嵌入失败
• PDF 中文乱码

安装中文字体

安装 Noto CJK 字体：

yum install -y \
    google-noto-sans-cjk-ttc-fonts \
    google-noto-serif-cjk-ttc-fonts

刷新字体缓存：

fc-cache -fv

验证字体安装结果

查看系统中的中文字体：

fc-list | grep "Noto Sans CJK"

输出示例：

Noto Sans CJK SC
Noto Sans CJK TC
Noto Sans CJK JP

说明字体已经安装成功。

验证字体匹配情况

查看系统对 Windows 字体的匹配结果：

fc-match "Microsoft YaHei"

fc-match "微软雅黑"

fc-match "SimSun"

fc-match "宋体"

正常情况下会返回类似结果：

NotoSansCJK-Regular.ttc

表示 FontConfig 已经将缺失字体映射到 Noto CJK 字体。

检查系统支持的中文字体

查看所有中文字体：

fc-list :lang=zh

输出示例：

Noto Sans CJK SC
Noto Serif CJK SC
Noto Sans CJK TC
Noto Sans CJK JP

说明系统已经具备完整的中文字体支持能力。

查看 LibreOffice 版本

确认当前 LibreOffice 版本：

libreoffice --version

示例：

LibreOffice 7.6.7.2

较新的 LibreOffice 版本对于字体映射和 PDF 导出兼容性更好。

导出 PDF

使用 Headless 模式转换：

soffice \
  --headless \
  --convert-to pdf \
  --outdir ./pdf \
  test.xlsx

或者：

libreoffice \
  --headless \
  --convert-to pdf:calc_pdf_Export \
  test.xlsx

转换成功后生成：

test.pdf

验证 PDF 字体嵌入

安装字体检测工具：

yum install -y poppler-utils

查看 PDF 中实际使用的字体：

pdffonts test.pdf

正常输出示例：

name                                 type
--------------------------------------------
NotoSansCJKsc-Regular                CID
NotoSerifCJKsc-Regular               CID

如果 PDF 中已经出现 Noto CJK 字体，说明字体已经正确嵌入。

使用 Windows 字体方案

部分业务场景要求 PDF 与 Windows 环境保持完全一致。

可以从 Windows 系统复制以下字体：

C:\Windows\Fonts

常见字体包括：

msyh.ttc
simsun.ttc
simhei.ttf
simkai.ttf
simfang.ttf

上传至服务器：

mkdir -p /usr/share/fonts/windows

将字体放入目录：

/usr/share/fonts/windows

刷新缓存：

fc-cache -fv

验证：

fc-match "Microsoft YaHei"

输出：

msyh.ttc

表示系统已经成功识别 Windows 字体。

完整排查流程

查看系统字体

fc-list | grep -i "noto\|wqy\|yahei\|simsun"

查看字体映射

fc-match "Microsoft YaHei"

fc-match "SimSun"

查看中文字体

fc-list :lang=zh

查看 LibreOffice 版本

libreoffice --version

转换 PDF

soffice \
  --headless \
  --convert-to pdf \
  test.xlsx

检查 PDF 字体

pdffonts test.pdf

结论

LibreOffice 在 Linux 环境下导出 Excel 为 PDF 出现中文乱码，本质上是字体缺失或字体映射失败导致的问题。

在 CentOS、Rocky Linux、AlmaLinux、Alibaba Cloud Linux 等发行版中，通过安装 Noto CJK 字体并刷新 FontConfig 缓存后，LibreOffice 即可正确识别中文字体并在导出的 PDF 中嵌入对应字体，从而解决中文乱码、方框字符以及文字缺失等问题。

安装完成后，通过 fc-match 验证字体映射，通过 pdffonts 验证 PDF 字体嵌入情况，可以快速定位和确认问题是否已经解决。