用 LibreOffice 命令行批量转换文档：headless 模式、过滤器参数与结果校验

如果你手头有一批 DOCX、XLSX 或 PPTX，需要统一转成 PDF，用桌面端逐个“另存为”会很快耗尽耐心。LibreOffice 的 headless 模式可以把这件事搬到命令行：不打开图形界面，直接调用转换过滤器，配合 --outdir 和一段循环脚本，就能对成百上千个文件做批处理。它适合放在本地批处理、定时任务或服务器端流水线里，但结果是否和桌面端一致，仍取决于字体、版式、文件复杂度和当前 LibreOffice 版本，动手前最好先拿一组样本实测。

先判断 headless 模式适不适合你的任务

headless 的核心价值是“无人值守”。你可以在终端、CI 任务或远程服务器上执行命令，不需要桌面会话，也不依赖鼠标操作。soffice --convert-to 本身就隐含了 headless 行为，但显式写上 --headless 更清楚，也更方便排查。

它比较适合这些场景：

把一批 DOCX、XLSX、PPTX、ODT、ODS 等格式统一导出为 PDF。
把文档转换成 HTML、TXT 等中间格式，供后续程序处理。
在固定时间或固定目录下自动转换新增文件。
在服务器上做文档预览、归档或下载前的格式统一。

它不适合直接替代所有桌面操作。宏、复杂域、嵌入对象、特殊字体、修订模式、受密码保护的文件、需要交互确认的弹窗，都可能让结果和预期不同。更重要的是，命令行转换通常不会替你做“视觉验收”，所以脚本跑完后仍然要抽查 PDF 的页数、字体、表格和分页。

安装与确认命令行入口

LibreOffice 在 Linux 上通常可以通过发行版仓库安装，命令名可能是 libreoffice，也可能是 soffice。安装完成后先确认版本和入口：

soffice --version
# 如果上面不可用，尝试：
libreoffice --version

Windows 和 macOS 的安装位置不同，建议在脚本中使用完整路径，或者把程序目录加入 PATH。

Windows 常见路径示例：

& "C:Program FilesLibreOfficeprogramsoffice.exe" --version

macOS 常见路径示例：

/Applications/LibreOffice.app/Contents/MacOS/soffice --version

不同版本、不同安装方式下路径可能变化，发布脚本前先用 --version 和目标文件做一次最小验证。LibreOffice 的命令行行为、过滤器名称和参数支持会随版本演进，涉及批量交付时，最好在目标机器上核验当前版本的实际表现。

最小转换命令与输出目录

把一个 DOCX 转成 PDF，最小命令是这样：

soffice --headless --convert-to pdf --outdir ./pdf ./input.docx

其中需要你替换的部分：

./input.docx：输入文件路径，可以写相对路径或绝对路径。
./pdf：输出目录，不存在时先创建。
pdf：目标扩展名，LibreOffice 会按扩展名选择默认过滤器。

如果不写 --outdir，输出文件会落在当前工作目录。批量脚本里建议始终显式指定输出目录，避免脚本从不同位置启动时把文件散落到意外位置。

一次转换多个文件时，可以让 shell 展开通配符：

soffice --headless --convert-to pdf --outdir ./pdf ./docs/*.docx

但要注意，不同 shell、不同文件名编码和空格处理方式不同。文件名里包含空格、括号、中文或特殊符号时，最稳妥的做法是在脚本里逐个文件调用，并用引号包住路径。

理解 –convert-to 的过滤器写法

--convert-to 的完整形式可以写成：

soffice --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams[,param]]] [--outdir output_dir] file...

拆开看：

OutputFileExtension：目标扩展名，例如 pdf、html、txt、xlsx。
OutputFilterName：可选，指定导出过滤器名称，例如 writer_pdf_Export、calc_pdf_Export。
OutputFilterParams：可选，传给过滤器的参数，常见形式是 JSON 字符串。
--outdir output_dir：输出目录。

几个实际写法：

# 按默认 PDF 过滤器转换 Writer 文档
soffice --headless --convert-to pdf --outdir ./pdf ./docs/*.docx

# 显式指定 Writer 的 PDF 导出过滤器
soffice --headless --convert-to pdf:writer_pdf_Export --outdir ./pdf ./docs/*.docx

# 转成 HTML，并指定过滤器名称和编码
soffice --headless --convert-to "html:XHTML Writer File:UTF8" --outdir ./html ./docs/*.doc

# 转成带编码的纯文本
soffice --headless --convert-to "txt:Text (encoded):UTF8" --outdir ./txt ./docs/*.doc

PDF 导出过滤器通常和文档类型对应：Writer 常用 writer_pdf_Export，Calc 常用 calc_pdf_Export，Impress 常用 impress_pdf_Export。具体名称以你当前版本的过滤器表为准。如果过滤器名称写错，转换可能无声地失败，或者只生成一个不符合预期的文件。

过滤器参数适合处理“只导出第一页”“指定页码范围”这类需求。例如 Calc 只导出第一页：

soffice --headless 
  --convert-to 'pdf:calc_pdf_Export:{"PageRange":{"type":"string","value":"1"}}' 
  --outdir ./pdf 
  ./input.xlsx

这里的 JSON 参数必须作为一个完整的 shell 参数传入，所以外面用了单引号。Windows PowerShell 和 CMD 的引号规则不同，需要按实际终端调整。更复杂的参数，例如选择工作表、调整图像质量或设置 PDF/A，建议先查当前版本的过滤器文档，再用单个文件验证。

还要注意两个容易踩坑的规则：如果同一条命令里多次出现 --convert-to，只有最后一个值生效；如果多次出现 --outdir，也只有最后一个值生效。批量脚本里不要试图用多个 --convert-to 做多格式输出，分成多次调用更可靠。

编写可复用的批量转换脚本

批量脚本要解决三件事：找到输入文件、保留目录结构、记录每个文件的成功或失败。下面是一个 Bash 串行版本，适合 Linux 和 macOS。

#!/usr/bin/env bash
set -uo pipefail

SOFFICE="${SOFFICE:-soffice}"
IN_DIR="${1:-./input}"
OUT_DIR="${2:-./output}"
LOG_FILE="${3:-./convert.log}"

mkdir -p "$OUT_DIR"
: > "$LOG_FILE"

find "$IN_DIR" -type f ( -iname '*.docx' -o -iname '*.xlsx' -o -iname '*.pptx' ) -print0 |
while IFS= read -r -d '' file; do
  rel="${file#"$IN_DIR"/}"
  out_sub="$OUT_DIR/$(dirname "$rel")"
  mkdir -p "$out_sub"

  echo "[$(date '+%F %T')] converting: $file" >> "$LOG_FILE"
  if "$SOFFICE" --headless --convert-to pdf --outdir "$out_sub" "$file" >> "$LOG_FILE" 2>&1; then
    echo "[$(date '+%F %T')] OK: $file" >> "$LOG_FILE"
  else
    echo "[$(date '+%F %T')] FAILED: $file" >> "$LOG_FILE"
  fi
done

使用时替换或传入三个位置参数：

./convert.sh ./inbox ./pdf-output ./convert.log

这个脚本会递归查找 DOCX、XLSX、PPTX，并把输出放到对应的子目录中，避免不同目录下同名文件互相覆盖。如果你只想处理顶层目录，把 find 换成 for file in "$IN_DIR"/*.docx 这样的写法即可。

Windows 可以用 PowerShell 做类似事情：

$Soffice = "C:Program FilesLibreOfficeprogramsoffice.exe"
$InDir   = "C:input"
$OutDir  = "C:output"
$LogFile = "C:outputconvert.log"

New-Item -ItemType Directory -Force -Path $OutDir | Out-Null

Get-ChildItem -Path "$InDir*" -Recurse -File -Include *.docx,*.xlsx,*.pptx | ForEach-Object {
  $rel = $_.FullName.Substring($InDir.Length).TrimStart('')
  $parent = Split-Path $rel -Parent
  $outSub = if ([string]::IsNullOrEmpty($parent)) { $OutDir } else { Join-Path $OutDir $parent }
  New-Item -ItemType Directory -Force -Path $outSub | Out-Null

  "[$(Get-Date -Format 's')] converting: $($_.FullName)" | Add-Content $LogFile
  & $Soffice --headless --convert-to pdf --outdir $outSub $_.FullName *>> $LogFile

  if ($LASTEXITCODE -eq 0) {
    "[$(Get-Date -Format 's')] OK: $($_.FullName)" | Add-Content $LogFile
  } else {
    "[$(Get-Date -Format 's')] FAILED: $($_.FullName)" | Add-Content $LogFile
  }
}

如果你的机器性能足够，可能会想并行转换。LibreOffice 共用一个用户配置目录时，多个实例可能互相干扰。需要并行时，给每个进程指定独立的用户配置目录，例如：

soffice -env:UserInstallation=file:///tmp/lo-profile-1 --headless --convert-to pdf --outdir ./pdf ./a.docx &
soffice -env:UserInstallation=file:///tmp/lo-profile-2 --headless --convert-to pdf --outdir ./pdf ./b.docx &
wait

路径和并发数需要按机器情况替换。对大多数批量任务来说，串行更稳，也更容易从日志中定位是哪个文件出了问题。

转换结果如何抽查与校验

脚本返回成功，不等于每个 PDF 都符合预期。你至少要做三层检查。

第一层检查输出文件是否存在、大小是否异常：

find ./pdf-output -type f -name '*.pdf' -size -1k -print

这条命令会列出小于 1KB 的 PDF，它们很可能是空文件或转换不完整的结果。你也可以用 -size 0 专门找空文件。

第二层检查页数和文档信息。安装 Poppler 工具后可以用：

pdfinfo ./pdf-output/demo.pdf

重点看 Pages、Page size、File size 等字段。如果原文档有 30 页，PDF 只有 1 页，说明过滤器参数、分页或文件本身可能有问题。注意 pdfinfo 是否可用取决于系统，没有的话可以用其他 PDF 元数据工具替代。

第三层是人工抽查。随机打开几个 PDF，检查标题层级、表格边框、中文字体、页码和分页位置。办公文档里最常见的偏差不是“能不能转”，而是“转出来像不像”：字体替换、行距变化、表格跨页、图表错位，通常都要靠肉眼确认。

日志方面，建议把标准输出和标准错误都重定向到文件：

soffice --headless --convert-to pdf --outdir ./pdf ./demo.docx > ./convert.log 2>&1

批量脚本里则按文件追加日志。排查时优先看失败文件附近的输出，尤其是过滤器名称、参数格式、文件路径和权限相关的报错。

常见失败与排查

命令找不到。 Linux 上先确认 soffice 或 libreoffice 是否在 PATH 中；Windows 和 macOS 建议在脚本里写完整路径。路径中有空格时，PowerShell 用 & 调用，Bash 用引号包住。

转换完成但没有输出文件。 先检查 --outdir 是否存在且可写，再检查目标扩展名和过滤器名称。过滤器名称里有空格时，必须整体加引号。还要确认 shell 是否把通配符展开成了你预期的文件列表。

多个文件互相覆盖。 如果不同子目录下有同名文件，全部输出到同一个目录会覆盖。按输入目录结构创建输出子目录，或者给文件名加前缀、哈希或时间戳。

字体和版式不一致。 服务器或另一台机器缺少原文档使用的字体时，LibreOffice 会替换字体，导致换行和分页变化。解决思路是安装缺失字体、在源文档中使用通用字体，或者在目标环境中实测后再批量跑。PDF 嵌入字体和源文档字体不是一回事，导出设置也需要确认。

文件被占用或受保护。 加密文档、带密码的文档、被其他进程锁定的文件可能无法转换。先解除保护或复制出可读副本，再进入批处理流程。

并发冲突。 多个 LibreOffice 实例同时读写同一个用户配置目录时，可能出现启动失败或转换异常。串行执行最简单；需要并行时，用 -env:UserInstallation=file:///... 给每个进程独立配置目录，并控制并发数量。

大文件超时。 包含大量图片、复杂表格或嵌入对象的文件，转换时间会明显增加。脚本里可以设置超时和重试，但不要无限重试同一个明显损坏的文件。

发布或交付前的核验要点

正式把脚本交给别人使用前，先做一轮小规模闭环验证：准备 5 到 10 个有代表性的样本，覆盖 DOCX、XLSX、PPTX，包含中文、表格、图片、页眉页脚和较长文档；在目标机器上运行转换；检查日志、输出文件大小和 PDF 页数；再人工打开抽查。

同时记录你使用的 LibreOffice 版本、操作系统、命令入口、过滤器和关键参数。LibreOffice 的命令行行为会随版本变化，今天可用的过滤器名称和 JSON 参数，换一个版本可能需要调整。把版本和样本验证结果写进使用说明，比在出问题时临时猜测更省时间。

用 LibreOffice 命令行批量转换文档：headless 模式、过滤器参数与结果校验

先判断 headless 模式适不适合你的任务

安装与确认命令行入口

最小转换命令与输出目录

理解 –convert-to 的过滤器写法

编写可复用的批量转换脚本

转换结果如何抽查与校验

常见失败与排查

发布或交付前的核验要点

热门话题

WeKnora 知识框架评估：RAG、ReAct Agent 与自动 Wiki 模式适合谁

Yuxi 多租户知识智能体平台：统一 RAG、知识图谱与权限管理的落地检查

评论列表 (1条)：

延伸阅读:

从 Python 脚本到可重复执行的办公任务：配置输入目录、参数和结果检查

用 PowerRename 批量重命名照片：替换文本、添加序号并先预览结果

把收件文件变成可复核的处理流程：设计分类、字段检查与异常转人工步骤

用 Python 批量提取 PDF 指定区域文字并导出 Excel：从框选到全自动运行

用 Audacity 批量统一多段录音音量：建立处理流程并抽查导出文件