soffice能正常运行才算真装好。需彻底卸载旧版、官网安装新版、补全图形与字体依赖、配置locale和字体缓存，并正确设置uno路径及headless服务，缺一不可。
soffice 能跑起来，才算真装好了。别只看图标能点开，很多离线安装后一导出 PDF 就崩，或中文显示为方块——问题往往出在依赖、字体、环境变量三处。
Ubuntu/Debian 系统用 apt 安装但版本旧？先清干净再手动装
系统自带的 libreoffice 通常滞后 1–2 年，功能缺失（比如 26.2 版本才有的 Markdown 导入），且和新版 .docx 兼容性差。
必须先彻底卸载：
sudo apt remove --purge libreoffice*sudo apt autoremove && sudo apt autoclean- 重启终端，确认
which soffice返回空
再从官网下载对应架构的 .deb 包（如 LibreOffice_26.2.2_Linux_x86-64_deb.tar.gz），解压后进 DEBS/ 目录执行：
sudo dpkg -i *.deb
如果报 dpkg: dependency problems，补一句：
sudo apt --fix-broken install
CentOS/RHEL 系统用 rpm 安装缺依赖？别跳过 X11 和字体库
直接 yum install *.rpm 很容易卡在 libXinerama.so.1 或 libSM.so.6 报错，这不是 LibreOffice 本身的问题，而是它底层依赖图形子系统。
- 先装基础图形库：
sudo yum install -y libXinerama libSM libXrender libXext - 再装完整桌面支持（避免 headless 模式失效）：
sudo yum groupinstall "X Window System" - 最后进
RPMS/目录运行：sudo yum localinstall *.rpm
验证是否真可用：
/opt/libreoffice26/program/soffice --version
注意路径里的版本号（如 libreoffice26），不是固定写死的 libreoffice。
中文乱码或导出 PDF 没汉字？光装软件不够，还得配字体和 locale
Linux 下 LibreOffice 默认不带中文字体，soffice --headless 转 PDF 时尤其容易丢字——因为没加载任何中文字体，连 fallback 都没有。
- 装字体包（推荐开源思源黑体）：
sudo apt install fonts-noto-cjk（Ubuntu）或sudo yum install gnu-free-fonts-common gnu-free-mono-fonts（CentOS） - 强制刷新字体缓存：
sudo fc-cache -fv - 检查中文字体是否生效：
fc-list :lang=zh应输出若干行含 “Noto” 或 “WenQuanYi” 的路径 - 设置语言环境（关键！）：在启动脚本或服务配置里加
export LC_ALL=zh_CN.UTF-8，否则即使字体存在，soffice仍按 C locale 解析文本
想用 Python 调用 LibreOffice 转 PDF？别直接 import uno
uno 模块不是 pip 装的，它随 LibreOffice 安装绑定在 /opt/libreofficeXX/program/ 下。Python 脚本要调用，必须满足三个条件：
- 确保
soffice进程已后台启动：/opt/libreoffice26/program/soffice --headless --accept="socket,host=127.0.0.1,port=2002;urp;" --nofirststartwizard - Python 中指定 UNO 路径：
import sys; sys.path.append('/opt/libreoffice26/program') - 连接时用绝对路径启动：
context = resolver.resolve("uno:socket,host=127.0.0.1,port=2002;urp;StarOffice.ComponentContext")
漏掉任意一条，ImportError: No module named 'uno' 或 Connection refused 就会立刻出现。
soffice --headless 在无桌面环境下稳定转出带中文的 PDF —— 字体、locale、Java 运行时（部分扩展需要）、共享内存大小（容器场景下尤其关键），每个环节都可能静默失败。
