1. 为什么非要把“写文档”这件事做成一键流水线先说一个我自己的场景。平时做后端开发接口文档、技术方案、升级说明这些全是用 Markdown 写的写起来确实爽语法轻、格式干净、代码块和表格都很直观。但问题是文档最终不是给自己看的。业务方要验收文档、产品要归档材料、客户要交付报告这些人大部分用的是 Word 或者 PDF甚至有人直接甩一句“能发个 docx 吗”。于是每次写完 Markdown都要手动复制粘贴到 Word 里重新排版代码块高亮没了、表格挤成一坨、图片路径乱掉改一次格式半小时起步碰上带公式的文档更是灾难。后来我开始琢磨怎么把这条链路自动化。目标很明确写完 Markdown一条命令或者一次接口调用同时出 Word 和 PDF排版基本不乱代码和表格能正常展示而且要在公司那批老机器、老环境上跑得起来。这里的“老环境”指的就是 JDK 8——当时项目基线是 JDK 8很多在线转换工具装了要 JDK 11 或者依赖新版运行库压根没法接进服务和 CI 流程里。这套方案折腾下来核心链路是Markdown → Pandoc → docx → LibreOffice headless → PDF。全流程在 JDK 8 环境里亲测可用Windows 和 Linux 都跑过。过程里踩了不少坑尤其是中文字体、表格宽度、模板样式这几块网上资料比较零散我把自己验证过的完整方案整理出来希望对同样在搞文档自动化的人有帮助。适合这几类人来参考用 Markdown 写作但需要交付 Word/PDF 的人想把文档转换接进 Java 服务或 CI 流水线的开发以及被字体和排版问题折磨过的人。2. 工具链选型这套组合是怎么定下来的2.1 直接转 PDF 的路为什么难走最早我尝试过 Pandoc 直接转 PDF也就是 Markdown → PDF 一条路走到底。Pandoc 支持通过 LaTeX 引擎生成 PDF默认用的可能是 pdflatex、xelatex 或 lualatex。听起来挺省事实际跑起来问题一大堆首先要装完整的 TeX 发行版动辄几个 G公司内网环境装一次够呛其次中文字体要在 LaTeX 里手动配置配置错了中文全是方块再就是表格和代码块的样式控制很死板想调出符合公司文档规范的格式要写一堆 LaTeX 模板学习成本完全不值。后来也试过 Pandoc wkhtmltopdf 或者 weasyprint 的方案就是先把 Markdown 转成 HTML再用工具把 HTML 渲染成 PDF。这条路对网页布局友好但遇到长表格跨页、页眉页脚、页码这类排版需求时不够稳而且 wkhtmltopdf 对现代 CSS 的支持也有兼容问题最后输出的 PDF 效果差强人意。真正让我放弃“直接转 PDF”念头的是发现了 Pandoc 转 docx 的天然优势Pandoc 内部用 OOXML 模板渲染 Word 文档生成的 docx 结构非常干净标题层级、表格、代码块、列表都能正确映射到 Word 的原生样式。只要定制好一个 reference.docx 模板后续所有文档的字体、段落间距、标题颜色都会被这个模板接管一致性极高。2.2 先转 docx 再转 PDF 的好处既然 Pandoc 能把 Markdown 高质量转成 docx那 PDF 这步就交给专门的 Office 渲染引擎来做。我选的是 LibreOffice它的 headless 模式可以直接在命令行把 docx 转成 PDF不依赖图形界面适合服务器和 CI 环境。这套“两步走”的好处很明显第一中间产物 docx 本身就是交付物生成一次可以同时满足 Word 交付和 PDF 交付两种需求不用跑两遍流程。第二PDF 的排版完全由 docx 的样式控制而 docx 又由 Pandoc 模板控制整个链条的样式来源只有一个好维护。第三LibreOffice 对 OOXML 的兼容性在开源方案里算是最好的至少比直接用 HTML 渲染 PDF 稳得多特别是中文字体、分页、表格边框这些细节。有人会问为什么不直接用 Word 自己的 VBA 或者 COM 接口来做转换那个方案确实在 Windows 上效果最好因为本身就是 Office 在渲染。但它对环境的依赖太重必须先装完整版 Office还只能在 Windows 上跑服务器是 Linux 的话完全没法用。LibreOffice 跨平台一条命令搞定明显更符合服务端自动化的诉求。2.3 为什么不用 Apache POI 硬刚我第一反应也想过用 Apache POI 纯 Java 生成 docx因为项目本来就在 JDK 8 上POI 对 docx 的支持也相当成熟。但仔细评估后发现这条路更辛苦POI 生成 docx 相当于用代码逐段构建文档从标题、段落、表格、图片到样式设置每一步都要手写代码工作量大还能接受关键是后续维护太痛苦。文档结构一变代码跟着大改样式要调整得翻代码找对应的 XWPF 类。而且把 Markdown 解析成结构化的文档树再映射到 POI 的对象模型这中间基本上等于自己写一个 Pandoc性价比太低。所以最终架构定为Pandoc 负责解析 Markdown 并生成结构良好的 docxLibreOffice 负责将 docx 精确渲染为 PDFJava 代码只负责调度这两个外部进程。外部工具做好工具的事程序只做流程编排这个分工清晰多了。2.4 版本组合要提前锁死这套方案里版本组合非常关键。不是所有版本的 Pandoc 和 LibreOffice 都互相兼容也不是所有版本都能在 JDK 8 的机器上稳定跑。我最终锁定的版本组合如下组件版本备注JDK1.8.0_202项目基线实测兼容Pandoc2.19.22.x 系列稳定版LibreOffice7.3.7headless 模式稳定操作系统Ubuntu 20.04 / Windows Server 2019两套环境均可跑通Pandoc 2.x 的核心转换逻辑基本稳定版本选择上不用太纠结但最好不要低于 2.0因为 2.0 以后的 docx 写入器writer对样式模板的处理更完善Markdown 语法解析也更符合 CommonMark 规范。LibreOffice 7.x 系列对 OOXML 的兼容性明显好于 6.x尤其是表格样式和字体嵌入方面推荐至少用 7.0 以上。3. JDK 8 环境里装工具缺一不可的检查项3.1 JDK 8 的安装与验证虽然 Pandoc 和 LibreOffice 本身不是 Java 程序但这套流水线的调度层是我用 Java 写的所以 JDK 环境必须提前准备好。如果你是想在本地先把流程手动跑通JDK 不一定马上要用到但如果要接进服务或者写个自动化的 Java 程序JDK 8 就得先确认到位。JDK 8 的安装其实不难关键是环境变量配置容易出问题。Windows 上我习惯手动装不建议用那种“一键安装包”因为你不知道它会在系统里塞什么。从官网下载 JDK 8u202 或相近版本安装的时候记住安装路径比如C:\Program Files\Java\jdk1.8.0_202。然后配置环境变量JAVA_HOME指向 JDK 安装根目录不要带bin后缀。Path里追加%JAVA_HOME%\bin。有些老项目还要求配CLASSPATH但 JDK 8 以后其实不是必需的配了反而可能引入坑。配置完成后新开一个命令行窗口输入java -version验证。能输出版本信息且显示的是 1.8 开头就没问题。这里有个细节容易被忽略改完环境变量后已经打开的命令行窗口不会刷新环境变量必须新建窗口才能识别到。热搜里有人问“jdk环境变量配置失败”八成就是这个原因或者是Path里误用了分号和引号导致格式错误。Linux 上更简单用分发版的包管理装 OpenJDK 8 即可。比如 Ubuntu 上apt install openjdk-8-jdkDebian 系和 CentOS 系略有差异但大差不差。唯一要注意的是别装出了多个 JDK 版本命令行的java到底指向哪个版本要用update-alternatives --config java确认清楚。3.2 Pandoc 的安装与验证Pandoc 安装分平台。Windows 上最省心是用 Chocolatey 装choco install pandoc。如果公司机器不让用 choco也可以去 GitHub 下载 Windows 安装包双击安装然后命令行验证pandoc --version。注意 Pandoc 安装包有两个形态一个是便携版 exe一个是安装版建议用安装版因为便携版可能缺少某些内置的资源文件比如默认的 reference.docx。Linux 上可以用发行版自带的包管理装但版本往往偏旧。我推荐直接去 Pandoc 的 GitHub Release 页面下载对应发行版的 deb 包或 tar.gz 包。比如 Ubuntu 20.04 上下载.deb包后执行dpkg -i安装。这样版本可控不会出现“系统的 pandoc 太老Markdown 表格解析不过”之类的问题。安装完一定要验证两个点。第一是版本号pandoc --version。第二是确认它能从 stdin 读入 Markdown 并输出 docx跑一条最简单的测试命令echo # Hello | pandoc -f markdown -t docx -o test.docx如果这个命令跑不出来后面的流程就不用谈了。这一步能帮你提前发现 PATH 配置问题或者 Pandoc 安装不完整的问题。3.3 LibreOffice headless 模式LibreOffice 的安装比 Pandoc 稍微重一点但也不是大问题。Windows 上从官网下载安装包一路下一步即可。Linux 上同样用包管理或官网 deb 包。安装完要确认soffice或libreoffice命令能用不同发行版的命令名可能有差异Ubuntu 上通常是libreofficeWindows 上是soffice.exe。headless 模式这个点必须单独说。LibreOffice 默认启动是图形界面服务器环境根本没有显示器所以在命令行调用时要加--headless参数。完整的转换命令是soffice --headless --convert-to pdf --outdir /output/path /input/path/test.docx这个命令会在指定输出目录生成同名的 PDF。跑这条命令前建议先手动把某个 docx 传上去测试一下如果 PDF 能正常生成说明 LibreOffice 安装没问题可以进入下一步。我第一次在 Linux 服务器上跑这个命令时报了一堆有关缺少libXinerama之类的依赖错误后来知道是服务器没有装图形相关库把那些libx11、libxinerama、libxrandr等基础库补上就解决了。3.4 中文字体是隐藏的第一道坑这一步看起来和“文档转换”关系不大但它是整个方案里最容易让中文 PDF 变方块的一环。LibreOffice 渲染 docx 转 PDF 时字体解析依赖系统安装的字体。如果系统里没有文档指定的中文字体它就会用默认字体替代轻则排版错乱重则中文变成方框或者丢失。我踩过最大的坑是在一台精简版 Linux 上跑转换输出 PDF 的正文标题全是方块一开始以为是 Pandoc 模板的问题排查了半天最后用fc-list :langzh一看系统里一个中文字体都没有。解决办法就是先把字体装上。Debian/Ubuntu 上推荐装这几个apt install fonts-noto-cjk fonts-noto-cjk-extra fonts-wqy-zenhei装完用fc-list :langzh确认字体是否被系统识别。Windows 系统一般自带微软雅黑和宋体不需要额外装。这里建议你顺便把 Pandoc 模板里用到的主要中文字体统一指定为系统中存在的那一个避免字体名对不上。我自己的模板里是这么处理的正文用 Noto Serif CJK SC代码块用 Noto Sans Mono CJK SC标题用 Noto Sans CJK SC。这三个字体在 fonts-noto-cjk 包里都有跨平台兼容性也比较好。4. Markdown 到 Word 的转换参数设计4.1 写 Markdown 时的规范不要小看这一步。Pandoc 虽然解析能力强但 Markdown 写得不规范转换出来的 docx 同样会不听话。结合我的实践经验有四个规则强烈建议你遵守。第一标题层级从一级开始连续递增不要跳级。比如用了##就不要直接跳到####否则 Word 的导航窗格会乱目录生成也对应不上。第二代码块要标注语言比如javaPandoc 会把这个语言信息写到 docx 的代码块样式里后续模板定制时才知道怎么给不同的语言上高亮。第三表格尽量用简洁的管道语法单元格里不要塞太长的段落尤其不要用br硬换行Pandoc 对 GFMGitHub Flavored Markdown表格的支持很好但遇到复杂的合并单元格就无能为力了这种场景建议用原始 HTML 表格写Pandoc 能透传 HTML 表格。第四图片引用要使用相对路径并且保证执行转换命令时的工作目录正确否则图片资源找不到docx 里会留一个空的引用框。4.2 Pandoc 命令的核心参数单条核心命令长这样pandoc input.md \ -f markdownraw_htmlpipe_tablestex_math_dollars \ -t docx \ --reference-docreference.docx \ --toc \ --toc-depth3 \ -o output.docx这里逐个解释一下参数的作用。-f指定输入格式。markdown是 Pandoc 对 Markdown 的扩展语法后面跟的raw_html表示允许 Markdown 里嵌原始 HTMLpipe_tables是管道的表格语法tex_math_dollars是允许用$...$写 LaTeX 数学公式。这几个扩展项在实际文档里出现频率最高建议默认带上。--reference-doc是核心中的核心。它指定一个 docx 文件作为样式参考模板Pandoc 会以这个文件的样式为准来生成新的 docx。不带这个参数时Pandoc 用的是内置默认样式虽然也不错但排版风格是 Pandoc 自己的和公司文档规范基本对不上。--toc在 docx 开头生成自动目录--toc-depth3控制目录收录到三级标题。目录在 Word 里是域field打开 docx 后如果目录没刷新右键更新域即可。如果希望 PDF 里也有目录页这一步很关键因为目录最终会连同整个 docx 一起被 LibreOffice 渲染进 PDF。还有两个参数要根据场景选用。--number-sections可以自动给章节编号适合技术文档--highlight-style控制代码块的语法高亮样式可选值有pygments默认、tango、espresso、zenburn等。我个人喜欢tango颜色相对克制打出来不会太脏。4.3 定制 reference.docx 模板排版风格切换的关键不带--reference-doc的转换生成的 docx 虽然结构正确但中文字体、标题颜色、代码块底色都用的是 Pandoc 默认风格很多公司对交付文档外观有要求这一步就必须定制模板。定制方法不复杂。先在任意目录生成一个默认模板文件pandoc -o reference.docx --print-default-data-file reference.docx生成的 reference.docx 可以用 Word 打开也可以解压后直接改 XML但最方便的方式是用 Word 打开后直接改样式。打开后按下 CtrlShiftAltS 打开样式窗格然后逐个调整修改“标题 1”“标题 2”“标题 3”的字体、字号、颜色和段前段后间距。修改“正文”样式设置中文字体、西文字体、行距、首行缩进。修改“代码块”样式Pandoc 里叫“Source Code”设置等宽字体和浅灰底色。修改表格样式设置边框粗细和颜色。改完保存这个文件就成了你所有文档的统一皮肤。后续交给 Pandoc 转换时只需要引用这个模板所有生成的 docx 都会自动套用这套样式。有一点要提醒模板里不要设置具体的页边距和纸张大小之外的额外内容比如不要插入页眉页脚以外的文本框否则可能会被 Pandoc 忽略。页边距、纸张大小这类页面级设置是会被带过去的所以模板里可以一并定好 A4、上下左右边距等基础参数。4.4 图片路径与资源目录图片是 Markdown 转 Word 时最容易出问题的地方。Pandoc 处理图片的机制是把 Markdown 里引用的图片路径直接读入并嵌入 docx。因此路径必须是 Pandoc 能访问到的相对路径或绝对路径。如果图片在 Markdown 文档的images子目录里转换时工作目录放在 Markdown 所在目录写即可。不过有一个小坑如果 Markdown 文件的路径和图片相对路径跨了目录层级Pandoc 解析时会相对当前工作目录去找不在 Markdown 文件所在目录找。我的做法是执行转换前先cd到 Markdown 文件所在目录用相对路径运行 Pandoc这样最稳妥。如果是 Java 程序里调用注意 ProcessBuilder 的命令工作目录也要设成 Markdown 所在目录否则图片引用全部失效。这个坑我踩过一次最终输出 docx 里的图片全是空的查了半天才发现是工作目录的问题。另外如果图片很多且体积很大生成的 docx 会非常臃肿。Pandoc 本身不会压缩图片建议源 Markdown 里尽量用压缩过的小图尤其是图片总大小动辄几十兆的场景不压缩的 docx 传到微信里根本打不开。5. Word 到 PDF 踩过的几个真坑5.1 LibreOffice headless 命令的正确姿势Pandoc 生成 docx 后PDF 的渲染就交给soffice --headless --convert-to pdf。这个命令有几个细节必须严格遵守直接关系到转换能不能成功。第一--outdir必须放在源文件路径之前或者至少保证它不是紧随--convert-to之后有歧义。建议写全参数名避免解析问题。第二--outdir指向的目录必须已存在LibreOffice 不会帮你创建目录目录不存在时命令会静默失败。我当时找这个问题花了不少时间没有报错但 PDF 就是不出现。第三如果一次要转换多个文件可以直接用通配符或列出多个文件路径LibreOffice 支持批量转换。Linux 上还要注意如果当前用户是 rootLibreOffice 7.x 默认会拒绝以 root 身份运行 headless 转换因为 GUI 模式禁 root 的安全机制误伤到了 headless 模式。这时需要加一个环境变量-env:UserInstallationfile:///tmp/lo_profile给 LibreOffice 指定一个临时用户配置目录同时创建该目录。这个参数基本是服务器场景必加项我第一次跑 root 环境时被这个问题拦住报错内容还特抽象不看日志根本不知道是权限问题。完整的 Linux 版转换命令soffice --headless \ -env:UserInstallationfile:///tmp/lo_profile \ --convert-to pdf \ --outdir /output/path \ /input/path/output.docx5.2 表格宽度溢出是常见坑Pandoc 从 Markdown 表格生成的 docx 表格默认宽度往往超过页面正文区域尤其在表格列数多或某一列文字特别长的情况下。转换到 PDF 后表格直接溢出页边距右半部分被裁掉非常难看。这个问题我研究了很久根因有两个层面。第一Pandoc 生成表格时不一定给每列设置明确的宽度Word 在渲染时按内容自动分配宽度遇到长字符串就撑爆。第二LibreOffice 转 PDF 时对表格宽度的理解跟 Word 不完全一致同样一份 docxWord 打开自动调整了宽度但 LibreOffice 不会自动调整。解决办法是在 reference.docx 模板里提前设定好表格样式。具体做法是打开 reference.docx找到默认的表格样式把表格选项里的“自动调整窗口大小”打开并设置表格宽度为 100%。更硬核的做法是写一个 Lua filter 或者 Python filter在 Pandoc 转 docx 之前把所有表格的列宽重新计算并设置成比例宽度。如果不想碰 filter退而求其次的办法是在 Markdown 的表格前加一行|:---|:---|之类的对齐标记同时确保单元格内容不会太长能缓解一部分溢出问题。如果你愿意折腾我建议用 Pandoc 的 Lua filter 来处理表格宽度这个方案一劳永逸。写一个table-width.lua遍历表格对象把每列的相对宽度设为总宽度的比值然后用--lua-filtertable-width.lua参与转换。这样不管 Markdown 里表格多宽最终 docx 里的表格宽度都是可控的。5.3 页边距与页面尺寸要一次性定好页边距、页面尺寸这些信息最终来自 reference.docx 的文档级设置。也就是说如果 reference.docx 是 A4 纸、两边距 2.5cm、上下边距 3cm那么 Pandoc 生成的 docx 也是这个设置PDF 自然也是这个设置。这算是优点也是坑。优点是统一页面设置非常方便坑在于如果 reference.docx 没设置好比如 Word 默认的 Letter 纸型而中国习惯用 A4那么所有转换出来的 PDF 都是 Letter 尺寸打印和归档都会出问题。所以定制模板时一定别漏掉页面设置。还有页眉页脚如果要加公司 logo、页码、保密等级之类的也提前在模板里加好Pandoc 会把模板里的页眉页脚一并带过去。如果你对页码格式有要求比如“第 X 页 / 共 Y 页”这需要在 Word 域代码里写。可以直接在模板的页脚插入自动页码域Pandoc 不会动文档页脚的内容所以插一次以后就一直生效。5.4 文档内的自动目录在 PDF 里长什么样用--toc生成的 docx 目录是一个 Word 域。这个域的值不是静态文字它关联的是文档的标题结构。关键点来了Pandoc 生成的目录在 docx 打开时默认是显示上一次计算的值有时候这个值是空的。Word 打开 docx 后目录区域会显示“右键点击更新域”那是因为 Word 有自己的“打开时更新域”的逻辑。但 LibreOffice 转 PDF 时不会自动更新域如果目录域没有值PDF 里的目录页就是一片空白。这个问题我遇到过两次很坑。解决思路有两个推荐第二个。第一个思路是让 Pandoc 自己把目录内容写死到文档里但 Pandoc 目前没有直接把 toc 展开成普通文本的选项硬来的话要用 filter 或者后处理麻烦。第二个思路是利用 LibreOffice 的一个特性执行转换时增加一个选项让它更新文档里的目录域。我在 LibreOffice 7.x 里实测可以的方案是在调用soffice前先用 Python 或者宏手段操作 docx 里的w:sdt/w:fldSimple把目录域替换为静态文字。但这个方案维护成本高。更简单实际的做法是在自己可控的 Java 调度层里用 docx4j 或者 OpenXML SDKWindows 上先打开 docx强制更新所有域再保存最后交给 LibreOffice 转换。docx4j 的FieldUpdater可以专门做这件事。不过这个方案对依赖库版本要求高在 JDK 8 上我用的 docx4j 6.1.2 稳定能跑。你也可以反过来不改目录域直接在 LibreOffice 渲染完成后用 poppler 或者 PDF 编辑器处理但这就偏离了“全自动”的初衷。如果你不想引入 docx4j还有一招Pandoc 转 docx 时先不加--toc同时在 Markdown 末尾手动放一个静态的目录列表用链接跳转到标题锚点。这个方法在转换成 PDF 后目录是静态文字不会自动更新但至少不会出现空白页。我自己的正式方案是 docx4j 更新域后交给 LibreOffice线上跑了半年多稳定得很。6. 用 Java 把整条链路串成自动化服务6.1 用 ProcessBuilder 而不是 Runtime.exec前面都是手动敲命令但在服务化场景下必须用 Java 程序来调度外部进程。可能有人会图省事用Runtime.getRuntime().exec()我个人建议一律用ProcessBuilder。原因很简单exec(String)底层把命令字符串交给 shell 或者空格拆分一旦路径里带空格Windows 上直接出幺蛾子而 ProcessBuilder 支持列表形式的命令参数每个参数作为一个独立的字符串不需要转义可靠性高很多。一段最小可用的代码示例ProcessBuilder pb new ProcessBuilder( pandoc, inputPath, -f, markdownraw_htmlpipe_tablestex_math_dollars, -t, docx, --reference-doc templatePath, --toc, --toc-depth3, -o, outputPath ); pb.directory(new File(mdDir)); pb.redirectErrorStream(true); Process process pb.start(); try (BufferedReader reader new BufferedReader( new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) { String line; while ((line reader.readLine()) ! null) { log.info([pandoc] {}, line); } } int exitCode process.waitFor(); if (exitCode ! 0) { throw new RuntimeException(Pandoc 转换失败退出码: exitCode); }代码里有几个细节值得提。pb.directory()设置工作目录解决图片相对路径问题。redirectErrorStream(true)把 stderr 合入 stdout统一读取方便打日志。读取输出流一定要在waitFor()之前启动独立线程或循环读取否则外部进程的输出缓冲区满了会阻塞进程导致死锁——这个经典问题在转换大文档时特别容易触发。6.2 超时、日志与错误处理一个都不能少外部进程调用的一个特点就是不可控Pandoc 可能因为模板损坏崩溃LibreOffice 可能因为字体问题卡住。所以用 Java 调用这两个命令时必须设置超时不能无限等待。Process.waitFor(long timeout, TimeUnit unit)提供了超时等待。如果超时返回false则销毁进程树再抛异常。LibreOffice 转换大文档偶尔会跑到十几秒我习惯把超时设置成 60 秒Pandoc 一般不会超过 10 秒但保险起见统一给了 60 秒。如果业务方上传的文档可能更大你可以给 Pandoc 和 LibreOffice 分别设置不同的超时时间。日志的作用被很多人忽视。调试时最有效的日志格式是记录完整的外部命令包含参数的 List、工作目录、退出码、以及外部程序的标准输出。每次转换把这三样打出来出问题基本能一眼定位。我自己在服务里打了这样的日志格式cmd: pandoc /tmp/xxx/input.md -f markdownraw_html ... -o /tmp/xxx/output.docx workdir: /tmp/xxx exitCode: 0不要嫌日志多排障时这几行比什么都管用。我还遇到过一种情况LibreOffice 因为用户配置文件损坏导致转换异常但报错信息完全没提示后来加了-env:UserInstallation参数指定独立配置目录才绕过这也是日志之外的经验之一。6.3 性能与并发控制慢在 LibreOffice整套流水线的性能瓶颈基本都在 LibreOffice 转 PDF 这一步。Pandoc 转 docx 通常几百毫秒就完成了LibreOffice 启动并加载库文件就要花 2 到 5 秒再加上渲染时间。LibreOffice 的 headless 模式不支持并发启动多个实例或者说并发会带来不可预知的错误。多个请求同时触发转换如果都去启动 LibreOffice 进程很容易出现用户配置目录冲突、死锁、进程僵死等情况。解决办法是全局加锁把 LibreOffice 的转换过程串行化private final Semaphore libreOfficeSemaphore new Semaphore(1); public void convertToPdf(String docxPath, String pdfDir) throws Exception { libreOfficeSemaphore.acquire(); try { // 执行 soffice 命令 } finally { libreOfficeSemaphore.release(); } }这种串行化牺牲了一点并发能力但换来了稳定性对大多数内部服务绰绰有余。如果你文档量特别大可以预先启动一个常驻的 LibreOffice 实例通过 UNO 接口远程调用那样就不用每次启动进程了但复杂度明显上升我目前没有采用这个方案串行足够用。6.4 扩展思路把这条链路接进 CI 和定时任务整套方案一旦封成 Java 服务或者工具类扩展场景就多了。我目前把它接进了两处一处是 CI 流水线每次代码变更后自动把文档仓库里的 Markdown 全部转成 docx/pdf 并附到构建产物体里另一处是管理后台上传 Markdown点击“生成文档”按钮直接返回可下载的 Word 和 PDF。这两处本质上都是同一套 Java 调用逻辑只是入口不同。如果你只是个人用不想写 Java 程序也可以直接用 Shell 脚本把这套流程固化下来效果差不多无非是少了点错误处理。比如写一个md2docx-pdf.sh#!/bin/bash set -e MD_FILE$1 DIR$(dirname $MD_FILE) cd $DIR BASENAME$(basename $MD_FILE .md) pandoc $MD_FILE \ -f markdownraw_htmlpipe_tablestex_math_dollars \ -t docx \ --reference-doc/data/templates/reference.docx \ --toc --toc-depth3 \ -o $BASENAME.docx soffice --headless \ -env:UserInstallationfile:///tmp/lo_profile \ --convert-to pdf \ --outdir $DIR \ $BASENAME.docx最后再分享一个实际操作过程中很有用的点Pandoc 和 LibreOffice 不是 Java 库本质上是外部进程所以理论上你的调度层可以是任意语言。但把它放在 Java 里的优势是整个服务的依赖管理和部署可以统一到一个发布包里对运维更友好。尤其是在内网环境里服务器上没有 Python 运行时也没有 Node.js只有 JDK 8那么 Java 调度外部进程反而是最轻便的方案。以上就是这套方案的全部内容核心就是“两步走”加“模板统一风格”只要这两个关键点掌握了Markdown 一键生成 Word 加 PDF 就再也不是靠手工排版硬撑的活。
