Base64：徹底解決HTML轉(zhuǎn)PDF圖片丟失問(wèn)題)
做小程序開(kāi)發(fā)這幾年但凡涉及“生成 PDF 報(bào)告”“導(dǎo)出電子合同”“分享帶圖卡片”十有八九都會(huì)撞上同一個(gè)難題圖片在頁(yè)面上顯示得好好的一進(jìn) PDF 就消失或者只有一行排版的“幽靈”占位符。踩過(guò)幾次坑之后我才徹底明白這個(gè)小程序里的圖片想lnthtml 轉(zhuǎn) PDF基本繞不開(kāi) base64 這條路。今天就把這個(gè)問(wèn)題的來(lái)龍去脈、各種轉(zhuǎn)換方案、以及我在 SelectPdf 上踩過(guò)的坑一次性講清楚。1. 問(wèn)題本質(zhì)為什么 PDF 引擎讀不到小程序里的圖片先別急著寫(xiě)代碼搞清楚底層原因比啥都重要。你用 SelectPdf 這類(lèi)服務(wù)端渲染庫(kù)去轉(zhuǎn)換 PDF 時(shí)它本質(zhì)上是一個(gè)獨(dú)立于小程序環(huán)境的 HTML 渲染引擎。這個(gè)引擎執(zhí)行 JS、解析 CSS、加載資源全都發(fā)生在你的服務(wù)器上。它和你的小程序客戶(hù)端隔著整個(gè)網(wǎng)絡(luò)。1.1 小程序圖片的三種來(lái)源后端一個(gè)都拿不到小程序里的圖片資源無(wú)非這三種來(lái)源網(wǎng)絡(luò) URLhttps://your-cdn.com/images/logo.png。理論上后端能訪(fǎng)問(wèn)但現(xiàn)實(shí)中往往被防盜鏈、跨域策略、臨時(shí)簽名失效擋住而且如果這張圖來(lái)自小程序云存儲(chǔ)URL 里多半帶動(dòng)態(tài)簽名轉(zhuǎn) PDF 那一刻可能已經(jīng)過(guò)期。本地臨時(shí)文件wxfile://tmp_xxx/photo.jpg。這是小程序最常用的方式場(chǎng)景里拍照、選圖后得到的都是這種本地路徑。可這個(gè)路徑是客戶(hù)端文件系統(tǒng)里的路徑服務(wù)器端 SelectPdf 連你這臺(tái)電腦的文件都讀不到更何況是千里之外的手機(jī)沙箱。云文件 IDcloud://env-id.xxxx/xxx.png。這個(gè)更特殊只有小程序端通過(guò)云能力才能解析后端拿到的就是一個(gè)字符串 ID無(wú)法直接當(dāng)圖片 URL 用。所以你會(huì)看到一種詭異現(xiàn)象在小程序里用 web-view 預(yù)覽那個(gè) HTML 時(shí)圖片正常顯示因?yàn)?web-view 在客戶(hù)端運(yùn)行能訪(fǎng)問(wèn)本地文件但一旦把同樣的 HTML 字符串 POST 給后端 SelectPdf圖片全掛。1.2 PDF 渲染引擎的加載機(jī)制要理解怎么辦先得理解 SelectPdf 這類(lèi)引擎的工作方式。它會(huì)解析 HTML 字符串構(gòu)建 DOM碰到img標(biāo)簽時(shí)根據(jù)src屬性去發(fā)起資源請(qǐng)求。如果src是wxfile://開(kāi)頭引擎根本不認(rèn)識(shí)這個(gè)協(xié)議如果src是相對(duì)路徑/images/a.png引擎會(huì)嘗試基于一個(gè) BaseUrl 去拼接但你顯然沒(méi)給它配如果是公網(wǎng) URL 但圖片服務(wù)器有防盜鏈Referer 校驗(yàn)失敗就直接返回 403?？偠灾矆D片路徑存在一點(diǎn)不確定性最終 PDF 里就是一片空白。這也就是標(biāo)題里那句“圖片必須編碼”的由來(lái)——不是玄學(xué)是傳輸鏈路決定的。1.3 base64 為什么能成為終極解決方案base64 本質(zhì)上是用 64 個(gè)可打印字符來(lái)表示二進(jìn)制數(shù)據(jù)。一張圖片的二進(jìn)制內(nèi)容經(jīng)過(guò)編碼后變成一串字符然后以?xún)?nèi)聯(lián)方式塞進(jìn) HTMLimg srcdata:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... /data:URI 是 RFC 2397 定義的方案瀏覽器的渲染引擎見(jiàn)到這種src不需要發(fā)任何網(wǎng)絡(luò)請(qǐng)求直接解碼字符串里的二進(jìn)制數(shù)據(jù)并渲染。不管你是本地臨時(shí)文件、網(wǎng)絡(luò)圖片還是云文件只要在小程序端把它轉(zhuǎn)成了 base64 字符串塞進(jìn) HTML 里后端 SelectPdf 就一定能渲染出圖片來(lái)。這個(gè)方案跨平臺(tái)、跨語(yǔ)言、沒(méi)有防盜鏈問(wèn)題笨但是絕對(duì)可靠。2. 小程序圖片轉(zhuǎn) base64 的三種實(shí)操方案在實(shí)際開(kāi)發(fā)中不同場(chǎng)景的圖片得用不同姿勢(shì)去轉(zhuǎn) base64。我總結(jié)下來(lái)就是三板斧讀臨時(shí)文件、下載網(wǎng)絡(luò)圖再讀、canvas 繪制導(dǎo)出。2.1 方案一FileSystemManager 讀取本地臨時(shí)文件如果你手里的圖片已經(jīng)在小程序的本地文件系統(tǒng)里比如wx.chooseImage、wx.chooseMedia返回的tempFilePath直接用FileSystemManager.readFile指定編碼為base64就能拿到 base64 字符串。const fs wx.getFileSystemManager(); function fileToBase64(filePath) { return new Promise((resolve, reject) { fs.readFile({ filePath: filePath, encoding: base64, success(res) { resolve(res.data); // 這里是純 base64 字符串沒(méi)有 data:image 前綴 }, fail(err) { reject(err); } }); }); } // 使用示例選擇圖片后馬上轉(zhuǎn) base64 wx.chooseMedia({ count: 1, mediaType: [image], success: async (res) { const tempFilePath res.tempFiles[0].tempFilePath; const base64 await fileToBase64(tempFilePath); console.log(base64); } });注意這里有個(gè)細(xì)節(jié)readFile返回的base64字符串是不含data:image/jpeg;base64,前綴的。你得自己拼上圖片的 MIME 類(lèi)型才能變成 HTML 能識(shí)別的 data URIfunction buildDataUri(base64, mimeType image/jpeg) { return data:${mimeType};base64,${base64}; }MIME 類(lèi)型怎么拿可以根據(jù)文件后綴判斷.jpg-image/jpeg.png-image/png.gif-image/gif.webp-image/webp。如果你用wx.chooseMedia返回的tempFiles[0].fileType也可以作為參考。2.2 方案二網(wǎng)絡(luò)圖片先下載再轉(zhuǎn) base64如果圖片本身是網(wǎng)絡(luò) URL直接轉(zhuǎn) base64 需要在服務(wù)端解決防盜鏈小程序端最穩(wěn)妥的辦法是先用wx.downloadFile把圖片下載成臨時(shí)文件然后再走方案一的readFile。function downloadFileToBase64(url) { return new Promise((resolve, reject) { wx.downloadFile({ url: url, success: async (res) { if (res.statusCode 200) { try { const base64 await fileToBase64(res.tempFilePath); resolve({ tempFilePath: res.tempFilePath, base64 }); } catch (e) { reject(e); } } else { reject(new Error(下載失敗HTTP ${res.statusCode})); } }, fail: reject }); }); }為什么先下載再讀取因?yàn)閣x.downloadFile幫你繞過(guò)了很多瀏覽器環(huán)境和后端環(huán)境的限制。小程序內(nèi)部有自己的一套網(wǎng)絡(luò)棧能處理一些特殊域名證書(shū)、跳過(guò)跨域限制前提是在后臺(tái)配置了合法域名。下載成功后圖片就變成了本地臨時(shí)文件再用readFile轉(zhuǎn) base64 就順理成章。注意wx.downloadFile有 10MB 的單文件大小限制iOS/Android 略有差異超過(guò)會(huì)走 fail 回調(diào)。真機(jī)測(cè)試時(shí)尤其要留意大圖場(chǎng)景。2.3 方案三canvas 重繪后導(dǎo)出 dataURL有些場(chǎng)景下圖片不能直接讀取文件內(nèi)容比如你從后端拿到的是一張需要加水印合成的圖片或者你想在導(dǎo)出 PDF 前把圖片壓縮一下。這時(shí)候可以用wx.createOffscreenCanvas或者傳統(tǒng)的canvas組件把圖片繪制到畫(huà)布上再通過(guò)wx.canvasToDataURL導(dǎo)出。function drawImageToDataUrl(imagePath, { width 750, height 750 } {}) { return new Promise((resolve, reject) { const offscreenCanvas wx.createOffscreenCanvas({ type: 2d, width, height }); const ctx offscreenCanvas.getContext(2d); const img offscreenCanvas.createImage(); img.onload () { ctx.clearRect(0, 0, width, height); // 等比縮放繪制 const scale Math.min(width / img.width, height / img.height); const dw img.width * scale; const dh img.height * scale; const dx (width - dw) / 2; const dy (height - dh) / 2; ctx.drawImage(img, dx, dy, dw, dh); const dataUrl offscreenCanvas.toDataURL(image/jpeg, 0.8); resolve(dataUrl); }; img.onerror reject; img.src imagePath; }); }這里產(chǎn)出的dataUrl是完整的data:image/jpeg;base64,...格式可以直接拼接進(jìn) HTML。這種方式最大的好處是可以順便壓縮圖片把 2MB 的圖壓到 200KB后面請(qǐng)求后端接口時(shí)壓力小很多。2.4 三種方案怎么選一張表講清楚場(chǎng)景首選方案原因拍照/相冊(cè)選圖后的臨時(shí)文件方案一直接讀文件開(kāi)銷(xiāo)最小網(wǎng)絡(luò)圖片、CDN 圖片方案二先下載解決防盜鏈再轉(zhuǎn)碼需要壓縮、加水印、裁剪方案三順便處理圖片一舉兩得云文件 ID先換 https 鏈接再走方案二wx.cloud.getTempFileURL換臨時(shí)鏈接我個(gè)人的習(xí)慣是只要圖片不是特別大一律先走 canvas 壓縮到 80% 質(zhì)量再編碼。省下來(lái)的流量和時(shí)間在弱網(wǎng)環(huán)境下體感差異非常明顯。3. SelectPdf 集成與圖片渲染完整實(shí)操當(dāng)你手里已經(jīng)有了一堆 base64 字符串接下來(lái)要做的就是把它們拼進(jìn) HTML交給 SelectPdf 轉(zhuǎn) PDF。這一節(jié)我會(huì)給出一套能直接跑通的完整流程。3.1 SelectPdf 的基本定位和工作原理SelectPdf 是一個(gè) .NET 平臺(tái)的 HTML 轉(zhuǎn) PDF 組件它基于自家的渲染內(nèi)核能解析 HTML CSS JavaScript生成 PDF 文件。它解決的核心痛點(diǎn)是PDF 排版極難手工控制而 HTML/CSS 排版有天然優(yōu)勢(shì)寫(xiě)完頁(yè)面模板直接轉(zhuǎn) PDF省去報(bào)表引擎那一大堆代碼。使用它非常直觀核心就是一個(gè)HtmlToPdf類(lèi)using SelectPdf; var converter new HtmlToPdf(); var pdfDoc converter.ConvertHtmlString(htmlContent); pdfDoc.Save(output.pdf); pdfDoc.Close();你可能會(huì)問(wèn)為什么不在前端用 html2canvas jsPDF老實(shí)說(shuō)小程序環(huán)境的 DOM 模型和瀏覽器差別很大html2canvas 在小程序里水土不服而 jsPDF 是一行行手動(dòng)追加內(nèi)容做復(fù)雜排版能寫(xiě)到懷疑人生。服務(wù)端 SelectPdf 用 HTML CSS 控制樣式模板復(fù)用度高后端還能順手加頁(yè)眉頁(yè)腳、頁(yè)碼水印所以在正經(jīng)業(yè)務(wù)里我更推薦這個(gè)鏈路。3.2 轉(zhuǎn)換前的圖片壓縮與編碼處理回到小程序端。假設(shè)用戶(hù)在小程序里填完一份體檢報(bào)告里面有一個(gè)指標(biāo)異常提示圖、一個(gè)趨勢(shì)圖canvas 繪制。你需要把這些圖都轉(zhuǎn)成 base64然后塞進(jìn)待傳給后端的 JSON 里。async function buildPdfPayload(formData, images) { const imageDataUris []; for (let i 0; i images.length; i) { const imgInfo images[i]; let dataUri ; if (imgInfo.type temp) { const b64 await fileToBase64(imgInfo.path); dataUri data:${imgInfo.mime};base64,${b64}; } else if (imgInfo.type network) { const res await downloadFileToBase64(imgInfo.url); dataUri data:${imgInfo.mime};base64,${res.base64}; } else if (imgInfo.type canvas) { dataUri await drawImageToDataUrl(imgInfo.path, { width: 600, height: 400 }); } imageDataUris.push(dataUri); } return { ...formData, htmlContent: renderReportHtml(formData, imageDataUris) }; }renderReportHtml就用模板字符串把圖片的 data URI 嵌進(jìn)去function renderReportHtml(formData, imageDataUris) { const imageTags imageDataUris.map((uri, idx) { return img src${uri} stylemax-width:100%;margin:10px 0; /; }).join(); return !DOCTYPE html html head meta charsetutf-8 / style body { font-family: PingFang SC, Microsoft YaHei, sans-serif; padding: 20px; color: #333; } h1 { text-align: center; border-bottom: 2px solid #1890ff; padding-bottom: 10px; } .info-row { display: flex; justify-content: space-between; margin: 8px 0; } .highlight { color: #e6a23c; font-weight: bold; } /style /head body h1${formData.title}/h1 div classinfo-rowspan姓名/spanspan${formData.name}/span/div div classinfo-rowspan報(bào)告日期/spanspan${formData.date}/span/div div classinfo-rowspan異常指標(biāo)/spanspan classhighlight${formData.alertCount} 項(xiàng)/span/div ${imageTags} /body /html; }然后把htmlContent通過(guò)wx.request發(fā)給后端wx.request({ url: https://your-server.com/api/convert, method: POST, data: { html: htmlContent }, success(res) { if (res.statusCode 200) { // 拿到 PDF 文件臨時(shí)路徑 const pdfPath res.data.pdfPath; wx.openDocument({ filePath: pdfPath, fileType: pdf }); } } });3.3 服務(wù)端 C# 接收 HTML 并生成 PDF服務(wù)端這邊我用 ASP.NET Core 寫(xiě)了個(gè)接口接收 JSON 里的 HTML調(diào)用 SelectPdf 轉(zhuǎn)換。要注意幾個(gè)關(guān)鍵配置[HttpPost(api/convert)] public IActionResult ConvertPdf([FromBody] PdfRequest request) { var converter new HtmlToPdf(); // 關(guān)鍵配置 converter.Options.PdfPageSize PdfPageSize.A4; converter.Options.PdfPageOrientation PdfPageOrientation.Portrait; converter.Options.MarginLeft 20; converter.Options.MarginRight 20; converter.Options.MarginTop 20; converter.Options.MarginBottom 20; converter.Options.WebPageWidth 750; // 按小程序設(shè)計(jì)稿寬度渲染 converter.Options.WebPageHeight 0; // 0 表示高度自適應(yīng) // 渲染 HTML var doc converter.ConvertHtmlString(request.Html); // 輸出到內(nèi)存流 using var ms new MemoryStream(); doc.Save(ms); doc.Close(); var pdfBytes ms.ToArray(); return File(pdfBytes, application/pdf, report.pdf); }WebPageWidth我建議設(shè)成 750 或者和你的小程序頁(yè)面寬度一致。SelectPdf 渲染頁(yè)面時(shí)會(huì)把 HTML 當(dāng)成一個(gè) 750px 寬的網(wǎng)頁(yè)來(lái)排版這樣圖片的max-width: 100%、流式布局才會(huì)有正確的視覺(jué)比例。如果默認(rèn) 1024有些擠壓效果或者換行位置會(huì)有偏差。3.4 圖片格式與 base64 編碼的細(xì)節(jié)控制SelectPdf 對(duì)圖片格式的兼容性不錯(cuò)JPG、PNG、WebP 基本都能正確處理。但有幾個(gè)細(xì)節(jié)圖片格式統(tǒng)一成 JPG 或 PNG 就夠了。小程序里經(jīng)常會(huì)遇到image/gif轉(zhuǎn) PDF 時(shí) gif 動(dòng)圖只會(huì)取第一幀而且 base64 體積很大。如果只是靜態(tài)展示建議在 canvas 方案里強(qiáng)制轉(zhuǎn)成 JPEG。base64 字符串的完整性。后端接到的 base64 可能有換行符、空格SelectPdf 解析 data URI 時(shí)比較挑剔。你可以在后端做個(gè)清理request.Html Regex.Replace(request.Html, data:image/[^;];base64,([^])(?|), m { var clean m.Groups[1].Value.Replace(\r, ).Replace(\n, ).Replace( , ); return $data:image/jpeg;base64,{clean}; });我遇到過(guò)非常詭異的問(wèn)題前端傳給后端時(shí)請(qǐng)求體里 base64 被encodeURIComponent了一遍后端忘了decodeURIComponent導(dǎo)致data:image/jpeg;base64,%2F9j%2F...SelectPdf 當(dāng)然認(rèn)不出來(lái)。這種問(wèn)題排查起來(lái)很煩最好在前端發(fā)送前就約定好HTML 原文傳不轉(zhuǎn)義后端收到直接進(jìn)轉(zhuǎn)換器。base64 體積暴漲 33%接口要提前做好預(yù)案。原始圖片 1MB轉(zhuǎn) base64 后約 1.37MB。如果一個(gè) PDF 里有 5 張這樣的圖POST 體積就接近 7MB。很多網(wǎng)關(guān)默認(rèn)有 1MB/10MB 的請(qǐng)求體限制線(xiàn)上環(huán)境要確認(rèn) nginx 的client_max_body_size和后端框架的MaxRequestBodySize否則會(huì)出現(xiàn)“小圖正常大圖 413”的詭異問(wèn)題。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這段是我最想寫(xiě)的因?yàn)楣馐恰皥D片轉(zhuǎn) base64 后 PDF 里還是不顯示”這一個(gè)問(wèn)題我就在生產(chǎn)環(huán)境折騰過(guò)整整一天。下面把典型的坑和排查思路都列出來(lái)。4.1 圖片不顯示但 HTML 里明明有 data URI現(xiàn)象后端日志里能看到 HTML 里有data:image/jpeg;base64,...但 PDF 輸出中圖片位置是空白。排查步驟把后端收到的 HTML 字符串原樣保存成.html文件用 Chrome 打開(kāi)。這是最重要的一步——先確認(rèn) HTML 本身沒(méi)問(wèn)題。如果 Chrome 里也空白說(shuō)明 base64 數(shù)據(jù)本身就是壞的問(wèn)題出在前端編碼環(huán)節(jié)。檢查 base64 前綴里的 MIME 是否和真實(shí)文件類(lèi)型匹配。常見(jiàn)錯(cuò)誤是PNG 圖片卻標(biāo)注了data:image/jpeg某些渲染內(nèi)核會(huì)比較嚴(yán)格按 jpeg 解碼 png 數(shù)據(jù)直接失敗。檢查 base64 里是否混入了\n、\r、空格。理論上 data URI 里不應(yīng)該有這些字符。部分庫(kù)能容忍SelectPdf 我實(shí)測(cè)下來(lái)對(duì)它很敏感清理干凈最穩(wěn)。我踩過(guò)的具體例子小程序端用了wx.getFileSystemManager().readFile的encoding: base64但圖片路徑是云文件 IDcloud://...readFile 直接報(bào)錯(cuò)我當(dāng)時(shí)沒(méi)接fail回調(diào)結(jié)果 base64 是一個(gè)空字符串頁(yè)面和 HTML 都“正?！本褪菦](méi)圖。4.2 圖片在部分手機(jī)上正常部分手機(jī)空白現(xiàn)象同樣一套代碼iOS 上生成 PDF 有圖Android 上沒(méi)有。這種問(wèn)題大多數(shù)出在圖片路徑的時(shí)效性上。wx.downloadFile的臨時(shí)文件在onUnload后基本就沒(méi)了如果用戶(hù)從選擇圖片頁(yè)面跳轉(zhuǎn)到預(yù)覽頁(yè)面兩個(gè)頁(yè)面之間通過(guò)全局變量存了tempFilePath但底層的臨時(shí)文件已經(jīng)被回收那你readFile時(shí)拿到的是已經(jīng)失效的路徑。解決辦法在拿到臨時(shí)文件后立即轉(zhuǎn) base64不要存路徑只存 base64 字符串。這樣圖片數(shù)據(jù)就變成了內(nèi)存字符串和文件生命周期無(wú)關(guān)了。// 錯(cuò)誤做法只存路徑下次頁(yè)面再用 globalData.tempImagePath tempFilePath; // 正確做法立刻轉(zhuǎn) base64 存起來(lái) globalData.tempImageBase64 await fileToBase64(tempFilePath);4.3 base64 太大導(dǎo)致請(qǐng)求超時(shí)或內(nèi)存暴漲現(xiàn)象圖片一多小程序端wx.request直接fail超時(shí)或者后端進(jìn)程內(nèi)存突然飆高。這不僅是網(wǎng)絡(luò)問(wèn)題還是性能問(wèn)題。base64 文本在 JSON 序列化/反序列化時(shí)會(huì)被復(fù)制多份內(nèi)存圖片數(shù)據(jù)動(dòng)輒幾 MB在小程序這種 JSCore 環(huán)境下很容易觸發(fā)內(nèi)存告警。我的處理思路是分級(jí)優(yōu)化第一級(jí)canvas 壓縮。把長(zhǎng)邊壓到 800px、質(zhì)量 80%肉眼基本看不出差異體積卻能縮小 70% 以上。 第二級(jí)PDF 不需要透明通道的場(chǎng)景全部轉(zhuǎn) JPEG不要用 PNG。PNG 的 base64 膨脹率更高。 第三級(jí)大圖拆分請(qǐng)求不要一次性把 10 張圖塞一個(gè)請(qǐng)求里按 3~4 張一批后端分頁(yè)合成 PDF。4.4 防盜鏈與 Referer 校驗(yàn)的坑小程序端wx.downloadFile的網(wǎng)絡(luò)棧是白名單制的所以能下載的圖基本都是合法域名。但有時(shí)候你從某個(gè)圖片 CDN 下載沒(méi)問(wèn)題后端 SelectPdf 直接訪(fǎng)問(wèn)原圖 URL 卻被 403這就是防盜鏈。遇到這種情況不必和后端去糾結(jié)配 Referer 白名單小程序端直接把圖下載轉(zhuǎn)成 base64 就完事了。base64 內(nèi)聯(lián)進(jìn) HTML 后SelectPdf 不會(huì)再去發(fā)圖片請(qǐng)求防盜鏈規(guī)則形同虛設(shè)。這是我強(qiáng)烈推薦“先下載再轉(zhuǎn)碼”的核心理由。4.5 臨時(shí)文件堆滿(mǎn)存儲(chǔ)空間小程序端每downloadFile一次都會(huì)在用戶(hù)設(shè)備上殘留臨時(shí)文件。如果用戶(hù)高頻操作臨時(shí)文件積累多了會(huì)占滿(mǎn)存儲(chǔ)空間。雖然wx.downloadFile返回的tempFilePath會(huì)在小程序退出時(shí)清理但同一會(huì)話(huà)內(nèi)頻繁生成也會(huì)有問(wèn)題。實(shí)操建議轉(zhuǎn)完 base64 以后主動(dòng)清理臨時(shí)文件const fs wx.getFileSystemManager(); // 不需要的臨時(shí)文件直接刪掉 try { fs.unlinkSync(tempFilePath); } catch (e) { // 忽略刪除失敗臨時(shí)文件后續(xù)還會(huì)被系統(tǒng)回收 }4.6 常見(jiàn)問(wèn)題速查表癥狀可能原因快速解決PDF 圖片空白但 HTML 正常base64 含換行空格、MIME 類(lèi)型不對(duì)后端正則清理嚴(yán)格校驗(yàn) MIME部分機(jī)型失敗臨時(shí)文件被回收拿到路徑立刻轉(zhuǎn) base64別存路徑請(qǐng)求 413 或超時(shí)base64 體積過(guò)大、網(wǎng)關(guān)限制壓縮圖片、分批提交、調(diào)大請(qǐng)求體限制圖片拉伸變形canvas 繪制時(shí)未等比縮放用Math.min計(jì)算縮放比例居中繪制圖片模糊原圖分辨率低、canvas 導(dǎo)出尺寸小提高 canvas 尺寸到 2 倍設(shè)置 quality 0.9WebP 格式異常SelectPdf 對(duì)部分 WebP 解碼兼容性差統(tǒng)一轉(zhuǎn) JPEG5. 這套流程還能怎么擴(kuò)展從單圖到批量 PDF 的工程化改造前面講的都是單份 PDF 的生成流程。真實(shí)業(yè)務(wù)里往往是一個(gè)訂單下有多個(gè)報(bào)告或者一個(gè)批次要生成幾百份合同。在這個(gè)基礎(chǔ)上我對(duì)這個(gè)方案又做了幾層工程化改造也算是給讀者一條進(jìn)階路徑。5.1 模板與數(shù)據(jù)分離小程序的 HTML 模板不要硬編碼在后端 C# 里也不要在前端字符串拼建議統(tǒng)一放到后端模板管理表里。小程序端只傳業(yè)務(wù)數(shù)據(jù)name、date、images 數(shù)組后端用 Razor 模板引擎或者簡(jiǎn)單的字符串模板去渲染最終 HTML。好處是排版的調(diào)整不需要發(fā)版小程序只更新服務(wù)端模板就行。5.2 批量生成 異步任務(wù)隊(duì)列當(dāng)圖片數(shù)量巨大時(shí)同步ConvertHtmlString會(huì)長(zhǎng)時(shí)間占用后端線(xiàn)程。建議引入消息隊(duì)列比如 RabbitMQ 或者簡(jiǎn)單的 Redis 隊(duì)列。請(qǐng)求進(jìn)來(lái)先返回“任務(wù)ID”后臺(tái) Worker 逐份渲染 PDF完成后推送到小程序。小程序的體驗(yàn)就是用戶(hù)點(diǎn)了“生成報(bào)告”頁(yè)面出現(xiàn)一個(gè)“處理中”的進(jìn)度條1~2 秒后服務(wù)端主動(dòng)推送 PDF 地址再wx.openDocument打開(kāi)。比同步卡死優(yōu)雅太多。5.3 PDF 的頁(yè)眉頁(yè)腳、頁(yè)碼、水印SelectPdf 這塊做得比較完善。合同場(chǎng)景下頁(yè)腳可以放頁(yè)碼、公司電話(huà)頁(yè)眉放公司 logo這個(gè) logo 又是一張圖同樣轉(zhuǎn) base64。水印可以在converter.Options里配置也可以在 HTML 里用 CSS 畫(huà)一個(gè)半透明背景層。我實(shí)測(cè)下來(lái)CSS 水印在 PDF 渲染里很穩(wěn)定多頁(yè)內(nèi)容會(huì)重復(fù)出現(xiàn)在每頁(yè)上效果比組件自帶的更可控。6. 寫(xiě)在最后的一點(diǎn)經(jīng)驗(yàn)如果要在這一堆實(shí)操里挑一句最想對(duì)后來(lái)人說(shuō)的別在小程序端做任何依賴(lài)“文件路徑”的持久化圖片數(shù)據(jù)必須在你還在當(dāng)前頁(yè)面環(huán)境時(shí)立刻轉(zhuǎn)化為 base64。這個(gè)原則能幫你規(guī)避掉上面 90% 的坑。另外大家可能也發(fā)現(xiàn)了整個(gè)鏈路里所有圖片在服務(wù)端看來(lái)都不是“文件”而是“字符串”——這其實(shí)是 PDF 生成領(lǐng)域的一種穩(wěn)定哲學(xué)把資源內(nèi)聯(lián)化消除外部依賴(lài)。小到一篇文章大到一份合同只要圖片全部以 base64 內(nèi)嵌PDF 生成器就成了一個(gè)無(wú)狀態(tài)引擎不會(huì)因?yàn)槁窂?、?quán)限、防盜鏈、過(guò)期時(shí)間這些變量而翻車(chē)。最后再補(bǔ)充一個(gè)個(gè)人習(xí)慣小程序端每次轉(zhuǎn)完 base64 后順手把生成 HTML 的片段打個(gè)日志打印出來(lái)挑幾個(gè)字符看一眼前綴是不是data:image。這個(gè)動(dòng)作只要 5 秒鐘卻能讓你在后續(xù)“圖片又沒(méi)了”的排查里少走一個(gè)小時(shí)彎路。祝你一次跑通再也不被圖片空白問(wèn)題折磨。 小程序圖片轉(zhuǎn)Base64：徹底解決HTML轉(zhuǎn)PDF圖片丟失問(wèn)題
做小程序開(kāi)發(fā)這幾年但凡涉及“生成 PDF 報(bào)告”“導(dǎo)出電子合同”“分享帶圖卡片”十有八九都會(huì)撞上同一個(gè)難題圖片在頁(yè)面上顯示得好好的一進(jìn) PDF 就消失或者只有一行排版的“幽靈”占位符。踩過(guò)幾次坑之后我才徹底明白這個(gè)小程序里的圖片想lnthtml 轉(zhuǎn) PDF基本繞不開(kāi) base64 這條路。今天就把這個(gè)問(wèn)題的來(lái)龍去脈、各種轉(zhuǎn)換方案、以及我在 SelectPdf 上踩過(guò)的坑一次性講清楚。1. 問(wèn)題本質(zhì)為什么 PDF 引擎讀不到小程序里的圖片先別急著寫(xiě)代碼搞清楚底層原因比啥都重要。你用 SelectPdf 這類(lèi)服務(wù)端渲染庫(kù)去轉(zhuǎn)換 PDF 時(shí)它本質(zhì)上是一個(gè)獨(dú)立于小程序環(huán)境的 HTML 渲染引擎。這個(gè)引擎執(zhí)行 JS、解析 CSS、加載資源全都發(fā)生在你的服務(wù)器上。它和你的小程序客戶(hù)端隔著整個(gè)網(wǎng)絡(luò)。1.1 小程序圖片的三種來(lái)源后端一個(gè)都拿不到小程序里的圖片資源無(wú)非這三種來(lái)源網(wǎng)絡(luò) URLhttps://your-cdn.com/images/logo.png。理論上后端能訪(fǎng)問(wèn)但現(xiàn)實(shí)中往往被防盜鏈、跨域策略、臨時(shí)簽名失效擋住而且如果這張圖來(lái)自小程序云存儲(chǔ)URL 里多半帶動(dòng)態(tài)簽名轉(zhuǎn) PDF 那一刻可能已經(jīng)過(guò)期。本地臨時(shí)文件wxfile://tmp_xxx/photo.jpg。這是小程序最常用的方式場(chǎng)景里拍照、選圖后得到的都是這種本地路徑。可這個(gè)路徑是客戶(hù)端文件系統(tǒng)里的路徑服務(wù)器端 SelectPdf 連你這臺(tái)電腦的文件都讀不到更何況是千里之外的手機(jī)沙箱。云文件 IDcloud://env-id.xxxx/xxx.png。這個(gè)更特殊只有小程序端通過(guò)云能力才能解析后端拿到的就是一個(gè)字符串 ID無(wú)法直接當(dāng)圖片 URL 用。所以你會(huì)看到一種詭異現(xiàn)象在小程序里用 web-view 預(yù)覽那個(gè) HTML 時(shí)圖片正常顯示因?yàn)?web-view 在客戶(hù)端運(yùn)行能訪(fǎng)問(wèn)本地文件但一旦把同樣的 HTML 字符串 POST 給后端 SelectPdf圖片全掛。1.2 PDF 渲染引擎的加載機(jī)制要理解怎么辦先得理解 SelectPdf 這類(lèi)引擎的工作方式。它會(huì)解析 HTML 字符串構(gòu)建 DOM碰到img標(biāo)簽時(shí)根據(jù)src屬性去發(fā)起資源請(qǐng)求。如果src是wxfile://開(kāi)頭引擎根本不認(rèn)識(shí)這個(gè)協(xié)議如果src是相對(duì)路徑/images/a.png引擎會(huì)嘗試基于一個(gè) BaseUrl 去拼接但你顯然沒(méi)給它配如果是公網(wǎng) URL 但圖片服務(wù)器有防盜鏈Referer 校驗(yàn)失敗就直接返回 403?？偠灾矆D片路徑存在一點(diǎn)不確定性最終 PDF 里就是一片空白。這也就是標(biāo)題里那句“圖片必須編碼”的由來(lái)——不是玄學(xué)是傳輸鏈路決定的。1.3 base64 為什么能成為終極解決方案base64 本質(zhì)上是用 64 個(gè)可打印字符來(lái)表示二進(jìn)制數(shù)據(jù)。一張圖片的二進(jìn)制內(nèi)容經(jīng)過(guò)編碼后變成一串字符然后以?xún)?nèi)聯(lián)方式塞進(jìn) HTMLimg srcdata:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... /data:URI 是 RFC 2397 定義的方案瀏覽器的渲染引擎見(jiàn)到這種src不需要發(fā)任何網(wǎng)絡(luò)請(qǐng)求直接解碼字符串里的二進(jìn)制數(shù)據(jù)并渲染。不管你是本地臨時(shí)文件、網(wǎng)絡(luò)圖片還是云文件只要在小程序端把它轉(zhuǎn)成了 base64 字符串塞進(jìn) HTML 里后端 SelectPdf 就一定能渲染出圖片來(lái)。這個(gè)方案跨平臺(tái)、跨語(yǔ)言、沒(méi)有防盜鏈問(wèn)題笨但是絕對(duì)可靠。2. 小程序圖片轉(zhuǎn) base64 的三種實(shí)操方案在實(shí)際開(kāi)發(fā)中不同場(chǎng)景的圖片得用不同姿勢(shì)去轉(zhuǎn) base64。我總結(jié)下來(lái)就是三板斧讀臨時(shí)文件、下載網(wǎng)絡(luò)圖再讀、canvas 繪制導(dǎo)出。2.1 方案一FileSystemManager 讀取本地臨時(shí)文件如果你手里的圖片已經(jīng)在小程序的本地文件系統(tǒng)里比如wx.chooseImage、wx.chooseMedia返回的tempFilePath直接用FileSystemManager.readFile指定編碼為base64就能拿到 base64 字符串。const fs wx.getFileSystemManager(); function fileToBase64(filePath) { return new Promise((resolve, reject) { fs.readFile({ filePath: filePath, encoding: base64, success(res) { resolve(res.data); // 這里是純 base64 字符串沒(méi)有 data:image 前綴 }, fail(err) { reject(err); } }); }); } // 使用示例選擇圖片后馬上轉(zhuǎn) base64 wx.chooseMedia({ count: 1, mediaType: [image], success: async (res) { const tempFilePath res.tempFiles[0].tempFilePath; const base64 await fileToBase64(tempFilePath); console.log(base64); } });注意這里有個(gè)細(xì)節(jié)readFile返回的base64字符串是不含data:image/jpeg;base64,前綴的。你得自己拼上圖片的 MIME 類(lèi)型才能變成 HTML 能識(shí)別的 data URIfunction buildDataUri(base64, mimeType image/jpeg) { return data:${mimeType};base64,${base64}; }MIME 類(lèi)型怎么拿可以根據(jù)文件后綴判斷.jpg-image/jpeg.png-image/png.gif-image/gif.webp-image/webp。如果你用wx.chooseMedia返回的tempFiles[0].fileType也可以作為參考。2.2 方案二網(wǎng)絡(luò)圖片先下載再轉(zhuǎn) base64如果圖片本身是網(wǎng)絡(luò) URL直接轉(zhuǎn) base64 需要在服務(wù)端解決防盜鏈小程序端最穩(wěn)妥的辦法是先用wx.downloadFile把圖片下載成臨時(shí)文件然后再走方案一的readFile。function downloadFileToBase64(url) { return new Promise((resolve, reject) { wx.downloadFile({ url: url, success: async (res) { if (res.statusCode 200) { try { const base64 await fileToBase64(res.tempFilePath); resolve({ tempFilePath: res.tempFilePath, base64 }); } catch (e) { reject(e); } } else { reject(new Error(下載失敗HTTP ${res.statusCode})); } }, fail: reject }); }); }為什么先下載再讀取因?yàn)閣x.downloadFile幫你繞過(guò)了很多瀏覽器環(huán)境和后端環(huán)境的限制。小程序內(nèi)部有自己的一套網(wǎng)絡(luò)棧能處理一些特殊域名證書(shū)、跳過(guò)跨域限制前提是在后臺(tái)配置了合法域名。下載成功后圖片就變成了本地臨時(shí)文件再用readFile轉(zhuǎn) base64 就順理成章。注意wx.downloadFile有 10MB 的單文件大小限制iOS/Android 略有差異超過(guò)會(huì)走 fail 回調(diào)。真機(jī)測(cè)試時(shí)尤其要留意大圖場(chǎng)景。2.3 方案三canvas 重繪后導(dǎo)出 dataURL有些場(chǎng)景下圖片不能直接讀取文件內(nèi)容比如你從后端拿到的是一張需要加水印合成的圖片或者你想在導(dǎo)出 PDF 前把圖片壓縮一下。這時(shí)候可以用wx.createOffscreenCanvas或者傳統(tǒng)的canvas組件把圖片繪制到畫(huà)布上再通過(guò)wx.canvasToDataURL導(dǎo)出。function drawImageToDataUrl(imagePath, { width 750, height 750 } {}) { return new Promise((resolve, reject) { const offscreenCanvas wx.createOffscreenCanvas({ type: 2d, width, height }); const ctx offscreenCanvas.getContext(2d); const img offscreenCanvas.createImage(); img.onload () { ctx.clearRect(0, 0, width, height); // 等比縮放繪制 const scale Math.min(width / img.width, height / img.height); const dw img.width * scale; const dh img.height * scale; const dx (width - dw) / 2; const dy (height - dh) / 2; ctx.drawImage(img, dx, dy, dw, dh); const dataUrl offscreenCanvas.toDataURL(image/jpeg, 0.8); resolve(dataUrl); }; img.onerror reject; img.src imagePath; }); }這里產(chǎn)出的dataUrl是完整的data:image/jpeg;base64,...格式可以直接拼接進(jìn) HTML。這種方式最大的好處是可以順便壓縮圖片把 2MB 的圖壓到 200KB后面請(qǐng)求后端接口時(shí)壓力小很多。2.4 三種方案怎么選一張表講清楚場(chǎng)景首選方案原因拍照/相冊(cè)選圖后的臨時(shí)文件方案一直接讀文件開(kāi)銷(xiāo)最小網(wǎng)絡(luò)圖片、CDN 圖片方案二先下載解決防盜鏈再轉(zhuǎn)碼需要壓縮、加水印、裁剪方案三順便處理圖片一舉兩得云文件 ID先換 https 鏈接再走方案二wx.cloud.getTempFileURL換臨時(shí)鏈接我個(gè)人的習(xí)慣是只要圖片不是特別大一律先走 canvas 壓縮到 80% 質(zhì)量再編碼。省下來(lái)的流量和時(shí)間在弱網(wǎng)環(huán)境下體感差異非常明顯。3. SelectPdf 集成與圖片渲染完整實(shí)操當(dāng)你手里已經(jīng)有了一堆 base64 字符串接下來(lái)要做的就是把它們拼進(jìn) HTML交給 SelectPdf 轉(zhuǎn) PDF。這一節(jié)我會(huì)給出一套能直接跑通的完整流程。3.1 SelectPdf 的基本定位和工作原理SelectPdf 是一個(gè) .NET 平臺(tái)的 HTML 轉(zhuǎn) PDF 組件它基于自家的渲染內(nèi)核能解析 HTML CSS JavaScript生成 PDF 文件。它解決的核心痛點(diǎn)是PDF 排版極難手工控制而 HTML/CSS 排版有天然優(yōu)勢(shì)寫(xiě)完頁(yè)面模板直接轉(zhuǎn) PDF省去報(bào)表引擎那一大堆代碼。使用它非常直觀核心就是一個(gè)HtmlToPdf類(lèi)using SelectPdf; var converter new HtmlToPdf(); var pdfDoc converter.ConvertHtmlString(htmlContent); pdfDoc.Save(output.pdf); pdfDoc.Close();你可能會(huì)問(wèn)為什么不在前端用 html2canvas jsPDF老實(shí)說(shuō)小程序環(huán)境的 DOM 模型和瀏覽器差別很大html2canvas 在小程序里水土不服而 jsPDF 是一行行手動(dòng)追加內(nèi)容做復(fù)雜排版能寫(xiě)到懷疑人生。服務(wù)端 SelectPdf 用 HTML CSS 控制樣式模板復(fù)用度高后端還能順手加頁(yè)眉頁(yè)腳、頁(yè)碼水印所以在正經(jīng)業(yè)務(wù)里我更推薦這個(gè)鏈路。3.2 轉(zhuǎn)換前的圖片壓縮與編碼處理回到小程序端。假設(shè)用戶(hù)在小程序里填完一份體檢報(bào)告里面有一個(gè)指標(biāo)異常提示圖、一個(gè)趨勢(shì)圖canvas 繪制。你需要把這些圖都轉(zhuǎn)成 base64然后塞進(jìn)待傳給后端的 JSON 里。async function buildPdfPayload(formData, images) { const imageDataUris []; for (let i 0; i images.length; i) { const imgInfo images[i]; let dataUri ; if (imgInfo.type temp) { const b64 await fileToBase64(imgInfo.path); dataUri data:${imgInfo.mime};base64,${b64}; } else if (imgInfo.type network) { const res await downloadFileToBase64(imgInfo.url); dataUri data:${imgInfo.mime};base64,${res.base64}; } else if (imgInfo.type canvas) { dataUri await drawImageToDataUrl(imgInfo.path, { width: 600, height: 400 }); } imageDataUris.push(dataUri); } return { ...formData, htmlContent: renderReportHtml(formData, imageDataUris) }; }renderReportHtml就用模板字符串把圖片的 data URI 嵌進(jìn)去function renderReportHtml(formData, imageDataUris) { const imageTags imageDataUris.map((uri, idx) { return img src${uri} stylemax-width:100%;margin:10px 0; /; }).join(); return !DOCTYPE html html head meta charsetutf-8 / style body { font-family: PingFang SC, Microsoft YaHei, sans-serif; padding: 20px; color: #333; } h1 { text-align: center; border-bottom: 2px solid #1890ff; padding-bottom: 10px; } .info-row { display: flex; justify-content: space-between; margin: 8px 0; } .highlight { color: #e6a23c; font-weight: bold; } /style /head body h1${formData.title}/h1 div classinfo-rowspan姓名/spanspan${formData.name}/span/div div classinfo-rowspan報(bào)告日期/spanspan${formData.date}/span/div div classinfo-rowspan異常指標(biāo)/spanspan classhighlight${formData.alertCount} 項(xiàng)/span/div ${imageTags} /body /html; }然后把htmlContent通過(guò)wx.request發(fā)給后端wx.request({ url: https://your-server.com/api/convert, method: POST, data: { html: htmlContent }, success(res) { if (res.statusCode 200) { // 拿到 PDF 文件臨時(shí)路徑 const pdfPath res.data.pdfPath; wx.openDocument({ filePath: pdfPath, fileType: pdf }); } } });3.3 服務(wù)端 C# 接收 HTML 并生成 PDF服務(wù)端這邊我用 ASP.NET Core 寫(xiě)了個(gè)接口接收 JSON 里的 HTML調(diào)用 SelectPdf 轉(zhuǎn)換。要注意幾個(gè)關(guān)鍵配置[HttpPost(api/convert)] public IActionResult ConvertPdf([FromBody] PdfRequest request) { var converter new HtmlToPdf(); // 關(guān)鍵配置 converter.Options.PdfPageSize PdfPageSize.A4; converter.Options.PdfPageOrientation PdfPageOrientation.Portrait; converter.Options.MarginLeft 20; converter.Options.MarginRight 20; converter.Options.MarginTop 20; converter.Options.MarginBottom 20; converter.Options.WebPageWidth 750; // 按小程序設(shè)計(jì)稿寬度渲染 converter.Options.WebPageHeight 0; // 0 表示高度自適應(yīng) // 渲染 HTML var doc converter.ConvertHtmlString(request.Html); // 輸出到內(nèi)存流 using var ms new MemoryStream(); doc.Save(ms); doc.Close(); var pdfBytes ms.ToArray(); return File(pdfBytes, application/pdf, report.pdf); }WebPageWidth我建議設(shè)成 750 或者和你的小程序頁(yè)面寬度一致。SelectPdf 渲染頁(yè)面時(shí)會(huì)把 HTML 當(dāng)成一個(gè) 750px 寬的網(wǎng)頁(yè)來(lái)排版這樣圖片的max-width: 100%、流式布局才會(huì)有正確的視覺(jué)比例。如果默認(rèn) 1024有些擠壓效果或者換行位置會(huì)有偏差。3.4 圖片格式與 base64 編碼的細(xì)節(jié)控制SelectPdf 對(duì)圖片格式的兼容性不錯(cuò)JPG、PNG、WebP 基本都能正確處理。但有幾個(gè)細(xì)節(jié)圖片格式統(tǒng)一成 JPG 或 PNG 就夠了。小程序里經(jīng)常會(huì)遇到image/gif轉(zhuǎn) PDF 時(shí) gif 動(dòng)圖只會(huì)取第一幀而且 base64 體積很大。如果只是靜態(tài)展示建議在 canvas 方案里強(qiáng)制轉(zhuǎn)成 JPEG。base64 字符串的完整性。后端接到的 base64 可能有換行符、空格SelectPdf 解析 data URI 時(shí)比較挑剔。你可以在后端做個(gè)清理request.Html Regex.Replace(request.Html, data:image/[^;];base64,([^])(?|), m { var clean m.Groups[1].Value.Replace(\r, ).Replace(\n, ).Replace( , ); return $data:image/jpeg;base64,{clean}; });我遇到過(guò)非常詭異的問(wèn)題前端傳給后端時(shí)請(qǐng)求體里 base64 被encodeURIComponent了一遍后端忘了decodeURIComponent導(dǎo)致data:image/jpeg;base64,%2F9j%2F...SelectPdf 當(dāng)然認(rèn)不出來(lái)。這種問(wèn)題排查起來(lái)很煩最好在前端發(fā)送前就約定好HTML 原文傳不轉(zhuǎn)義后端收到直接進(jìn)轉(zhuǎn)換器。base64 體積暴漲 33%接口要提前做好預(yù)案。原始圖片 1MB轉(zhuǎn) base64 后約 1.37MB。如果一個(gè) PDF 里有 5 張這樣的圖POST 體積就接近 7MB。很多網(wǎng)關(guān)默認(rèn)有 1MB/10MB 的請(qǐng)求體限制線(xiàn)上環(huán)境要確認(rèn) nginx 的client_max_body_size和后端框架的MaxRequestBodySize否則會(huì)出現(xiàn)“小圖正常大圖 413”的詭異問(wèn)題。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這段是我最想寫(xiě)的因?yàn)楣馐恰皥D片轉(zhuǎn) base64 后 PDF 里還是不顯示”這一個(gè)問(wèn)題我就在生產(chǎn)環(huán)境折騰過(guò)整整一天。下面把典型的坑和排查思路都列出來(lái)。4.1 圖片不顯示但 HTML 里明明有 data URI現(xiàn)象后端日志里能看到 HTML 里有data:image/jpeg;base64,...但 PDF 輸出中圖片位置是空白。排查步驟把后端收到的 HTML 字符串原樣保存成.html文件用 Chrome 打開(kāi)。這是最重要的一步——先確認(rèn) HTML 本身沒(méi)問(wèn)題。如果 Chrome 里也空白說(shuō)明 base64 數(shù)據(jù)本身就是壞的問(wèn)題出在前端編碼環(huán)節(jié)。檢查 base64 前綴里的 MIME 是否和真實(shí)文件類(lèi)型匹配。常見(jiàn)錯(cuò)誤是PNG 圖片卻標(biāo)注了data:image/jpeg某些渲染內(nèi)核會(huì)比較嚴(yán)格按 jpeg 解碼 png 數(shù)據(jù)直接失敗。檢查 base64 里是否混入了\n、\r、空格。理論上 data URI 里不應(yīng)該有這些字符。部分庫(kù)能容忍SelectPdf 我實(shí)測(cè)下來(lái)對(duì)它很敏感清理干凈最穩(wěn)。我踩過(guò)的具體例子小程序端用了wx.getFileSystemManager().readFile的encoding: base64但圖片路徑是云文件 IDcloud://...readFile 直接報(bào)錯(cuò)我當(dāng)時(shí)沒(méi)接fail回調(diào)結(jié)果 base64 是一個(gè)空字符串頁(yè)面和 HTML 都“正?！本褪菦](méi)圖。4.2 圖片在部分手機(jī)上正常部分手機(jī)空白現(xiàn)象同樣一套代碼iOS 上生成 PDF 有圖Android 上沒(méi)有。這種問(wèn)題大多數(shù)出在圖片路徑的時(shí)效性上。wx.downloadFile的臨時(shí)文件在onUnload后基本就沒(méi)了如果用戶(hù)從選擇圖片頁(yè)面跳轉(zhuǎn)到預(yù)覽頁(yè)面兩個(gè)頁(yè)面之間通過(guò)全局變量存了tempFilePath但底層的臨時(shí)文件已經(jīng)被回收那你readFile時(shí)拿到的是已經(jīng)失效的路徑。解決辦法在拿到臨時(shí)文件后立即轉(zhuǎn) base64不要存路徑只存 base64 字符串。這樣圖片數(shù)據(jù)就變成了內(nèi)存字符串和文件生命周期無(wú)關(guān)了。// 錯(cuò)誤做法只存路徑下次頁(yè)面再用 globalData.tempImagePath tempFilePath; // 正確做法立刻轉(zhuǎn) base64 存起來(lái) globalData.tempImageBase64 await fileToBase64(tempFilePath);4.3 base64 太大導(dǎo)致請(qǐng)求超時(shí)或內(nèi)存暴漲現(xiàn)象圖片一多小程序端wx.request直接fail超時(shí)或者后端進(jìn)程內(nèi)存突然飆高。這不僅是網(wǎng)絡(luò)問(wèn)題還是性能問(wèn)題。base64 文本在 JSON 序列化/反序列化時(shí)會(huì)被復(fù)制多份內(nèi)存圖片數(shù)據(jù)動(dòng)輒幾 MB在小程序這種 JSCore 環(huán)境下很容易觸發(fā)內(nèi)存告警。我的處理思路是分級(jí)優(yōu)化第一級(jí)canvas 壓縮。把長(zhǎng)邊壓到 800px、質(zhì)量 80%肉眼基本看不出差異體積卻能縮小 70% 以上。 第二級(jí)PDF 不需要透明通道的場(chǎng)景全部轉(zhuǎn) JPEG不要用 PNG。PNG 的 base64 膨脹率更高。 第三級(jí)大圖拆分請(qǐng)求不要一次性把 10 張圖塞一個(gè)請(qǐng)求里按 3~4 張一批后端分頁(yè)合成 PDF。4.4 防盜鏈與 Referer 校驗(yàn)的坑小程序端wx.downloadFile的網(wǎng)絡(luò)棧是白名單制的所以能下載的圖基本都是合法域名。但有時(shí)候你從某個(gè)圖片 CDN 下載沒(méi)問(wèn)題后端 SelectPdf 直接訪(fǎng)問(wèn)原圖 URL 卻被 403這就是防盜鏈。遇到這種情況不必和后端去糾結(jié)配 Referer 白名單小程序端直接把圖下載轉(zhuǎn)成 base64 就完事了。base64 內(nèi)聯(lián)進(jìn) HTML 后SelectPdf 不會(huì)再去發(fā)圖片請(qǐng)求防盜鏈規(guī)則形同虛設(shè)。這是我強(qiáng)烈推薦“先下載再轉(zhuǎn)碼”的核心理由。4.5 臨時(shí)文件堆滿(mǎn)存儲(chǔ)空間小程序端每downloadFile一次都會(huì)在用戶(hù)設(shè)備上殘留臨時(shí)文件。如果用戶(hù)高頻操作臨時(shí)文件積累多了會(huì)占滿(mǎn)存儲(chǔ)空間。雖然wx.downloadFile返回的tempFilePath會(huì)在小程序退出時(shí)清理但同一會(huì)話(huà)內(nèi)頻繁生成也會(huì)有問(wèn)題。實(shí)操建議轉(zhuǎn)完 base64 以后主動(dòng)清理臨時(shí)文件const fs wx.getFileSystemManager(); // 不需要的臨時(shí)文件直接刪掉 try { fs.unlinkSync(tempFilePath); } catch (e) { // 忽略刪除失敗臨時(shí)文件后續(xù)還會(huì)被系統(tǒng)回收 }4.6 常見(jiàn)問(wèn)題速查表癥狀可能原因快速解決PDF 圖片空白但 HTML 正常base64 含換行空格、MIME 類(lèi)型不對(duì)后端正則清理嚴(yán)格校驗(yàn) MIME部分機(jī)型失敗臨時(shí)文件被回收拿到路徑立刻轉(zhuǎn) base64別存路徑請(qǐng)求 413 或超時(shí)base64 體積過(guò)大、網(wǎng)關(guān)限制壓縮圖片、分批提交、調(diào)大請(qǐng)求體限制圖片拉伸變形canvas 繪制時(shí)未等比縮放用Math.min計(jì)算縮放比例居中繪制圖片模糊原圖分辨率低、canvas 導(dǎo)出尺寸小提高 canvas 尺寸到 2 倍設(shè)置 quality 0.9WebP 格式異常SelectPdf 對(duì)部分 WebP 解碼兼容性差統(tǒng)一轉(zhuǎn) JPEG5. 這套流程還能怎么擴(kuò)展從單圖到批量 PDF 的工程化改造前面講的都是單份 PDF 的生成流程。真實(shí)業(yè)務(wù)里往往是一個(gè)訂單下有多個(gè)報(bào)告或者一個(gè)批次要生成幾百份合同。在這個(gè)基礎(chǔ)上我對(duì)這個(gè)方案又做了幾層工程化改造也算是給讀者一條進(jìn)階路徑。5.1 模板與數(shù)據(jù)分離小程序的 HTML 模板不要硬編碼在后端 C# 里也不要在前端字符串拼建議統(tǒng)一放到后端模板管理表里。小程序端只傳業(yè)務(wù)數(shù)據(jù)name、date、images 數(shù)組后端用 Razor 模板引擎或者簡(jiǎn)單的字符串模板去渲染最終 HTML。好處是排版的調(diào)整不需要發(fā)版小程序只更新服務(wù)端模板就行。5.2 批量生成 異步任務(wù)隊(duì)列當(dāng)圖片數(shù)量巨大時(shí)同步ConvertHtmlString會(huì)長(zhǎng)時(shí)間占用后端線(xiàn)程。建議引入消息隊(duì)列比如 RabbitMQ 或者簡(jiǎn)單的 Redis 隊(duì)列。請(qǐng)求進(jìn)來(lái)先返回“任務(wù)ID”后臺(tái) Worker 逐份渲染 PDF完成后推送到小程序。小程序的體驗(yàn)就是用戶(hù)點(diǎn)了“生成報(bào)告”頁(yè)面出現(xiàn)一個(gè)“處理中”的進(jìn)度條1~2 秒后服務(wù)端主動(dòng)推送 PDF 地址再wx.openDocument打開(kāi)。比同步卡死優(yōu)雅太多。5.3 PDF 的頁(yè)眉頁(yè)腳、頁(yè)碼、水印SelectPdf 這塊做得比較完善。合同場(chǎng)景下頁(yè)腳可以放頁(yè)碼、公司電話(huà)頁(yè)眉放公司 logo這個(gè) logo 又是一張圖同樣轉(zhuǎn) base64。水印可以在converter.Options里配置也可以在 HTML 里用 CSS 畫(huà)一個(gè)半透明背景層。我實(shí)測(cè)下來(lái)CSS 水印在 PDF 渲染里很穩(wěn)定多頁(yè)內(nèi)容會(huì)重復(fù)出現(xiàn)在每頁(yè)上效果比組件自帶的更可控。6. 寫(xiě)在最后的一點(diǎn)經(jīng)驗(yàn)如果要在這一堆實(shí)操里挑一句最想對(duì)后來(lái)人說(shuō)的別在小程序端做任何依賴(lài)“文件路徑”的持久化圖片數(shù)據(jù)必須在你還在當(dāng)前頁(yè)面環(huán)境時(shí)立刻轉(zhuǎn)化為 base64。這個(gè)原則能幫你規(guī)避掉上面 90% 的坑。另外大家可能也發(fā)現(xiàn)了整個(gè)鏈路里所有圖片在服務(wù)端看來(lái)都不是“文件”而是“字符串”——這其實(shí)是 PDF 生成領(lǐng)域的一種穩(wěn)定哲學(xué)把資源內(nèi)聯(lián)化消除外部依賴(lài)。小到一篇文章大到一份合同只要圖片全部以 base64 內(nèi)嵌PDF 生成器就成了一個(gè)無(wú)狀態(tài)引擎不會(huì)因?yàn)槁窂?、?quán)限、防盜鏈、過(guò)期時(shí)間這些變量而翻車(chē)。最后再補(bǔ)充一個(gè)個(gè)人習(xí)慣小程序端每次轉(zhuǎn)完 base64 后順手把生成 HTML 的片段打個(gè)日志打印出來(lái)挑幾個(gè)字符看一眼前綴是不是data:image。這個(gè)動(dòng)作只要 5 秒鐘卻能讓你在后續(xù)“圖片又沒(méi)了”的排查里少走一個(gè)小時(shí)彎路。祝你一次跑通再也不被圖片空白問(wèn)題折磨。