CentOS 上 LibreOffice 无法启动的排查与修复
一 快速自检与通用修复
- 确认命令路径与版本：使用安装目录下的可执行文件测试，例如 /opt/libreoffice7.6/program/soffice --headless --invisible --convert-to pdf:writer_pdf_Export /www/1.docx --outdir /www；若提示命令不存在，先定位安装路径（常见为 /opt/libreofficeX.Y/）。
- 前台直接运行看报错：执行 /opt/libreofficeX.Y/program/soffice（无参数），前台输出能最快定位是缺库、路径还是权限问题。
- 安装/补齐依赖：无界面或 headless 场景建议安装 libreoffice-headless；桌面环境缺失图形库会导致启动失败，按需补齐（见下文“常见缺库对照表”）。
- 避免中文或空格路径：项目/文档路径包含中文或空格时，LibreOffice（尤其是转换/服务场景）容易异常或找不到进程，建议改为全英文路径测试。
- 端口与进程：转换服务常用端口 8100；若提示 “started but its pid could not be found”，多为服务未真正起来或端口被占用，先检查端口占用并更换端口重试。
二 常见缺库与对应安装命令
- 下表覆盖最常见的启动/转换失败原因及修复（按报错关键词安装对应包）：
| 报错关键词 |
可能缺失的包 |
安装命令示例 |
| error while loading shared libraries: libSM.so.6 |
libSM |
sudo yum install -y libSM |
| error while loading shared libraries: libICE.so.6 |
libICE |
sudo yum install -y libICE |
| error while loading shared libraries: libX11-xcb.so.1 |
libX11-xcb |
sudo yum install -y libX11-xcb |
| error while loading shared libraries: libXext.so.6 |
libXext |
sudo yum install -y libXext |
| error while loading shared libraries: libXinerama.so.1 |
libXinerama |
sudo yum install -y libXinerama |
| error while loading shared libraries: libcairo.so.2 |
cairo |
sudo yum install -y cairo |
| error while loading shared libraries: libcups.so.2 |
cups-libs |
sudo yum install -y cups-libs |
| no suitable windowing system found, exiting |
图形相关库（如 libXt、libXrender） |
sudo yum install -y libXt libXrender |
- 一键补齐常用依赖（无界面/转换推荐）：sudo yum install -y libreoffice-headless libSM libICE libX11-xcb libXext libXinerama cairo cups-libs；若仍报缺库，用 yum provides “/缺失文件名.so” 精准查找并安装对应包。
三 以服务方式启动与端口占用处理
- 启动命令（前台便于看日志）：
/opt/libreoffice7.6/program/soffice --headless --accept=“socket,host=127.0.0.1,port=8100;urp;” --nofirststartwizard &
- 更换端口避免冲突（例如 10087）：
/opt/libreoffice7.6/program/soffice --headless --accept=“socket,host=127.0.0.1,port=10087;urp;” --nofirststartwizard &
- 检查端口占用：
netstat -nalp | grep 8100（或 grep 10087）
- 若提示 “process … started but its pid could not be found”，优先检查端口是否被占用、是否以正确用户启动、是否缺少依赖导致进程秒退。
四 Java 集成场景的要点（JodConverter/Spring Boot）
- 配置 officeHome 时不要带 program 子目录：正确示例为 /opt/libreoffice7.5，错误示例为 /opt/libreoffice7.5/program。
- 启动命令建议使用前台方式（便于排查），确认无报错后再交给服务托管。
- 若命令行可转、但接口超时：重启 Java 服务，确保使用与命令行一致的 officeHome 与 端口。
五 其他注意事项
- 升级与重装：若版本过旧或组件损坏，先彻底卸载再重装（如 yum remove libreoffice*），然后从官方站点下载 RPM 包解压安装，进入 RPMS 目录执行 *yum localinstall -y .rpm。
- 字体问题：转换后中文乱码或字体不一致，将字体放入 /usr/share/fonts/，执行 fc-cache -fv 刷新缓存，必要时安装常用中文字体包。
- 系统环境：CentOS 7 已于 2024-06-30 停止维护，长期建议迁移到仍受支持的 RHEL/SLES 或新版本发行版，以获得更好的兼容性与安全更新。
