上周有個(gè)朋友發(fā)來一份 ODT 文件說在 WPS 里轉(zhuǎn) PDF 后表格全部錯(cuò)位問我能不能寫個(gè) Python 腳本穩(wěn)定搞定。這個(gè)問題其實(shí)特別典型ODT 轉(zhuǎn) PDF 在辦公自動(dòng)化里天天遇到但很多人只會(huì)改后綴名、用在線轉(zhuǎn)換網(wǎng)站文件一多要么格式崩要么隱私泄露。我自己在幾個(gè)項(xiàng)目里折騰過各種方案踩了不少坑今天把這套實(shí)戰(zhàn)經(jīng)驗(yàn)完整捋一遍。內(nèi)容圍繞 Python 調(diào)用 LibreOffice 命令行實(shí)現(xiàn)文檔轉(zhuǎn)換也會(huì)聊到純 Python 庫(kù)的局限性、批量并發(fā)處理的正確姿勢(shì)、Web 服務(wù)里怎么用才不把進(jìn)程卡死。適合正在搭建文檔處理管線的 Python 開發(fā)者也適合辦公自動(dòng)化剛?cè)腴T、想少走彎路的朋友。真正要做的是渲染而不是改名ODT 內(nèi)部是一堆 XML 和資源文件打包成的 ZIPPDF 則是排版引擎把每個(gè)字符、圖片、表格按固定坐標(biāo)繪制出來的結(jié)果兩者之間必須有一個(gè)軟件真正打開文檔、計(jì)算分頁(yè)、導(dǎo)出 PDF。LibreOffice 就是干這個(gè)的最可靠選擇而且它提供了無需圖形界面的命令行模式非常適合被 Python 腳本調(diào)用。1. ODT 轉(zhuǎn)換 PDF 的本質(zhì)為什么看起來簡(jiǎn)單卻問題不斷1.1 改擴(kuò)展名和真正導(dǎo)出的區(qū)別先回答一個(gè)很多人問過的蠢問題把document.odt直接重命名為document.pdf會(huì)怎樣答案是不會(huì)怎樣雙擊打開 PDF 會(huì)報(bào)錯(cuò)。原因在于 ODT 和 PDF 的文件結(jié)構(gòu)完全不同。ODT 本質(zhì)是一個(gè) ZIP 壓縮包里面裝著content.xml、styles.xml、meta.xml和一堆圖片資源而 PDF 至少包含對(duì)象樹、內(nèi)容流、交叉引用表等結(jié)構(gòu)需要由渲染引擎繪制出來。可以類比成做菜ODT 是一份菜譜和一堆食材PDF 是最終端上桌的成品菜肴。重命名只是給菜譜貼了個(gè)成品的標(biāo)簽并沒有人真正烹飪。真正的轉(zhuǎn)換必須由某個(gè)軟件打開 ODT解析樣式、計(jì)算文本流的換行與分頁(yè)、確定圖片位置、處理表格寬度再調(diào)用字體渲染引擎輸出頁(yè)面。LibreOffice、OpenOffice、ONLYOFFICE 這類辦公套件內(nèi)置的就是這個(gè)能力。1.2 市面上能得到的三條路線從 Python 的角度出發(fā)想要把 ODT 轉(zhuǎn)成 PDF可選的路線大致三條調(diào)用 LibreOffice/OpenOffice 命令行最成熟、保真度最高能處理復(fù)雜的頁(yè)眉頁(yè)腳、樣式、圖表。LibreOffice 提供 headless 模式無界面后臺(tái)運(yùn)行適合服務(wù)器。用純 Python 庫(kù)解析 ODT 并自己生成 PDF比如odfpyreportlab理論上可行但實(shí)現(xiàn)成本極高只適用于極簡(jiǎn)純文本文檔。調(diào)用在線轉(zhuǎn)換 API上傳文檔然后下載結(jié)果適合不要求隱私、偶爾轉(zhuǎn)換的個(gè)人場(chǎng)景不適合批量自動(dòng)化因?yàn)榫W(wǎng)絡(luò)傳輸慢、文件大小受限、還有數(shù)據(jù)泄露風(fēng)險(xiǎn)。我的選型結(jié)論很直接只要條件是穩(wěn)定、私有化、可控就選 LibreOffice 命令行。下面所有方案都圍繞這條路展開。1.3 為什么第一個(gè)推薦是 LibreOfficeLibreOffice 是自由開源的辦公套件它的 Writer 組件原生支持 ODT 格式也就是說 ODT 是它自己的文件格式。用自己最熟悉格式的軟件去轉(zhuǎn)換錯(cuò)誤率自然最低。它提供soffice命令可以通過--headless --convert-to pdf直接批量轉(zhuǎn)換不彈窗、不需要登錄、不依賴網(wǎng)絡(luò)。GitHub 上很多文檔轉(zhuǎn)換項(xiàng)目最終都退回到這個(gè)方案道理就在這。2. 環(huán)境準(zhǔn)備Python 環(huán)境、LibreOffice 安裝和版本兼容性坑2.1 Windows 系統(tǒng)下安裝與配置Windows 下安裝 LibreOffice 很簡(jiǎn)單去官網(wǎng)下載最新安裝包安裝時(shí)一直下一步就行。安裝完成后重點(diǎn)注意soffice.exe的路徑默認(rèn)在C:\Program Files\LibreOffice\program\soffice.exe有些版本也存在于C:\Program Files (x86)\LibreOffice\program\soffice.exe。建議把這個(gè)目錄加到系統(tǒng) PATH 環(huán)境變量里否則 Python 每次調(diào)用時(shí)都要寫絕對(duì)路徑腳本換一臺(tái)機(jī)器就廢了。添加 PATH 的方式右鍵此電腦 → 屬性 → 高級(jí)系統(tǒng)設(shè)置 → 環(huán)境變量 → 在系統(tǒng)變量里找到 Path → 編輯 → 新建 → 粘貼安裝目錄 → 確定。然后在新的命令行窗口里輸入soffice --version如果顯示版本號(hào)說明配置成功。如果提示找不到命令多半是環(huán)境變量沒生效重開終端或者直接用絕對(duì)路徑。這里有個(gè)容易忽略的點(diǎn)LibreOffice 有 32 位和 64 位兩種版本但 Python 的subprocess調(diào)用并不關(guān)心位數(shù)只要系統(tǒng)能運(yùn)行對(duì)應(yīng)程序即可。不過建議和操作系統(tǒng)位數(shù)一致避免某些第三方組件不兼容。2.2 Linux 系統(tǒng)下的安裝與字體坑Linux 服務(wù)器上安裝一般用 apt/yum。Ubuntu/Debian 上我通常只安裝 Writer 組件減小體積sudo apt update sudo apt install -y libreoffice-writer如果嫌依賴解析麻煩也可以直接sudo apt install -y libreoffice會(huì)裝全家桶但磁盤占用多幾個(gè) GB。瘦身黨可以裝libreoffice-core再加libreoffice-writer不過新手還是建議裝完整版省得缺組件后排查半天。裝完檢查soffice是否符合預(yù)期which soffice通常輸出/usr/bin/soffice。Linux 上最大的坑是字體。服務(wù)器不帶圖形界面通常也不裝中文字體導(dǎo)致轉(zhuǎn)換出來的 PDF 中文全是方框或亂碼。我踩過不止一次。解決辦法是安裝中文字體包sudo apt install -y fonts-noto-cjk裝完可以用fc-list | grep -i noto驗(yàn)證。實(shí)際演示時(shí)我還專門寫過一段代碼檢查系統(tǒng)中文字體是否存在后面會(huì)給出。2.3 macOS 上的一行命令macOS 上用 Homebrew 最方便brew install --cask libreoffice安裝后可執(zhí)行文件路徑不是直接soffice而是/Applications/LibreOffice.app/Contents/MacOS/soffice建議在.zshrc里加一行 aliasalias soffice/Applications/LibreOffice.app/Contents/MacOS/soffice另外 macOS 會(huì)要求首次運(yùn)行白名單授權(quán)如果在服務(wù)器上以launchd方式跑注意給足夠權(quán)限。3. 方案一subprocess 調(diào)用 LibreOffice 命令行的完整解讀3.1 基礎(chǔ)命令結(jié)構(gòu)與參數(shù)語(yǔ)義LibreOffice 的命令行轉(zhuǎn)換核心長(zhǎng)這樣soffice --headless --convert-to pdf --outdir /output/path /input/file.odt四個(gè)關(guān)鍵參數(shù)逐一解釋--headless無頭模式不啟動(dòng)圖形界面。服務(wù)器上必須加否則會(huì)因?yàn)闆]有顯示器直接報(bào)錯(cuò)。--convert-to pdf指定輸出格式為 PDF。LibreOffice 內(nèi)置導(dǎo)入過濾器會(huì)自動(dòng)根據(jù)目標(biāo)格式調(diào)用 Writer 導(dǎo)出。--outdir /output/path指定輸出目錄。值得注意的是如果不加--outdir生成的 PDF 會(huì)放在輸入文件所在目錄并覆蓋實(shí)際測(cè)試并不會(huì)覆蓋原 ODT只是在旁邊生成同名 PDF。但為了保險(xiǎn)我始終顯式指定--outdir。/input/file.odt輸入文件完整路徑。路徑中不能有不符合編碼的字符否則轉(zhuǎn)換會(huì)靜默失敗。還可以更精細(xì)地指定 PDF 過濾器參數(shù)例如soffice --headless --convert-to pdf:writer_pdf_Export:{SelectPdfVersion:{type:long,value:17}} test.odt這段的意思是使用writer_pdf_Export過濾器并設(shè)置 PDF 版本為 1.7值為 17 表示 PDF/A-1a需要注意不同版本枚舉不同。日常轉(zhuǎn)換不需要這種級(jí)別但當(dāng)你需要控制 PDF/A 屬性、壓縮質(zhì)量、字體嵌入策略時(shí)就需要研究過濾器選項(xiàng)了。一般默認(rèn)參數(shù)已經(jīng)夠用。3.2 Python 調(diào)用代碼示例正確處理路徑、輸出和退出碼Python 里用subprocess調(diào)用時(shí)最忌諱用shellTrue拼字符串因?yàn)槁窂嚼锏目崭瘛⒅形?、引?hào)會(huì)讓命令直接卡殼。正確做法是把命令參數(shù)寫成列表由subprocess自行處理轉(zhuǎn)義import subprocess import os import sys def odt_to_pdf(input_path: str, output_dir: str) - str: input_path os.path.abspath(input_path) output_dir os.path.abspath(output_dir) os.makedirs(output_dir, exist_okTrue) cmd [ soffice, --headless, --convert-to, pdf, --outdir, output_dir, input_path ] result subprocess.run(cmd, capture_outputTrue, textTrue, timeout120) if result.returncode ! 0: raise RuntimeError(f轉(zhuǎn)換失敗: {result.returncode}\n{result.stderr}) base os.path.splitext(os.path.basename(input_path))[0] pdf_path os.path.join(output_dir, base .pdf) if not os.path.isfile(pdf_path): raise FileNotFoundError(fPDF 文件未生成: {pdf_path}) return pdf_path幾個(gè)細(xì)節(jié)說明capture_outputTrue用于捕獲 LibreOffice 的 stdout 和 stderr方便排查問題。textTrue把輸出解碼為字符串否則是 bytes。timeout120防止轉(zhuǎn)換幾十頁(yè)的大文檔時(shí)進(jìn)程掛死。如果轉(zhuǎn)換超時(shí)subprocess.run會(huì)拋出TimeoutExpired外層捕獲后應(yīng)該殺掉殘留 soffice 進(jìn)程這點(diǎn)在并發(fā)場(chǎng)景尤為重要。returncode非零時(shí)拋出異常是常規(guī)操作。但你一定會(huì)遇到returncode 為零但 PDF 沒生成的情況比如輸入文件損壞、字體缺失時(shí) LibreOffice 可能只輸出一條警告仍然返回 0。所以生成后檢查 PDF 文件是否存在非常有必要。3.3 同名文件覆蓋與特殊字符問題LibreOffice 在輸出目錄下生成與輸入 ODT 同名的 PDF。如果目標(biāo)目錄已經(jīng)存在同名 PDF新轉(zhuǎn)換會(huì)直接覆蓋舊文件不會(huì)有任何確認(rèn)提示。這個(gè)行為在批量重復(fù)轉(zhuǎn)換時(shí)反而省事但如果你希望保留歷史版本要自己在腳本里處理沖突比如按時(shí)間戳重命名。文件名里如果帶有、(,),[,],#等特殊字符subprocess 列表形式不會(huì)有問題因?yàn)闆]經(jīng)過 shell 解析。但如果路徑里包含非 UTF-8 編碼的字符比如從某個(gè)舊 Windows 系統(tǒng)拷過來的 GBK 文件名Python 側(cè)就可能先報(bào)編碼錯(cuò)誤這通常不是 LibreOffice 的問題而是操作系統(tǒng)文件名編碼不統(tǒng)一。生產(chǎn)環(huán)境中最好在入庫(kù)時(shí)就把文件名統(tǒng)一成 ASCII 或規(guī)范 UTF-8。3.4 高頻典型問題用戶配置文件鎖導(dǎo)致的間歇性失敗這個(gè)坑幾乎每個(gè)用 LibreOffice 做并發(fā)的團(tuán)隊(duì)都會(huì)遇到。LibreOffice 首次啟動(dòng)會(huì)創(chuàng)建一個(gè)用戶配置文件目錄Windows 在%APPDATA%\LibreOffice\4\userLinux 在~/.config/libreoffice/4/user。當(dāng)你連續(xù)調(diào)用好幾個(gè)soffice進(jìn)程時(shí)它們會(huì)爭(zhēng)搶這個(gè)配置文件導(dǎo)致報(bào)錯(cuò)信息類似Error: source file could not be loaded或者The lock file ... already exists, another LibreOffice process is using it實(shí)際上文件本身沒問題純粹是并發(fā)沖突。解決辦法是在每次調(diào)用時(shí)給 LibreOffice 一個(gè)獨(dú)立的臨時(shí)配置目錄soffice -env:UserInstallationfile:///tmp/lo_profile_123 --headless --convert-to pdf ...這樣每個(gè)進(jìn)程用獨(dú)立的 profile互不干擾。Python 里可以用進(jìn)程 ID 或隨機(jī)字符串拼一個(gè)唯一路徑import tempfile profile_dir tempfile.mkdtemp(prefixlo_profile_) cmd [ soffice, f-env:UserInstallationfile://{profile_dir}, --headless, --convert-to, pdf, --outdir, output_dir, input_path ]用完最好把臨時(shí)目錄回收。后面講并發(fā)時(shí)還會(huì)專門說。4. 方案二純 Python 庫(kù)方案為什么不可靠——從一個(gè) content.xml 實(shí)驗(yàn)講起4.1 ODT 內(nèi)部結(jié)構(gòu)長(zhǎng)什么樣為了說清楚純 Python 方案的局限我直接解壓一個(gè) ODT 文件看看內(nèi)部結(jié)構(gòu)unzip -l sample.odt典型輸出包含mimetype content.xml styles.xml meta.xml settings.xml Pictures/1.png manifest.rdf META-INF/manifest.xml其中content.xml是正文和大部分內(nèi)容所在styles.xml保存樣式定義Pictures/是嵌入的圖片。我們可以用 Python 的zipfile讀取content.xmlimport zipfile from lxml import etree with zipfile.ZipFile(sample.odt) as z: with z.open(content.xml) as f: root etree.fromstring(f.read()) text_parts root.findall(.//{urn:oasis:names:tc:opendocument:xmlns:text}1.0/p)如果文檔只有幾段普通文字你會(huì)得到清晰的text:p列表。這給了很多新手一種錯(cuò)覺把text:p里的文本提取出來用reportlab一行行畫到 PDF 不就行了4.2 解析 XML 自己畫 PDF 的五個(gè)致命傷真正動(dòng)手后會(huì)發(fā)現(xiàn)任何非平凡文檔都會(huì)讓這個(gè)方案崩盤樣式繼承ODT 的文本樣式通過text:span text:style-nameT1引用樣式表中定義的字體、字號(hào)、顏色、縮進(jìn)而樣式表又有段落樣式、字符樣式、表格樣式、頁(yè)面樣式四層。要完整復(fù)現(xiàn)等于重寫一個(gè)排版引擎。字體度量PDF 繪制文本必須知道每個(gè)字符的寬度才能計(jì)算自動(dòng)換行和對(duì)齊。你需要讀取系統(tǒng)字體計(jì)算每個(gè)字形寬度并處理中英文混排時(shí)的基線對(duì)齊。分頁(yè)計(jì)算ODT 文檔流是動(dòng)態(tài)分頁(yè)的段落前后的分頁(yè)符、表格行跨頁(yè)、頁(yè)眉頁(yè)腳跟隨頁(yè)面樣式變化。純規(guī)則引擎很難處理 keep-next 這類 Word 處理習(xí)慣的段落控制屬性。圖片位置正文中的浮動(dòng)圖片、錨定段落、環(huán)繞模式全都需要模擬 Writer 的排版邏輯。表格寬度ODT 表格列寬可以使用絕對(duì)單位、相對(duì)百分比、甚至自適應(yīng)內(nèi)容。真實(shí)世界里的表格幾乎都有復(fù)雜跨行、跨列、合并單元格純 XML 遍歷處理會(huì)寫到你懷疑人生。結(jié)論很明確除非文檔是你自己程序生成的、結(jié)構(gòu)極度受控的純文本 ODT否則不要用純 Python 庫(kù)轉(zhuǎn) PDF。這不是 Python 不行而是 Office 排版引擎本身就是巨大的工程。4.3 什么場(chǎng)景下純庫(kù)方案反而合適當(dāng)然純庫(kù)方案并非一無是處。如果你處理的文檔是程序自動(dòng)生成的比如導(dǎo)出訂單、發(fā)票、通知函正文只有標(biāo)題、段落、一個(gè)簡(jiǎn)單表格且你已經(jīng)完全了解 ODT 的結(jié)構(gòu)那么用odfpy讀取內(nèi)容再用reportlab生成 PDF響應(yīng)速度會(huì)更快也不會(huì)依賴服務(wù)器上安裝 LibreOffice。我的經(jīng)驗(yàn)是凡是一次性轉(zhuǎn)換用戶上傳的任意 ODT 文件都不要碰純庫(kù)方案凡是你自己模板生成的 ODT數(shù)量大、格式固定純庫(kù)也許是愛。但現(xiàn)實(shí)里為了一個(gè)純文本模塊去維護(hù)兩套渲染邏輯后期成本很高。我最終還是在項(xiàng)目中統(tǒng)一回退到 LibreOffice。5. 方案三Windows 沒有 LibreOffice 時(shí)的曲線救國(guó)——ODT 轉(zhuǎn) DOCX 再轉(zhuǎn) PDF5.1 用 win32com 調(diào) Word 直接打開 ODT 的局限性有些公司只給開發(fā)機(jī)裝了 Microsoft Office不允許再裝 LibreOffice。此時(shí)很多同事會(huì)想著用pywin32調(diào) Word 的 COM 接口處理轉(zhuǎn)換import win32com.client import os def convert_odt_to_pdf_with_word(input_path, output_path): word win32com.client.Dispatch(Word.Application) word.Visible False doc word.Documents.Open(input_path) doc.SaveAs2(output_path, FileFormat17) # 17 表示 wdFormatPDF doc.Close() word.Quit()這個(gè)方案確實(shí)能跑通但我要說實(shí)話Word 打開 ODT 的兼容性并不好。普通的文本、圖片問題不大可一旦遇到 LibreOffice 特有的樣式屬性、頁(yè)面設(shè)置、表格邊框Word 渲染結(jié)果經(jīng)常和原文件有差異。更麻煩的是 COM 調(diào)用要求機(jī)器上有完整的 Office 許可、不允許無頭運(yùn)行服務(wù)器上還會(huì)彈出奇怪的交互對(duì)話框。若非不得已不推薦。5.2 橋接五次不如原生一次為什么還是建議裝 LibreOffice也有人推出一個(gè)橋接思路先用 LibreOffice——等等既然你都裝了 LibreOffice為什么不直接轉(zhuǎn) PDF所以這個(gè)思路本質(zhì)上只在一種情況下成立你手頭既有 Word 又要保留可編輯的 DOCX需要先轉(zhuǎn)換格式再交給 Word 做二次處理。但中間轉(zhuǎn)兩次格式必然會(huì)損失部分細(xì)節(jié)浪費(fèi)的時(shí)間和空間也不值得。我在實(shí)際項(xiàng)目里的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果服務(wù)器允許安裝開源軟件優(yōu)先裝 LibreOffice一步到位只有當(dāng)你確定客戶環(huán)境絕對(duì)不允許安裝任何額外辦公套件、且所有 ODT 文檔都是簡(jiǎn)單格式時(shí)才考慮win32com調(diào) Word。前者穩(wěn)定可控后者看人品。5.3 其他跨平臺(tái)替代工具ONLYOFFICE 和 Calligra 值得一提除了 LibreOfficeONLYOFFICE Desktop Editors 也支持 ODT 轉(zhuǎn) PDF而且它的排版引擎在網(wǎng)頁(yè)協(xié)作場(chǎng)景表現(xiàn)不錯(cuò)。Calligra 是 KDE 社區(qū)的辦公套件但成熟度相對(duì)一般。服務(wù)器自動(dòng)化領(lǐng)域LibreOffice 依然是命令接口最完整、文檔最多、坑最少的選擇。OpenOffice 大家也常用但它的無頭模式 API 更老新版本不開源支持下更新緩慢。除非公司強(qiáng)依賴 OpenOffice 的 UNO 擴(kuò)展否則沒必要繞遠(yuǎn)。6. 實(shí)戰(zhàn)包含圖片、表格、頁(yè)眉頁(yè)腳的復(fù)雜 ODT 轉(zhuǎn)換與異常排查6.1 準(zhǔn)備一個(gè)帶料的測(cè)試文檔并跑通為了驗(yàn)證方案的可靠性我特意用 LibreOffice Writer 創(chuàng)建了一個(gè)測(cè)試文檔test_complex.odt里面包含一個(gè)三行兩列的表格其中一格跨兩列、一張嵌入圖片、打印樣式的頁(yè)眉和頁(yè)腳、標(biāo)題下面的一個(gè)無序列表。然后在虛擬環(huán)境里執(zhí)行python -c from converter import odt_to_pdf; print(odt_to_pdf(test_complex.odt, out/))輸出/abs/path/out/test_complex.pdfPDF 打開后頁(yè)眉頁(yè)腳完整圖片居中表格邊框無溢出。這個(gè)結(jié)果說明--convert-to pdf默認(rèn)導(dǎo)出已經(jīng)足夠處理大部分辦公文檔。真正復(fù)雜的部分往往不是轉(zhuǎn)換本身而是異常處理。6.2 生產(chǎn)級(jí)函數(shù)超時(shí)、臨時(shí) Profile、錯(cuò)誤號(hào)一個(gè)都不能少我整理了一份在多個(gè)項(xiàng)目里用過的生產(chǎn)級(jí)函數(shù)。它比上面的基礎(chǔ)版多了四件事獨(dú)立臨時(shí)配置目錄、超時(shí)后清理進(jìn)程、返回碼非零時(shí)打印完整 stderr、生成文件后校驗(yàn)大小非零。import os import shutil import subprocess import tempfile def odt_to_pdf_pro(input_path: str, output_dir: str, timeout: int 180) - str: input_path os.path.abspath(input_path) output_dir os.path.abspath(output_dir) os.makedirs(output_dir, exist_okTrue) profile_dir tempfile.mkdtemp(prefixlo_profile_) try: cmd [ soffice, f-env:UserInstallationfile://{profile_dir}, --headless, --norestore, --convert-to, pdf, --outdir, output_dir, input_path ] proc subprocess.run( cmd, capture_outputTrue, textTrue, timeouttimeout ) except subprocess.TimeoutExpired as e: # 超時(shí)后嘗試清理殘余進(jìn)程 subprocess.run([pkill, -f, profile_dir], capture_outputTrue) raise RuntimeError(f轉(zhuǎn)換超時(shí): {input_path}) from e except FileNotFoundError as e: raise RuntimeError(找不到 soffice是否安裝 LibreOffice 并配置 PATH?) from e finally: shutil.rmtree(profile_dir, ignore_errorsTrue) if proc.returncode ! 0: raise RuntimeError( fLibreOffice 返回碼 {proc.returncode}: {proc.stderr} ) base os.path.splitext(os.path.basename(input_path))[0] pdf_path os.path.join(output_dir, base .pdf) if not os.path.isfile(pdf_path) or os.path.getsize(pdf_path) 0: raise RuntimeError(fPDF 未生成或大小為 0: {pdf_path}) return pdf_path幾個(gè)小細(xì)節(jié)--norestore防止 LibreOffice 恢復(fù)上次未保存的文檔彈窗pkill -f profile_dir用于殺殘留進(jìn)程最后檢查文件大小非零很多靜默失敗能在這里被攔截。6.3 字體缺失導(dǎo)致整頁(yè)方塊的真實(shí)案例有次我在一臺(tái)干凈的 Debian 服務(wù)器上跑批量轉(zhuǎn)換所有中文文本轉(zhuǎn)出來都是□□□。逐個(gè)排查后發(fā)現(xiàn)服務(wù)器上沒有任何中文字體。fc-list輸出里只有幾個(gè) DejaVu 字體而 DejaVu 不含中文字形。裝好fonts-noto-cjk后重新轉(zhuǎn)換中文恢復(fù)正常。這類問題最坑的地方在于LibreOffice 不會(huì)因?yàn)槿弊煮w而報(bào)錯(cuò)它只是找一個(gè)能用的字體替代替代不了就畫方框。所以轉(zhuǎn)換后的 PDF 必須做可視化抽查或至少抽樣驗(yàn)證文本內(nèi)容長(zhǎng)度。如果必須自動(dòng)化檢查可以用pdftotext抽文本pdftotext out.pdf - | wc -l對(duì)比源文檔的文本量能發(fā)現(xiàn)約八成缺字問題。7. 批量與并發(fā)轉(zhuǎn)換把腳本從能用升級(jí)到抗打7.1 批量轉(zhuǎn)換的基本框架glob 失敗清單第一步先把單個(gè)轉(zhuǎn)換擴(kuò)展成掃目錄全部轉(zhuǎn)換同時(shí)保留失敗清單不要因?yàn)橐粋€(gè)壞文件中斷整個(gè)任務(wù)from pathlib import Path def batch_convert(input_dir: str, output_dir: str): input_dir Path(input_dir) output_dir Path(output_dir) errors [] for odt_path in input_dir.glob(*.odt): try: pdf_path odt_to_pdf_pro(str(odt_path), str(output_dir)) print(fOK: {odt_path.name} - {Path(pdf_path).name}) except Exception as e: errors.append((odt_path.name, str(e))) print(fFAIL: {odt_path.name}: {e}) print(f完成成功 {len(list(input_dir.glob(*.odt))) - len(errors)}失敗 {len(errors)} 個(gè)) return errors如果要遍歷子目錄把glob(*.odt)改成rglob(*.odt)。7.2 concurrent.futures 做并發(fā)時(shí)必踩的連環(huán)坑很多人寫完串行版本嫌慢就上了ThreadPoolExecutor。結(jié)果發(fā)現(xiàn)要么崩潰要么報(bào) profile 鎖錯(cuò)誤。核心原因前面提過LibreOffice 的默認(rèn)用戶配置目錄只有一個(gè)多個(gè)進(jìn)程同時(shí)寫會(huì)沖突。解決方案有三個(gè)層級(jí)方案 A完全不并發(fā)串行跑。文件不多時(shí)最簡(jiǎn)單不會(huì)出問題。 方案 B限制并發(fā)數(shù)為 1本質(zhì)還是串行但用線程池統(tǒng)一管理超時(shí)與異常。 方案 C真正的并發(fā)每個(gè)子進(jìn)程都指定獨(dú)立的-env:UserInstallation臨時(shí)目錄讓每個(gè)進(jìn)程擁有獨(dú)立 profile。經(jīng)過測(cè)試并發(fā)數(shù)控制在 2~4 時(shí)CPU 和內(nèi)存收益最現(xiàn)實(shí)數(shù)量再多容易內(nèi)存爆炸。代碼示例from concurrent.futures import ThreadPoolExecutor, as_completed def convert_one(item): return odt_to_pdf_pro(item, output_dir) with ThreadPoolExecutor(max_workers4) as executor: futures {executor.submit(convert_one, str(p)): p for p in input_dir.glob(*.odt)} for future in as_completed(futures): try: pdf future.result() print(成功:, Path(pdf).name) except Exception as e: print(失敗:, futures[future].name, e)注意真正的瓶頸通常在內(nèi)存。每個(gè) soffice 進(jìn)程大約占用 200~400MB 內(nèi)存4 并發(fā)就是 1.6GB服務(wù)器只有 2GB 內(nèi)存時(shí)建議 max_workers2。7.3 在 Web 服務(wù)里避免同步阻塞和后端超時(shí)如果只是寫腳本subprocess.run阻塞沒什么問題。但放到 FastAPI 或 Flask 接口里直接同步調(diào)用會(huì)讓請(qǐng)求線程干等一個(gè) 180 秒的轉(zhuǎn)換。正確姿勢(shì)是使用線程池把轉(zhuǎn)換任務(wù)放到后臺(tái)執(zhí)行并限制并發(fā)數(shù)量。最簡(jiǎn)單的示例from fastapi import FastAPI, File, UploadFile from concurrent.futures import ThreadPoolExecutor app FastAPI() pool ThreadPoolExecutor(max_workers2) app.post(/convert/odt-to-pdf) async def convert_odt(file: UploadFile): content await file.read() # 保存臨時(shí)文件調(diào)用 pool.submit(odt_to_pdf_pro, ...) # 返回一個(gè) task_id前端輪詢?nèi)蝿?wù)狀態(tài)真正的生產(chǎn)項(xiàng)目里我一般不會(huì)直接在 Web 進(jìn)程內(nèi)跑 LibreOffice而是把任務(wù)丟給 Celery/Redis 隊(duì)列由獨(dú)立 worker 進(jìn)程去轉(zhuǎn)換避免 Web 服務(wù)器被打垮。如果業(yè)務(wù)量不大用線程池加信號(hào)量也夠用關(guān)鍵是千萬不要用os.system同步調(diào)用否則用戶請(qǐng)求線程全卡在等待上。7.4 日志、重試和統(tǒng)計(jì)的工程化套路工程化腳本還要加日志。核心信息包括輸入文件路徑、輸出路徑、耗時(shí)、返回碼、stderr 前 500 字符。出現(xiàn)失敗時(shí)自動(dòng)重試一次等待 2 秒如果仍然失敗記入錯(cuò)誤清單。import logging, time logger logging.getLogger(odt_converter) def convert_with_retry(path, output_dir, retries2): for i in range(retries): try: start time.time() pdf odt_to_pdf_pro(path, output_dir) logger.info(轉(zhuǎn)成功 %s - %s 耗時(shí) %.2fs, path, pdf, time.time()-start) return pdf except Exception as e: logger.warning(第 %d 次嘗試失敗 %s: %s, i1, path, e) time.sleep(2) raise RuntimeError(f重試后仍失敗: {path})日志文件名建議按天滾動(dòng)不然生產(chǎn)環(huán)境日志會(huì)巨大。8. 錯(cuò)誤速查表與我的最后幾點(diǎn)私貨8.1 高頻錯(cuò)誤速查對(duì)照表把幾年里遇到的典型錯(cuò)誤整理成了表格方便直接查報(bào)錯(cuò)現(xiàn)象可能原因解決方案soffice: command not foundLibreOffice 未安裝或 PATH 未配置正確安裝并配置 PATH或調(diào)用絕對(duì)路徑Error: source file could not be loaded輸入文件損壞、路徑編碼異常、實(shí)際不是 ODT檢查文件能正常用 Writer 打開統(tǒng)一文件名為 UTF-8return code 77缺系統(tǒng)基礎(chǔ)庫(kù)或字體安裝字體與依賴如libreoffice-gtk3或fonts-noto-cjk報(bào) profile lock 錯(cuò)誤多進(jìn)程并發(fā)共用用戶配置目錄每個(gè)調(diào)用使用獨(dú)立-env:UserInstallation轉(zhuǎn)換完成但 PDF 是空白的ODT 文檔內(nèi)容異常、或者過濾參數(shù)錯(cuò)誤手動(dòng)打開確認(rèn)文檔正常取消自定義過濾器參數(shù)中文全部是方框服務(wù)器缺少中文字體apt install fonts-noto-cjk或部署中文字體文件Python 報(bào)編碼 UnicodeDecodeError文件或 stdout 編碼不兼容 Windows使用textFalse然后按 utf-8 容錯(cuò)解碼轉(zhuǎn)換耗時(shí)很長(zhǎng)且 CPU 100%文檔含大量高清圖片或復(fù)雜表格考慮限制圖片導(dǎo)出分辨率doc 中圖片壓縮后再轉(zhuǎn)這個(gè)表不是萬能藥但覆蓋了 90% 的日常報(bào)錯(cuò)。8.2 我最后想說的幾句實(shí)在話搞了幾年文檔轉(zhuǎn)換最有價(jià)值的教訓(xùn)就是不要一開始就追求并發(fā)和花哨的庫(kù)先把最小的串行鏈路跑通再不斷加防護(hù)。LibreOffice 是這里面最普通卻最可靠的工具它沒有 Python 生態(tài)那種亮眼包裝但一個(gè)soffice命令穩(wěn)定得可怕。如果你在處理 ODT 轉(zhuǎn)換時(shí)遇到格式錯(cuò)亂先別急著改代碼打開 LibreOffice 人工轉(zhuǎn)一次。如果人工也一樣亂那問題就在源文檔本身不在腳本。如果人工正常而腳本生成的 PDF 亂再檢查字體和profile 鎖也不遲。另外轉(zhuǎn)換速度真的和機(jī)器性能關(guān)系極大。小文檔 1 秒內(nèi)出結(jié)果帶幾十張高清圖的文檔可能要 10 秒。批量任務(wù)上不要盲目設(shè) 120 秒超時(shí)可以按文檔大小乘以 5 再加 20 秒來動(dòng)態(tài)計(jì)算。我的項(xiàng)目中一般做成可配置參數(shù)默認(rèn) 180 秒。最后分享一個(gè)小技巧如果你需要轉(zhuǎn)換的 ODT 是從網(wǎng)上銀行、政府系統(tǒng)導(dǎo)出的里面常帶數(shù)字簽名和只讀保護(hù)。LibreOffice 默認(rèn)模式會(huì)提示輸入密碼或跳過受保護(hù)區(qū)域。這時(shí)在命令里加一個(gè)--writer參數(shù)指定文檔類型可以繞開部分保護(hù)彈窗。具體寫法是soffice --headless --writer --convert-to pdf --outdir ...。遇到導(dǎo)入時(shí)彈密碼框的文檔不妨試試這個(gè)組合能免去不少人工介入。