簡(jiǎn)介在數(shù)字化業(yè)務(wù)系統(tǒng)中PDF轉(zhuǎn)圖片是最常見(jiàn)的文檔處理需求之一無(wú)論是合同預(yù)覽、電子簽章存檔還是OA附件在線(xiàn)查看都依賴(lài)將PDF頁(yè)面渲染為位圖。理解PDF內(nèi)部矢量存儲(chǔ)與DPI每英寸點(diǎn)數(shù)的關(guān)系是掌握渲染原理的關(guān)鍵通過(guò)調(diào)整DPI可以靈活控制輸出圖片的清晰度與體積。開(kāi)源的PDFium引擎作為Chrome內(nèi)置的渲染器憑借BSD寬松協(xié)議和優(yōu)秀的渲染質(zhì)量成為跨平臺(tái)PDF處理的首選底層引擎。PdfiumLib則進(jìn)一步將其封裝為.NET友好的接口讓C#開(kāi)發(fā)者能夠輕松實(shí)現(xiàn)高性能的PDF轉(zhuǎn)圖片功能同時(shí)兼顧Windows、Linux與macOS等不同環(huán)境。本文從基礎(chǔ)概念出發(fā)結(jié)合工程實(shí)踐詳細(xì)講解基于PdfiumLib的完整實(shí)現(xiàn)方案包括參數(shù)配置、批量轉(zhuǎn)換、內(nèi)存優(yōu)化及常見(jiàn)問(wèn)題排查為需要落地PDF轉(zhuǎn)圖片功能的團(tuán)隊(duì)提供可直接參考的路徑。 現(xiàn)在很多業(yè)務(wù)系統(tǒng)里都繞不開(kāi)一個(gè)需求把PDF轉(zhuǎn)成圖片。無(wú)論是合同預(yù)覽、電子簽章存檔還是OA系統(tǒng)里的附件在線(xiàn)預(yù)覽PDF轉(zhuǎn)圖片都是最務(wù)實(shí)的一種實(shí)現(xiàn)方式。我之前在.Net Framework時(shí)代常用的是各種付費(fèi)組件后來(lái)切到.Net Core之后發(fā)現(xiàn)很多老組件都不再維護(hù)找了一圈開(kāi)源方案最后被PdfiumLib這個(gè)項(xiàng)目穩(wěn)住了。這篇文章就把我基于PdfiumLib實(shí)現(xiàn)PDF轉(zhuǎn)圖片的完整經(jīng)驗(yàn)整理出來(lái)里面包含了選型對(duì)比、踩坑記錄和可以直接抄走的代碼。1. 項(xiàng)目概述與方案選型分析1.1 為什么選PdfiumLib幾個(gè)主流方案的真實(shí)對(duì)比我在接手這個(gè)需求時(shí)先列了一下市面上可選的方案基本是這幾類(lèi)方案底層實(shí)現(xiàn)授權(quán)模式跨平臺(tái)能力維護(hù)活躍度Ghostscript自研PostScript/PDF解釋器AGPL商用需購(gòu)買(mǎi)商業(yè)許可支持Windows/Linux/macOS很活躍Adobe PDF LibraryAdobe官方商業(yè)付費(fèi)價(jià)格昂貴支持主流平臺(tái)穩(wěn)定Aspose.Pdf自研渲染引擎商業(yè)付費(fèi)支持主流平臺(tái)很活躍PDFiumGoogle開(kāi)源Chrome內(nèi)置BSD-3支持Windows/Linux/macOS/Android/iOS很活躍PdfiumLib基于PDFium的.NET封裝Apache-2.0支持.NET Framework/Core中等活躍選型時(shí)最核心的考量就兩條渲染質(zhì)量能不能保證、授權(quán)會(huì)不會(huì)有坑。Ghostscript渲染質(zhì)量確實(shí)不錯(cuò)但AGPL協(xié)議對(duì)商用項(xiàng)目不友好除非你愿意把整個(gè)應(yīng)用源碼開(kāi)源或者花錢(qián)買(mǎi)商業(yè)許可。Adobe PDF Library質(zhì)量最好但價(jià)格也最高中小項(xiàng)目很少愿意承擔(dān)這個(gè)成本。Aspose.Pdf功能全但按年付費(fèi)的模式也讓很多團(tuán)隊(duì)猶豫。而PDFium是Google為Chrome內(nèi)置的PDF渲染引擎BSD-3協(xié)議非常寬松沒(méi)有傳染性可以自由商用。渲染質(zhì)量經(jīng)過(guò)Chrome瀏覽器海量用戶(hù)驗(yàn)證足夠可靠。唯一的痛點(diǎn)是沒(méi)有官方維護(hù)的.NET綁定需要自己P/Invoke調(diào)用C接口。PdfiumLib正是在這個(gè)基礎(chǔ)上做了一層封裝把C API包裝成了C#友好的接口同時(shí)保持了底層引擎的能力。1.2 理解PdfiumLib的底層架構(gòu)為什么它能做到輕量高效PdfiumLib本質(zhì)上不是一個(gè)從零開(kāi)發(fā)的渲染引擎而是PDFium引擎的.NET橋接層。PDFium是Google用C實(shí)現(xiàn)的整個(gè)代碼庫(kù)非常龐大包含了PDF解析、頁(yè)面渲染、文字提取、表單填充等能力。PdfiumLib通過(guò)P/Invoke技術(shù)把這些C接口暴露給托管代碼其中最重要的接口就是渲染相關(guān)的FPDF_GetPage、FPDF_RenderPageBitmap、FPDFDocument_RenderPageBitmap。在.NET Core/5時(shí)代這個(gè)封裝的價(jià)值更加明顯。因?yàn)镻DFium本身是原生代碼通過(guò)P/Invoke調(diào)用時(shí)只要目標(biāo)平臺(tái)上存在對(duì)應(yīng)的原生動(dòng)態(tài)庫(kù)就可以正常工作。PdfiumLib針對(duì)不同平臺(tái)提供了對(duì)應(yīng)的庫(kù)文件Windows下是pdfium.dllLinux下是libpdfium.somacOS下是libpdfium.dylib這讓同一套C#代碼可以跨平臺(tái)運(yùn)行不需要為不同操作系統(tǒng)維護(hù)不同的邏輯。我這里補(bǔ)充一下PdfiumLib的NuGet包有兩種形態(tài)一種是PdfiumViewer它包含了WinForms的PDF查看器控件和底層文檔操作API另一種是PdfiumLib的最新版本它可以運(yùn)行在.NET Core/.NET 5環(huán)境下。我實(shí)際使用的是PdfiumViewer這個(gè)包它雖然名字里帶Viewer但核心的PdfDocument類(lèi)完全可以脫離UI控件單獨(dú)使用只做渲染不顯示界面這是很多人在初次接觸時(shí)容易忽略的點(diǎn)。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 關(guān)鍵概念DPI和頁(yè)面像素尺寸怎么算PDF轉(zhuǎn)圖片最核心的一個(gè)概念就是DPIDots Per Inch。PDF內(nèi)部存儲(chǔ)的是矢量數(shù)據(jù)理論上可以無(wú)損輸出到任意分辨率的圖片上。渲染時(shí)指定的DPI越高輸出的圖片像素越大細(xì)節(jié)越清晰同時(shí)內(nèi)存和CPU消耗也越高。我們?cè)陂_(kāi)發(fā)時(shí)通常會(huì)選一個(gè)基礎(chǔ)DPI作為基準(zhǔn)值然后按需縮放。常見(jiàn)的選擇是96因?yàn)閃indows下屏幕邏輯DPI是96按照這個(gè)值渲染出來(lái)的圖片在普通屏幕上正好是1:1顯示也就是PDF頁(yè)面的一個(gè)點(diǎn)對(duì)應(yīng)屏幕上的一個(gè)像素。像素尺寸的計(jì)算公式非常簡(jiǎn)單寬 頁(yè)面寬度(英寸) × DPI 高 頁(yè)面高度(英寸) × DPI舉例一張A4紙寬度是8.27英寸高度是11.69英寸。如果以96 DPI渲染輸出圖片尺寸就是794×1123像素如果以200 DPI渲染就是1654×2346像素。這里要注意PDF頁(yè)面尺寸的單位通常不是英寸而是點(diǎn)Point1 Point 1/72英寸。所以A4紙的實(shí)際尺寸是595×842 Points。計(jì)算像素時(shí)可以先統(tǒng)一單位即先除以72換算成英寸再乘以DPI。PdfiumViewer的PdfDocument.Render方法接收一個(gè)PdfRenderParams參數(shù)其中的DpiX和DpiY就是控制分辨率的。這個(gè)API設(shè)計(jì)得比較簡(jiǎn)單粗暴直接傳x和y方向的DPI值。需要注意的是PdfRenderParams里還有一個(gè)Size屬性這個(gè)Size會(huì)和DPI互相影響我下面細(xì)講。2.2 渲染參數(shù)的組合邏輯DPI和Size的優(yōu)先級(jí)問(wèn)題在實(shí)際調(diào)用Render方法時(shí)如果同時(shí)指定了Size和DpiX/DpiY系統(tǒng)會(huì)以Size為準(zhǔn)忽略部分DPI的影響。這個(gè)行為很容易讓人踩坑我也是在多次測(cè)試后才徹底搞清楚的。具體的邏輯是這樣的PdfRenderParams傳入Size后渲染器會(huì)直接把頁(yè)面按這個(gè)尺寸進(jìn)行繪制DPI只是作為一個(gè)附加信息傳入并不會(huì)影響輸出尺寸。換句話(huà)說(shuō)如果你傳入Size為500×400那輸出就是500×400的圖不管DPI設(shè)成96還是300。如果你不傳Size或者傳入Size.Empty渲染器就會(huì)根據(jù)DPI來(lái)計(jì)算尺寸。這時(shí)DPI才真正起作用。所以我的建議是做PDF轉(zhuǎn)圖片時(shí)優(yōu)先控制DPI不要傳Size讓渲染器自動(dòng)計(jì)算像素尺寸。這樣行為最可預(yù)期語(yǔ)義也清晰。只有在需要強(qiáng)制輸出成固定尺寸比如生成縮略圖時(shí)才手動(dòng)指定Size。這個(gè)細(xì)節(jié)很重要因?yàn)楹芏嗳嗽诰W(wǎng)上抄代碼時(shí)看到別人傳了Size自己也跟著傳結(jié)果發(fā)現(xiàn)輸出圖片尺寸不對(duì)還以為是DPI沒(méi)生效其實(shí)是這兩個(gè)參數(shù)的關(guān)系沒(méi)搞清楚。2.3 渲染質(zhì)量的關(guān)鍵抗鋸齒和圖像格式PdfiumLib的渲染質(zhì)量總體來(lái)說(shuō)是不錯(cuò)的但默認(rèn)渲染質(zhì)量在某些操作系統(tǒng)或某些PDF內(nèi)容上可能會(huì)顯得邊緣有點(diǎn)鋸齒。PdfiumViewer在Render方法中提供了一個(gè)Flags參數(shù)可以傳入一些渲染標(biāo)志位來(lái)優(yōu)化輸出質(zhì)量。常見(jiàn)的標(biāo)志位有標(biāo)志含義RenderFlags.LCDText使用LCD子像素渲染文字文字更平滑RenderFlags.Grayscale輸出灰度圖RenderFlags.Annotations渲染PDF注釋內(nèi)容RenderFlags.OptimizeText對(duì)文字渲染做優(yōu)化在大多數(shù)業(yè)務(wù)場(chǎng)景下我建議至少開(kāi)啟LCDText尤其是需要把PDF轉(zhuǎn)成圖片用于屏幕顯示的場(chǎng)合文字邊緣會(huì)明顯更平滑。不過(guò)LCDText在生成用于印刷的圖片時(shí)建議關(guān)閉因?yàn)橛∷⑤敵鍪褂没叶然蚣兩炊€(wěn)。圖像輸出格式方面我建議默認(rèn)使用PNG。PNG是無(wú)損壓縮適合保存包含文字的頁(yè)面快照。如果對(duì)圖片大小有嚴(yán)格要求可以輸出JPEG但JPEG是壓縮格式文字邊緣會(huì)產(chǎn)生壓縮偽影在合同存檔這類(lèi)需要清晰可辨的場(chǎng)景下不推薦。還有一個(gè)選擇是TIFF但TIFF格式在Web場(chǎng)景下兼容性差除非是給老的檔案系統(tǒng)用否則不建議選TIFF。2.4 PDF文檔結(jié)構(gòu)頁(yè)面索引、旋轉(zhuǎn)和表單渲染的處理PDF的頁(yè)面索引是從0開(kāi)始的這個(gè)特征和大多數(shù)程序員熟悉的數(shù)組索引一致處理起來(lái)很順。但有幾個(gè)容易踩的坑我詳細(xì)說(shuō)說(shuō)。頁(yè)面旋轉(zhuǎn)是第一個(gè)坑。有些PDF文檔內(nèi)部記錄了旋轉(zhuǎn)角度比如掃描件可能是橫向掃描但PDF內(nèi)部設(shè)置了旋轉(zhuǎn)90度。如果直接按原始坐標(biāo)渲染輸出圖片就是橫著的。PdfiumLib在渲染時(shí)會(huì)根據(jù)頁(yè)面的/Rotate屬性自動(dòng)處理旋轉(zhuǎn)所以正常調(diào)用API時(shí)輸出的圖片順序是正確的。但如果你的業(yè)務(wù)要自己計(jì)算頁(yè)面尺寸就必須考慮旋轉(zhuǎn)因素否則寬高比會(huì)算反?？s略圖項(xiàng)目里我曾經(jīng)遇到過(guò)一個(gè)問(wèn)題某些PDF頁(yè)面旋轉(zhuǎn)后直接用PdfPage.Pages獲取寬高比例不對(duì)導(dǎo)致生成縮略圖被裁切。解決方案是渲染前先判斷PdfPage.Rotation如果是90度或270度就把寬高對(duì)調(diào)再計(jì)算。第二個(gè)坑是表單渲染。PDF的一種常見(jiàn)類(lèi)型是AcroForm表單包含文本框、下拉框、復(fù)選框等。PdfiumLib的Render方法默認(rèn)不渲染表單值如果你直接把這類(lèi)PDF轉(zhuǎn)圖片會(huì)發(fā)現(xiàn)原本有內(nèi)容的表單變成了一片空白。解決方法是設(shè)置RenderFlags.Annotations標(biāo)志位讓渲染層把注釋和表單內(nèi)容一起繪制出來(lái)。這個(gè)標(biāo)志同時(shí)會(huì)影響渲染性能實(shí)測(cè)開(kāi)啟后渲染耗時(shí)大約增加10%~15%在批量轉(zhuǎn)換場(chǎng)景下需要考慮接受這個(gè)損耗。第三個(gè)坑是頁(yè)面懶加載。PdfiumLib的PdfDocument并不會(huì)在打開(kāi)文檔時(shí)加載所有頁(yè)面到內(nèi)存而是按需加載。這對(duì)內(nèi)存管理是好事但要注意PdfPage對(duì)象在使用完后必須Dispose否則隨著循環(huán)次數(shù)增加內(nèi)存會(huì)被慢慢吃光甚至觸發(fā)PDFium的原生內(nèi)存泄漏。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 環(huán)境準(zhǔn)備安裝PdfiumViewer NuGet包我采用的是PdfiumViewer包這雖然不是PdfiumLib這個(gè)名字但內(nèi)部使用的就是PdfiumLib的核心能力而且是社區(qū)里最成熟的封裝之一。在Visual Studio的NuGet包管理器里搜索PdfiumViewer安裝最新穩(wěn)定版本即可。當(dāng)前時(shí)間節(jié)點(diǎn)下直接使用dotnet add package PdfiumViewer命令安裝dotnet add package PdfiumViewer安裝完成后項(xiàng)目引用里會(huì)多出PdfiumViewer.dll。同時(shí)在項(xiàng)目的輸出目錄里會(huì)自動(dòng)包含pdfium.dllWindows環(huán)境下。這里要注意不同平臺(tái)的運(yùn)行時(shí)庫(kù)需要手動(dòng)放到對(duì)應(yīng)目錄。如果你是在Linux服務(wù)器上部署需要下載對(duì)應(yīng)的libpdfium.so文件放到應(yīng)用程序目錄下或者放到系統(tǒng)的庫(kù)搜索路徑中。建議直接放在程序運(yùn)行目錄下避免污染系統(tǒng)目錄也方便后續(xù)升級(jí)時(shí)替換文件。3.2 第一個(gè)可運(yùn)行的PDF轉(zhuǎn)圖片Demo從最小可運(yùn)行版本開(kāi)始下面是一個(gè)最簡(jiǎn)單的調(diào)用示例using PdfiumViewer; using System.Drawing; using System.Drawing.Imaging; public static class PdfToImageConverter { public static void ConvertToImageSimple(string pdfPath, string outputPath, int dpi 150) { using var document PdfDocument.Load(pdfPath); var pageCount document.PageCount; for (int i 0; i pageCount; i) { using var page document.Render(i, dpi, dpi, PdfRenderFlags.CorrectFromDpi); page.Save(${outputPath}_page_{i 1}.png, ImageFormat.Png); } } }這里有幾個(gè)關(guān)鍵點(diǎn)。PdfDocument.Load是同步加載如果PDF文件比較大幾十MB以上首次加載會(huì)有點(diǎn)耗時(shí)。document.Render方法接收頁(yè)碼從0開(kāi)始、水平DPI、垂直DPI和渲染標(biāo)志返回一個(gè)Image對(duì)象。PdfRenderFlags.CorrectFromDpi這個(gè)標(biāo)志告訴渲染器使用傳入的DPI來(lái)計(jì)算實(shí)際輸出尺寸避免因?yàn)轫?yè)面實(shí)際尺寸和默認(rèn)分辨率不一致導(dǎo)致圖片變形。運(yùn)行這段代碼后每個(gè)PDF頁(yè)面都會(huì)輸出成一張獨(dú)立的PNG圖片。這個(gè)demo版本已經(jīng)能跑通核心鏈路但距離生產(chǎn)級(jí)應(yīng)用還差一些細(xì)節(jié)我們繼續(xù)往下優(yōu)化。3.3 支持指定頁(yè)碼區(qū)間和按需渲染的完整實(shí)現(xiàn)實(shí)際業(yè)務(wù)中很少會(huì)無(wú)腦把PDF所有頁(yè)面都轉(zhuǎn)出來(lái)。更多場(chǎng)景是指定某個(gè)頁(yè)碼范圍或者先轉(zhuǎn)一頁(yè)做預(yù)覽?；谶@個(gè)需求我封裝了一個(gè)更實(shí)用的版本using PdfiumViewer; using System.Drawing; using System.Drawing.Imaging; public static class PdfToImageBatchConverter { /// summary /// 將PDF指定范圍內(nèi)的頁(yè)面轉(zhuǎn)為PNG圖片 /// /summary /// param namepdfPathPDF文件路徑/param /// param nameoutputFolder輸出目錄/param /// param namestartPage起始頁(yè)碼從1開(kāi)始包含/param /// param nameendPage結(jié)束頁(yè)碼從1開(kāi)始包含/param /// param namedpi渲染DPI默認(rèn)150/param /// returns輸出圖片的文件路徑列表/returns public static Liststring ConvertRange(string pdfPath, string outputFolder, int startPage, int endPage, int dpi 150) { var result new Liststring(); if (string.IsNullOrWhiteSpace(pdfPath)) throw new ArgumentException(PDF路徑不能為空, nameof(pdfPath)); if (!File.Exists(pdfPath)) throw new FileNotFoundException(PDF文件不存在, pdfPath); if (!Directory.Exists(outputFolder)) Directory.CreateDirectory(outputFolder); using var document PdfDocument.Load(pdfPath); int totalPages document.PageCount; // 頁(yè)碼邊界保護(hù) startPage Math.Max(1, startPage); endPage Math.Min(totalPages, endPage); if (startPage endPage) throw new ArgumentException(起始頁(yè)碼不能大于結(jié)束頁(yè)碼); for (int pageIndex startPage; pageIndex endPage; pageIndex) { // 內(nèi)部API使用0基索引 int zeroBasedIndex pageIndex - 1; using var page document.Render(zeroBasedIndex, dpi, dpi, PdfRenderFlags.CorrectFromDpi); string fileName Path.Combine(outputFolder, ${Path.GetFileNameWithoutExtension(pdfPath)}_page_{pageIndex}.png); page.Save(fileName, ImageFormat.Png); result.Add(fileName); } return result; } }這個(gè)版本最值得說(shuō)明的是頁(yè)碼邊界處理。用戶(hù)傳入的頁(yè)碼是從1開(kāi)始的符合業(yè)務(wù)系統(tǒng)的習(xí)慣但底層API使用0基索引所以轉(zhuǎn)換時(shí)需要減一。同時(shí)做了上下限保護(hù)避免用戶(hù)傳入超大頁(yè)碼導(dǎo)致越界異常。另外一個(gè)設(shè)計(jì)細(xì)節(jié)是返回了生成圖片的文件路徑列表。這在業(yè)務(wù)對(duì)接中很有用比如生成完圖片后需要把這些圖片寫(xiě)入數(shù)據(jù)庫(kù)、返回給前端展示或者繼續(xù)做OCR識(shí)別都需要拿到輸出路徑。3.4 從字節(jié)數(shù)組加載PDF并轉(zhuǎn)成圖片在實(shí)際的項(xiàng)目中PDF文件往往不落盤(pán)而是存在于數(shù)據(jù)庫(kù)中比如以BLOB存儲(chǔ)或者從遠(yuǎn)程接口拉取。這個(gè)場(chǎng)景下我們需要支持從字節(jié)數(shù)組加載。PdfiumViewer的PdfDocument.Load重載接受Stream我們可以把字節(jié)數(shù)組包裝成MemoryStream再傳入。public static byte[] ConvertPdfBytesToPng(byte[] pdfBytes, int pageNumber, int dpi 150) { using var stream new MemoryStream(pdfBytes); using var document PdfDocument.Load(stream); using var page document.Render(pageNumber, dpi, dpi, PdfRenderFlags.CorrectFromDpi); using var outputStream new MemoryStream(); page.Save(outputStream, ImageFormat.Png); return outputStream.ToArray(); }從MemoryStream加載有一個(gè)需要注意的地方PdfDocument.Load雖然返回了文檔對(duì)象但它并沒(méi)有把整個(gè)流內(nèi)容完全讀取到內(nèi)存中而是保留了流的引用在實(shí)際渲染時(shí)才從流中讀取數(shù)據(jù)。所以調(diào)用方必須保證在PdfDocument釋放前底層流不能關(guān)閉。上面的代碼里我用了using聲明實(shí)際上MemoryStream和PdfDocument的生命周期是正確的。如果業(yè)務(wù)上需要把流提前關(guān)閉比如是從請(qǐng)求流中讀取的穩(wěn)妥的做法是把字節(jié)數(shù)組完整拷貝一份到自定義流中或者直接使用字節(jié)數(shù)組重載。這個(gè)問(wèn)題在真實(shí)工作中很容易被忽略稍不注意就會(huì)遇到“流已關(guān)閉”的詭異異常。3.5 高性能批量轉(zhuǎn)換并發(fā)與內(nèi)存控制的取舍當(dāng)需要一次性轉(zhuǎn)換幾百頁(yè)甚至上千頁(yè)P(yáng)DF時(shí)串行循環(huán)的性能往往不能滿(mǎn)足要求這時(shí)需要考慮并發(fā)處理。PDFium引擎本身是線(xiàn)程安全的多個(gè)頁(yè)面可以并行渲染PdfiumViewer的封裝也保留了這一特性。但要注意并發(fā)渲染對(duì)內(nèi)存的壓力是成倍增長(zhǎng)的。比如單頁(yè)150 DPI的A4圖片大約是3~4MB內(nèi)存如果同時(shí)開(kāi)10個(gè)線(xiàn)程每個(gè)線(xiàn)程渲染一頁(yè)峰值內(nèi)存可能會(huì)額外增加30~40MB。對(duì)于幾百頁(yè)的文檔來(lái)說(shuō)這個(gè)內(nèi)存開(kāi)銷(xiāo)是可以接受的但如果同時(shí)處理多個(gè)文檔就需要控制全局并發(fā)數(shù)。我建議使用SemaphoreSlim控制并發(fā)度避免一口氣把所有頁(yè)面都拋給線(xiàn)程池。下面是并發(fā)控制的示例public static async Task ConvertAllPagesConcurrentAsync(string pdfPath, string outputFolder, int dpi, int maxConcurrency 4) { using var document PdfDocument.Load(pdfPath); int pageCount document.PageCount; Directory.CreateDirectory(outputFolder); using var semaphore new SemaphoreSlim(maxConcurrency); var tasks new ListTask(); for (int i 0; i pageCount; i) { int pageIndex i; tasks.Add(Task.Run(async () { await semaphore.WaitAsync(); try { using var page document.Render(pageIndex, dpi, dpi, PdfRenderFlags.CorrectFromDpi); string fileName Path.Combine(outputFolder, $page_{pageIndex 1}.png); lock (fileName) { // 多個(gè)線(xiàn)程同時(shí)保存不同文件名這里不需要鎖僅演示 } page.Save(fileName, ImageFormat.Png); } finally { semaphore.Release(); } })); } await Task.WhenAll(tasks); }這個(gè)實(shí)現(xiàn)有幾個(gè)細(xì)節(jié)需要強(qiáng)調(diào)。第一document對(duì)象在整個(gè)并發(fā)過(guò)程中保持打開(kāi)狀態(tài)不能被Dispose。第二頁(yè)面索引pageIndex在循環(huán)中被閉包捕獲如果直接使用循環(huán)變量i在異步執(zhí)行時(shí)可能會(huì)拿到錯(cuò)誤的值所以必須拷貝到局部變量。第三并發(fā)度設(shè)置為4比較穩(wěn)妥既提升了吞吐量又不會(huì)因?yàn)檫^(guò)度并發(fā)導(dǎo)致內(nèi)存峰值失控。我在實(shí)際項(xiàng)目中還嘗試過(guò)用Parallel.For但并發(fā)渲染的CPU密集程度很高Task.Run配合SemaphoreSlim控制更精細(xì)推薦這個(gè)方案。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 渲染出來(lái)的圖片模糊或尺寸不符合預(yù)期這個(gè)問(wèn)題排在問(wèn)題排行的第一位。經(jīng)過(guò)排查絕大多數(shù)情況都是因?yàn)闆](méi)搞清楚DPI和Size的優(yōu)先級(jí)或者是DPI設(shè)得太低。比如默認(rèn)96 DPI渲染出來(lái)的A4頁(yè)面只有794像素寬在2K屏幕上放大看自然模糊。解決方法是明確自己的業(yè)務(wù)場(chǎng)景一般Web端展示用120~150 DPI打印用200~300 DPIOCR識(shí)別建議300 DPI。如果發(fā)現(xiàn)尺寸根本不受DPI影響檢查一下是不是代碼里顯式傳了Size參數(shù)。傳了Size就會(huì)覆蓋DPI計(jì)算尺寸固定了再調(diào)DPI當(dāng)然沒(méi)反應(yīng)。4.2 內(nèi)存占用過(guò)高甚至OutOfMemoryException內(nèi)存問(wèn)題在批量轉(zhuǎn)換時(shí)特別突出。PDFiumEngine在渲染時(shí)會(huì)在原生堆上分配內(nèi)存且這部分內(nèi)存不受.NET垃圾回收控制。如果頁(yè)面對(duì)象釋放不及時(shí)或者原生資源沒(méi)有通過(guò)Dispose釋放內(nèi)存會(huì)持續(xù)增長(zhǎng)。我的排查思路是先在代碼層面審查是否每個(gè)PdfPage、PdfDocument、Image對(duì)象都被正確釋放。其次是控制并發(fā)度不要在循環(huán)中同時(shí)渲染太多頁(yè)面。如果在部署環(huán)境比如容器中內(nèi)存本身就有限建議限制最大DPI和并發(fā)數(shù)保證峰值內(nèi)存可控。還有一個(gè)容易被忽略的細(xì)節(jié)PdfDocument.Load加載文檔后文檔對(duì)象持有整個(gè)文檔的結(jié)構(gòu)樹(shù)。如果文檔頁(yè)面很多比如上千頁(yè)結(jié)構(gòu)樹(shù)本身就會(huì)占用不少內(nèi)存。此時(shí)建議把PDF先做拆分按頁(yè)處理處理完一頁(yè)釋放一頁(yè)峰值內(nèi)存會(huì)顯著下降。4.3 Linux服務(wù)器上運(yùn)行報(bào)找不到pdfium原生庫(kù)切換到Linux服務(wù)器部署時(shí)最常見(jiàn)的錯(cuò)誤是DllNotFoundException或者Unable to load shared library pdfium。這是因?yàn)镻dfiumViewer的Windows版本自動(dòng)包含了pdfium.dll但Linux環(huán)境下需要手動(dòng)放置libpdfium.so。解決方法是手動(dòng)下載對(duì)應(yīng)的Linux版本原生庫(kù)放到程序運(yùn)行目錄下并且確保文件名和PdfiumViewer期望的名稱(chēng)一致。如果是Docker部署需要在Dockerfile里加上COPY libpdfium.so /app/。這里還有一個(gè)更深層的坑Linux原生庫(kù)的依賴(lài)。libpdfium.so依賴(lài)了系統(tǒng)的libstdc、libc.so等基礎(chǔ)庫(kù)如果基礎(chǔ)鏡像太精簡(jiǎn)比如alpine很可能會(huì)缺少這些動(dòng)態(tài)庫(kù)導(dǎo)致加載報(bào)錯(cuò)。我的經(jīng)驗(yàn)是使用debian或ubuntu基礎(chǔ)鏡像依賴(lài)缺失的概率要小很多。如果非要使用alpine需要手動(dòng)安裝libstdc。4.4 渲染出來(lái)的圖片上有中文亂碼或方塊字中文PDF轉(zhuǎn)圖片后出現(xiàn)亂碼或方塊這是很多做PDF轉(zhuǎn)換的同學(xué)都會(huì)遇到的問(wèn)題。這個(gè)問(wèn)題的根源是PDF中的字體引用無(wú)法被正確解析或映射到系統(tǒng)字體。說(shuō)直白點(diǎn)PDF文件在制作時(shí)引用了某種中文字體如果系統(tǒng)里沒(méi)有安裝這個(gè)字體渲染引擎就只能使用回退字體或者直接顯示替代符號(hào)通常是方塊。排查思路是看PDF中嵌入的字體是什么在渲染服務(wù)器上安裝對(duì)應(yīng)的中文字體。Linux服務(wù)器上需要安裝字體包執(zhí)行apt-get install -y fonts-noto-cjk這樣可以解決大部分常見(jiàn)的中文字體缺失問(wèn)題。如果是使用某個(gè)業(yè)務(wù)特有的字體需要把字體文件上傳到服務(wù)器并注冊(cè)進(jìn)系統(tǒng)字體庫(kù)。還有一個(gè)容易忽略的點(diǎn)是PdfiumLib的字體渲染依賴(lài)FreeTypeFreeType在編譯時(shí)是否啟用了CJK支持會(huì)影響中文渲染效果。PdfiumViewer自帶的原生庫(kù)已經(jīng)包含了必要的支持這塊一般不需要額外操心。4.5 pdfium原生庫(kù)版本沖突項(xiàng)目中可能同時(shí)引用了其他依賴(lài)PDFium的組件比如某些OCR工具、PDF解析器等導(dǎo)致不同版本的pdfium.dll或libpdfium.so出現(xiàn)在同一目錄運(yùn)行時(shí)加載了錯(cuò)誤版本出現(xiàn)各種奇怪行為。排查方法是使用Process ExplorerWindows或lsofLinux確認(rèn)進(jìn)程實(shí)際加載的原生庫(kù)路徑。如果發(fā)現(xiàn)加載的不是預(yù)期路徑下的庫(kù)需要調(diào)整程序集加載順序或者在啟動(dòng)時(shí)先設(shè)置NativeLibrary.SetDllImportResolver把原生庫(kù)解析到指定目錄。還有一種情況是NuGet包內(nèi)置了一個(gè)舊版本的pdfium.dll和你手動(dòng)放到輸出目錄的新版本沖突。解決方法是檢查輸出目錄中的原生庫(kù)文件刪除多余版本只保留正確的那一個(gè)。4.6 渲染過(guò)程中出現(xiàn)Timeout或掛起在極端情況下某些損壞的PDF文件可能導(dǎo)致渲染器長(zhǎng)時(shí)間無(wú)響應(yīng)甚至掛起。PdfiumLib對(duì)損壞文件的容忍度有限Parser階段報(bào)錯(cuò)倒是還好處理主要是渲染階段的問(wèn)題比較頭疼。我的經(jīng)驗(yàn)是使用任務(wù)超時(shí)機(jī)制包裹渲染調(diào)用比如用Task.Run加WaitAsync實(shí)現(xiàn)超時(shí)控制。一旦超過(guò)設(shè)定時(shí)間比如30秒主動(dòng)取消任務(wù)避免整個(gè)轉(zhuǎn)換流程卡死。同時(shí)從業(yè)務(wù)層面攔截異常把損壞的PDF記錄下來(lái)待人工處理。另外PDFium內(nèi)部對(duì)惡意構(gòu)造的文件有防護(hù)機(jī)制但仍然建議部署時(shí)做文件大小和頁(yè)數(shù)上限的限制。比如超過(guò)200MB的文件或超過(guò)5000頁(yè)的文檔直接拒絕轉(zhuǎn)換避免拖垮整個(gè)服務(wù)。5. 性能優(yōu)化與生產(chǎn)級(jí)落地建議5.1 設(shè)置合理的緩存策略重復(fù)轉(zhuǎn)換同一PDF時(shí)避免重復(fù)渲染在真實(shí)業(yè)務(wù)中用戶(hù)可能會(huì)反復(fù)預(yù)覽同一個(gè)PDF文件。如果每次預(yù)覽都重新渲染一遍既浪費(fèi)CPU又浪費(fèi)磁盤(pán)I/O。更合理的做法是引入緩存以PDF文件路徑或數(shù)據(jù)庫(kù)存儲(chǔ)的BLOB哈希值為Key以渲染產(chǎn)物圖片路徑或二進(jìn)制為Value設(shè)置過(guò)期時(shí)間。我慣用的緩存策略是兩級(jí)。第一級(jí)是磁盤(pán)文件緩存轉(zhuǎn)換生成的圖片直接落盤(pán)到指定目錄文件名帶上頁(yè)面信息和DPI信息下次請(qǐng)求時(shí)先檢查文件是否存在存在就直接返回。第二級(jí)是內(nèi)存緩存適用于頻繁訪(fǎng)問(wèn)的頁(yè)面比如PDF首頁(yè)的預(yù)覽圖。內(nèi)存緩存推薦使用IMemoryCache可以設(shè)置滑動(dòng)過(guò)期時(shí)間防止緩存無(wú)限膨脹。這里有一個(gè)實(shí)踐細(xì)節(jié)如果同一份PDF需要支持多種DPI輸出比如縮略圖96 DPI、預(yù)覽圖150 DPI、打印300 DPI建議在緩存Key中把DPI值也帶上否則容易出現(xiàn)拿到低清圖去打印的尷尬情況。5.2 用ImageSharp替代System.Drawing解決跨平臺(tái)圖像處理問(wèn)題PdfiumViewer的Render方法返回的是System.Drawing.Image這個(gè)類(lèi)型在Windows上沒(méi)問(wèn)題但在Linux上依賴(lài)GDI兼容層有時(shí)會(huì)在邊緣場(chǎng)景下報(bào)錯(cuò)。如果做簡(jiǎn)單的截圖保存倒還好但一旦涉及圖片裁剪、加水印、格式轉(zhuǎn)換等后處理就可能踩到坑。我在跨平臺(tái)部署時(shí)更推薦直接把System.Drawing.Image轉(zhuǎn)換成字節(jié)數(shù)組然后用跨平臺(tái)的圖像庫(kù)做后續(xù)處理。常見(jiàn)的替代品有SixLabors.ImageSharp和SkiaSharp。兩者的成熟度都很高配合PdfiumViewer使用都沒(méi)有兼容性問(wèn)題。以ImageSharp為例把PDF渲染出的頁(yè)面字節(jié)流轉(zhuǎn)成Image后再疊加水印的示例using SixLabors.ImageSharp; using SixLabors.ImageSharp.Formats.Png; using SixLabors.ImageSharp.Processing; public static byte[] AddWatermark(byte[] sourcePng, string watermarkText) { using var image Image.Load(sourcePng); image.Mutate(x { x.DrawText(watermarkText, new Font(Arial, 24), Color.FromRgb(128, 128, 128), new PointF(20, 20)); }); using var output new MemoryStream(); image.Save(output, new PngEncoder()); return output.ToArray(); }需要注意ImageSharp的DrawText在Linux下也需要字體支持和上面提到的中文亂碼問(wèn)題類(lèi)似需要確保服務(wù)器上有目標(biāo)字體可用。5.3 文件命名與歸檔規(guī)范大批量轉(zhuǎn)換時(shí)輸出文件命名如果太隨意后期維護(hù)會(huì)非常痛苦。我建議的命名規(guī)范是{原文件名}_{頁(yè)碼}_{參數(shù)摘要}.png例如合同_20240101_page_001_d150.png。文件名里攜帶頁(yè)碼和DPI信息既方便排查問(wèn)題也能防止不同處理參數(shù)的結(jié)果互相覆蓋。歸檔目錄建議按日期分目錄比如/data/pdf-images/2024/01/01/避免單個(gè)目錄下文件數(shù)量過(guò)多影響文件系統(tǒng)性能。如果是長(zhǎng)期累積的轉(zhuǎn)換任務(wù)還要考慮定期清理過(guò)期緩存的策略否則磁盤(pán)會(huì)逐漸被塞滿(mǎn)。6. 個(gè)人經(jīng)驗(yàn)與避坑心得這套基于PdfiumLib的方案上線(xiàn)后穩(wěn)定運(yùn)行了大半年處理了幾十萬(wàn)頁(yè)的轉(zhuǎn)換任務(wù)。最深的體會(huì)是選型階段多花時(shí)間做對(duì)比遠(yuǎn)比中途返工更劃算。PdfiumLib雖然不是功能最全的PDF庫(kù)但它在“開(kāi)源、免費(fèi)商用、渲染質(zhì)量可靠、跨平臺(tái)”這個(gè)組合上表現(xiàn)得很均衡對(duì)大多數(shù)業(yè)務(wù)系統(tǒng)來(lái)說(shuō)已經(jīng)夠用。最后分享一個(gè)在真實(shí)業(yè)務(wù)中反復(fù)踩坑之后總結(jié)出來(lái)的小技巧渲染時(shí)建議在日志中記錄PDF的頁(yè)數(shù)、轉(zhuǎn)換耗時(shí)、輸出圖片大小等信息。等哪天文件量上來(lái)需要做性能分析時(shí)這些日志能幫你快速定位瓶頸。比如某段時(shí)間突然轉(zhuǎn)換耗時(shí)翻倍很可能不是代碼的問(wèn)題而是上游生成的PDF文件變復(fù)雜了頁(yè)面內(nèi)嵌了大量高清圖片或復(fù)雜矢量有日志支撐時(shí)排查速度會(huì)快很多。如果后續(xù)業(yè)務(wù)量繼續(xù)增長(zhǎng)還可以把轉(zhuǎn)換任務(wù)做成異步隊(duì)列形式把請(qǐng)求先丟進(jìn)消息隊(duì)列由后臺(tái)worker池處理避免同步請(qǐng)求阻塞Web應(yīng)用。這是我目前正在驗(yàn)證的方向等穩(wěn)定之后我再單獨(dú)寫(xiě)一篇做分享。本文還有配套的精品資源點(diǎn)擊獲取