LibreOffice headless模式下中文乱码如何解决？

Question

在使用LibreOffice headless模式进行文档转换（如DOC转PDF）时，常因系统缺少中文字体导致中文显示为乱码或方框。该问题多出现在Linux服务器环境，由于未安装支持中文的字体包（如wqy-zenhei、fonts-noto-cjk），LibreOffice无法正确渲染中文内容。即使文档本身使用宋体或微软雅黑，headless模式下亦无法映射到可用字体。如何在无GUI的服务器环境下正确安装并配置中文字体，使LibreOffice自动识别并正常渲染中文，是部署文档转换服务时的常见技术难题。

Answer 1

解决LibreOffice Headless模式下中文乱码问题的完整方案

1. 问题背景与现象描述

在Linux服务器环境中，使用LibreOffice的headless模式进行DOC到PDF等格式转换时，常出现中文字符显示为方框或乱码的情况。该问题的根本原因在于：系统未安装支持中文的TrueType或OpenType字体包，导致LibreOffice无法正确映射文档中指定的中文字体（如宋体、微软雅黑）。

即使原始文档明确使用了特定中文字体，在无GUI的headless环境下，LibreOffice会因字体缺失而回退至默认字体，若默认字体不包含中文字符集，则渲染失败。

2. 常见错误表现形式

• PDF输出中中文变为“□□□”或空白区域
• 日志中出现“Warning: font not found”相关提示
• 英文正常显示，但中文全部丢失或变形
• 不同版本LibreOffice行为不一致（如6.x vs 7.x）
• 本地测试正常，部署至Docker容器后异常

3. 字体机制分析：LibreOffice如何查找字体

LibreOffice在启动时通过Fontconfig系统查询可用字体。其搜索路径包括：

1. /usr/share/fonts/
2. ~/.local/share/fonts/
3. 系统缓存中的字体注册信息（由fc-cache生成）

当文档请求“SimSun”或“Microsoft YaHei”时，LibreOffice尝试匹配已安装字体。若无精确匹配，则依赖fontconfig的alias机制进行替代。

4. 解决方案层级结构

层级	措施	适用场景
1	安装基础中文字体包	所有Linux发行版
2	刷新字体缓存	字体安装后必须执行
3	配置fontconfig别名映射	模拟Windows字体
4	设置LibreOffice默认字体替换	批量处理统一风格
5	Docker镜像预置字体	云原生部署环境
6	自定义profile字体目录	多用户隔离场景

5. 实操步骤：以Ubuntu/Debian为例

# 安装常用中文字体包
sudo apt-get update
sudo apt-get install -y fonts-wqy-zenhei fonts-noto-cjk fonts-liberation2

# 可选：手动添加Windows字体（需合法授权）
sudo mkdir -p /usr/share/fonts/truetype/custom/
sudo cp /path/to/SIMSUN.TTC /usr/share/fonts/truetype/custom/
sudo fc-cache -fv

# 验证字体是否被识别
fc-list :lang=zh | grep -i "sun\|hei\|yahei"

6. Fontconfig高级配置：实现字体自动映射

编辑或创建文件 /etc/fonts/local.conf，添加如下内容以确保宋体、微软雅黑等能正确映射：

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
  <match target="pattern">
    <test qual="any" name="family">
      <string>SimSun</string>
    </test>
    <edit name="family" mode="assign">
      <string>WenQuanYi Zen Hei</string>
    </edit>
  </match>

  <match target="pattern">
    <test qual="any" name="family">
      <string>Microsoft YaHei</string>
    </test>
    <edit name="family" mode="assign">
      <string>Noto Sans CJK SC</string>
    </edit>
  </match>
</fontconfig>

7. LibreOffice内部字体替换策略

可通过修改LibreOffice配置文件强制字体替换。路径通常位于：

~/.config/libreoffice/4/user/registrymodifications.xcu

添加以下XML片段：

<item oor:path="/org.openoffice.Office.Common/Fonts/FontSubst">
  <prop oor:name="SubstFonts" oor:type="oor:string-list">
    <value>SimSun|WenQuanYi Zen Hei|0|0|0|0|;</value>
    <value>Microsoft YaHei|Noto Sans CJK SC|0|0|0|0|;</value>
  </prop>
</item>

8. Docker环境下的最佳实践

graph TD A[构建基础镜像] --> B[安装中文字体包] B --> C[运行fc-cache -fv] C --> D[拷贝fontconfig配置] D --> E[设置LO环境变量] E --> F[启动服务] style A fill:#f9f,stroke:#333 style F fill:#bbf,stroke:#333

9. 验证与调试技巧

使用如下命令检查LibreOffice实际使用的字体：

libreoffice --headless --convert-to pdf test.docx --outdir /output 2>&1 | grep -i font

启用详细日志：

export SAL_LOG=+all
export SAL_DEBUG=WARN

10. 扩展建议与长期维护

对于生产级文档转换服务，建议：

• 建立标准化字体模板镜像
• 定期更新Noto、WenQuanYi等开源字体版本
• 监控字体缓存状态
• 对OCR类文档增加字体嵌入策略
• 考虑使用unoconv或LibreOfficeKit提升性能
• 在CI/CD流程中集成字体可用性检测
• 避免从不可信来源获取TTF文件
• 关注LibreOffice社区关于CJK支持的更新
• 评估商业字体授权合规风险
• 记录每台服务器的字体清单用于审计