簡(jiǎn)介面向需要在 Java 項(xiàng)目中實(shí)現(xiàn) Excel 表格與圖表截圖導(dǎo)出的開(kāi)發(fā)者這份資料圍繞 Aspose.Cells 去水印與截圖場(chǎng)景整理適合作為個(gè)人學(xué)習(xí)與功能驗(yàn)證的參考。壓縮包共 5 個(gè)文件約 12MB包含 2 個(gè) jar 庫(kù)文件、1 個(gè) Java 演示程序、1 個(gè) xlsx 示例工作簿和 1 個(gè)本地 Maven 導(dǎo)入說(shuō)明覆蓋從依賴引入到樣例運(yùn)行的多個(gè)環(huán)節(jié)。已有 922 人學(xué)習(xí)下載說(shuō)明該方向具備一定實(shí)踐需求。讀者可借助演示代碼快速理解 Aspose.Cells 的調(diào)用方式結(jié)合示例工作簿對(duì)照截圖與圖表導(dǎo)出效果并通過(guò)導(dǎo)入說(shuō)明減少本地倉(cāng)庫(kù)配置時(shí)的阻礙資源描述中也提示了使用細(xì)節(jié)與缺失代碼的查閱位置便于進(jìn)一步排查問(wèn)題。需注意僅供個(gè)人學(xué)習(xí)請(qǐng)勿用于商業(yè)用途。1. 一張 Excel 預(yù)覽圖背后jar 包選型與那條甩不掉的水印上周有人把一個(gè) excel截圖jar.zip 丟過(guò)來(lái)說(shuō)用 Aspose.cells 把 Excel 導(dǎo)成截圖右下角永遠(yuǎn)壓著一條紅色評(píng)估字樣問(wèn)「去水印」是不是改個(gè)配置就能解決。我拆開(kāi)看完結(jié)論是這類 jar 包真正要解決的是「服務(wù)端把 xlsx 穩(wěn)定渲染成 PNG」這件事本身不復(fù)雜真正麻煩的是三處評(píng)估版限制怎么判定、渲染參數(shù)怎么影響成圖、容器里字體和線程怎么處理。它適合需要批量出表格預(yù)覽圖、報(bào)表縮略圖、審批留檔圖的后端同學(xué)不適合只想在瀏覽器里看表格的前端場(chǎng)景那種情況直接上在線表格組件更劃算。下面按「怎么選鏈路、怎么跑通、參數(shù)怎么調(diào)、水印從哪來(lái)、線上怎么排查」的順序拆一遍。2. 三條渲染鏈路怎么選從 POI 拼圖到 jar 包直出在動(dòng)手之前先想清楚一件事Excel 截圖不是「把文件讀出來(lái)」這么簡(jiǎn)單它本質(zhì)是一次排版渲染要把單元格樣式、列寬、合并、條件格式、嵌入圖片、圖表全部還原成像素。不同鏈路能還原的比例差別很大選錯(cuò)了后面全是補(bǔ)丁。2.1 三條鏈路的能力邊界對(duì)照落到工程上常見(jiàn)的就三條路我按實(shí)際踩過(guò)的順序列一下。鏈路樣式還原圖表/圖片部署依賴單頁(yè)耗時(shí)典型適用場(chǎng)景POI 逐單元格繪制需自己寫(xiě) Graphics2D基本不支持純 Java低幾十 ms固定模板、列數(shù)極少的對(duì)賬表轉(zhuǎn) PDF 再轉(zhuǎn)圖高支持需裝辦公套件進(jìn)程中高2-5 s報(bào)表留檔、打印級(jí)輸出渲染庫(kù)直接出圖高支持純 Java 字體文件中200-800 ms服務(wù)端批量預(yù)覽、接口同步返回第一條路很多人一開(kāi)始都會(huì)試POI 讀出 CellStyle拿 BufferedImage 一格一格畫(huà)。小表格能跑一旦遇到合并單元格、條件格式色階、凍結(jié)窗格就得不停補(bǔ)分支補(bǔ)到最后代碼比業(yè)務(wù)還長(zhǎng)。第二條路是把 xlsx 丟給無(wú)頭辦公套件轉(zhuǎn)成 PDF再用 pdftoppm 轉(zhuǎn) PNG還原度是三條里最高的代價(jià)是要在容器里裝一個(gè)幾百 MB 的進(jìn)程冷啟動(dòng)慢并發(fā)還要自己池化。第三條就是這份 jar 包走的路純 Java 進(jìn)程內(nèi)渲染一次調(diào)用直接吐 PNG 到磁盤(pán)或 OutputStream接口里能同步返回是預(yù)覽場(chǎng)景最省事的一種。選型判斷其實(shí)就一句話如果預(yù)覽圖要跟著接口實(shí)時(shí)返回、QPS 有要求走第三類如果是每天定時(shí)生成一批留檔圖、對(duì)還原度要求極高第二條更穩(wěn)如果表格結(jié)構(gòu)固定到列數(shù)都不變第一條成本最低。2.2 把 jar 包塞進(jìn) Maven 工程兩種引入方式如果目標(biāo)版本能從倉(cāng)庫(kù)拉到直接在 pom 里聲明就行版本號(hào)以你手上 jar 包的實(shí)際版本為準(zhǔn)別照抄別人的dependency groupIdcom.aspose/groupId artifactIdaspose-cells/artifactId version${aspose-cells.version}/version /dependency拿到的是 zip 里的獨(dú)立 jar就走本地安裝把它推進(jìn)本地倉(cāng)庫(kù)或私服團(tuán)隊(duì)其他人就不用各自拷貝了# -Dfile 指向解壓后的真實(shí) jar 路徑 # groupId/artifactId 保持與官方坐標(biāo)一致后面換倉(cāng)庫(kù)版不用改 import mvn install:install-file \ -Dfile./lib/aspose-cells.jar \ -DgroupIdcom.aspose \ -DartifactIdaspose-cells \ -Dversion0.0.0-local \ -Dpackagingjar \ -DgeneratePomtrue這里幾個(gè)參數(shù)值得說(shuō)一下-DgeneratePomtrue會(huì)順手生成一個(gè)最小 pom否則依賴進(jìn)私服后別人拉下來(lái)是殘缺的-Dversion建議帶個(gè)-local后綴一眼能看出這是手工裝進(jìn)去的包將來(lái)?yè)Q正式版好排查。還有一種寫(xiě)法是用scopesystem/scope加systemPath直接引本地文件我不推薦——打 fat jar 的時(shí)候極容易漏掉本地跑得好好的上線就 NoClassDefFoundError屬于典型的「本地玄學(xué)、線上血淚」。提示安裝完成后執(zhí)行一次mvn dependency:tree | grep -i aspose確認(rèn)依賴真的進(jìn)來(lái)了比對(duì)著 pom 猜快得多。2.3 跑通第一張導(dǎo)出圖最小可運(yùn)行示例先別急著封裝工具類寫(xiě)一個(gè)能一次跑通的 main把整條鏈路走一遍后面所有參數(shù)都在這個(gè)骨架上加。import com.aspose.cells.*; public class ExcelToPng { public static void main(String[] args) throws Exception { // 1. 授權(quán)必須在第一次 new Workbook 之前加載否則本進(jìn)程內(nèi)會(huì)一直按評(píng)估版渲染 License license new License(); try { license.setLicense(license.xml); } catch (Exception e) { // 不要靜默吞掉否則線上只能看到水印看不到真實(shí)原因 System.err.println(授權(quán)加載失敗輸出將帶評(píng)估水印: e.getMessage()); } // 2. 加載工作簿 Workbook wb new Workbook(input.xlsx); // 3. 渲染參數(shù) ImageOrPrintOptions opts new ImageOrPrintOptions(); opts.setImageType(ImageType.PNG); // 輸出格式 opts.setHorizontalResolution(200); // 橫向 DPI opts.setVerticalResolution(200); // 縱向 DPI opts.setOnePagePerSheet(true); // 整表壓到一頁(yè)大表慎用見(jiàn) 3.2 opts.setOnlyArea(true); // 只導(dǎo)出打印區(qū)域 opts.setPrintingPage(PrintingPageType.IGNORE_BLANK); // 跳過(guò)空白頁(yè) // 4. 逐 sheet 逐頁(yè)輸出 WorksheetCollection sheets wb.getWorksheets(); for (int i 0; i sheets.getCount(); i) { Worksheet ws sheets.get(i); if (ws.getName().startsWith(_)) { continue; // 約定下劃線開(kāi)頭的是隱藏的輔助頁(yè) } SheetRender render new SheetRender(ws, opts); for (int page 0; page render.getPageCount(); page) { String path String.format(out/%s_p%d.png, ws.getName(), page); render.toImage(page, path); } } } }這段代碼有幾個(gè)設(shè)計(jì)點(diǎn)值得展開(kāi)。第一授權(quán)加載放在最前面是因?yàn)殇秩編?kù)在類初始化階段就會(huì)讀取授權(quán)狀態(tài)一旦帶著評(píng)估狀態(tài)建過(guò) Workbook該 JVM 進(jìn)程內(nèi)后續(xù)再設(shè)置也可能不生效只能重啟。第二用SheetRender而不是工作簿級(jí)一次性導(dǎo)出好處是能按 sheet 跳過(guò)隱藏頁(yè)、能拿到單頁(yè)的 pageCount 做分頁(yè)控制輸出文件名也好定位問(wèn)題。第三setOnlyArea(true)依賴工作表里已經(jīng)設(shè)好的打印區(qū)域沒(méi)設(shè)的話等于導(dǎo)出整個(gè)已用區(qū)域邊界行為和你的預(yù)期可能差一截下一章會(huì)專門(mén)講。跑通之后你會(huì)得到out/下一批 PNG文件名帶 sheet 名和頁(yè)碼出問(wèn)題能直接對(duì)上是哪一頁(yè)。這一步別省很多人一上來(lái)就封裝成 Spring Bean結(jié)果連原始異常長(zhǎng)什么樣都沒(méi)見(jiàn)過(guò)。3. 導(dǎo)出參數(shù)逐項(xiàng)拆成圖質(zhì)量全押在這六個(gè)開(kāi)關(guān)上同樣一個(gè) xlsx參數(shù)調(diào)不對(duì)出來(lái)的圖可能是右邊切掉一列、中間糊成一片、或者整張圖只有 3 像素高。這一章把真正影響成圖的幾個(gè)開(kāi)關(guān)拆開(kāi)講。3.1 分辨率與像素格式200 DPI 是不是萬(wàn)能解DPI 決定的是「一英寸排多少像素」而 Excel 的頁(yè)面單位是英寸所以輸出位圖的像素尺寸約等于紙張寬英寸× DPI。A4 橫向 11.69 英寸200 DPI 下就是 2338 像素寬。這個(gè)尺寸丟給前端做縮略圖綽綽有余做 OCR 識(shí)別也基本夠用。常見(jiàn)的三檔取值我一般這么定場(chǎng)景建議 DPI單頁(yè)像素A4 橫向備注列表頁(yè)縮略圖96-1201123-1403 px體積小加載快詳情頁(yè)預(yù)覽150-2001754-2338 px中文小字號(hào)仍可辨認(rèn)打印/OCR/留檔3003508 px體積大注意內(nèi)存格式選擇上PNG 適合帶透明背景和線條清晰的表格JPEG 體積小但表格細(xì)線容易出鋸齒一般不用。要透明背景就opts.setTransparent(true)但只有 PNG 支持設(shè)成 JPEG 會(huì)直接報(bào)錯(cuò)或者被忽略。這里有個(gè)容易被忽略的賬位圖內(nèi)存是「寬 × 高 × 4 字節(jié)」。300 DPI 的 A4 單頁(yè)就是 3508 × 2480 × 4 ≈ 34 MB如果你把一張 50 頁(yè)的表壓成一頁(yè)尺寸會(huì)翻幾十倍JVM 直接原地起飛。先算清楚這個(gè)乘法比事后加-Xmx有用得多。ImageOrPrintOptions hiRes new ImageOrPrintOptions(); hiRes.setImageType(ImageType.PNG); hiRes.setHorizontalResolution(96); // 縮略圖檔 hiRes.setVerticalResolution(96); hiRes.setTransparent(false); // 白底更適合直接鋪在頁(yè)面上上面這段是我給列表頁(yè)用的配置96 DPI 出來(lái)的圖大概 100-300 KB七?；?OSS 上存幾十萬(wàn)張也不心疼。詳情頁(yè)再單獨(dú)走一套 200 DPI 的渲染兩套參數(shù)分開(kāi)配置別想著一個(gè)配置吃所有場(chǎng)景。3.2 打印區(qū)域、縮放與分頁(yè)整表壓一頁(yè)的代價(jià)setOnePagePerSheet(true)是最容易被濫用的一個(gè)開(kāi)關(guān)。它的語(yǔ)義是「把這個(gè) sheet 的所有內(nèi)容縮放到一頁(yè)里」聽(tīng)起來(lái)很美好實(shí)際效果是一張 500 行的表會(huì)被壓成高度只有幾個(gè)像素的細(xì)條字全糊在一起。正確的姿勢(shì)是先定打印區(qū)域再定縮放策略// 只渲染 A1 到 H40 這塊區(qū)域避免把整個(gè)已用區(qū)域拖進(jìn)來(lái) ws.getPageSetup().setPrintArea(A1:H40); // 橫向鋪滿 1 頁(yè)寬縱向允許多頁(yè)保持字號(hào)可讀 ws.getPageSetup().setOrientation(PageOrientationType.LANDSCAPE); ws.getPageSetup().setFitToPagesWide(1); ws.getPageSetup().setFitToPagesTall(0); // 0 表示縱向不限制參數(shù)含義setFitToPagesWide(1)是橫向壓到 1 頁(yè)setFitToPagesTall(0)表示縱向按內(nèi)容自然分頁(yè)不強(qiáng)行壓。這樣出來(lái)的效果是橫向不失真、縱向該分幾頁(yè)分幾頁(yè)SheetRender.getPageCount()會(huì)如實(shí)返回頁(yè)數(shù)。如果你確實(shí)要整表一頁(yè)比如給文件列表出個(gè)總覽縮略圖那就得加保護(hù)先判斷已用區(qū)域的行數(shù)超過(guò)閾值我一般設(shè) 200 行就退回分頁(yè)模式或者把 DPI 降到 72。另外setPrintingPage(PrintingPageType.IGNORE_BLANK)建議常開(kāi)很多模板表尾部有一堆空白頁(yè)不去掉會(huì)白白多渲染幾張全白圖還占存儲(chǔ)。參數(shù)作用建議值副作用setOnePagePerSheet整表壓一頁(yè)小表 true大表 false大表嚴(yán)重壓縮變形setOnlyArea只導(dǎo)出打印區(qū)域true未設(shè)打印區(qū)域時(shí)行為等同整表setPrintingPage空白頁(yè)處理IGNORE_BLANK無(wú)setFitToPagesWide橫向頁(yè)數(shù)1列太多時(shí)字會(huì)很小3.3 列寬、合并單元格與右側(cè)截?cái)唷赣疫吷僖涣小故沁@類渲染里最常見(jiàn)的一類反饋成因有三個(gè)得分開(kāi)看。第一個(gè)是打印區(qū)域沒(méi)覆蓋到最后一列。setOnlyArea(true)生效的前提是工作表里有明確的打印區(qū)域如果你的模板是從別的系統(tǒng)導(dǎo)出的打印區(qū)域可能還停留在 A1:F30而你新加了 G、H 兩列那截?cái)嗍潜厝坏?。解決辦法是導(dǎo)出前動(dòng)態(tài)重設(shè)// 先讓列寬按內(nèi)容自適應(yīng)再按已用區(qū)域重新圈定打印區(qū)域 ws.autoFitColumns(); Cells cells ws.getCells(); int maxRow cells.getMaxDataRow(); // 最后一個(gè)有數(shù)據(jù)的行 int maxCol cells.getMaxDataColumn(); // 最后一個(gè)有數(shù)據(jù)的列 if (maxRow 0 maxCol 0) { String area CellsHelper.cellIndexToName(0, 0) : CellsHelper.cellIndexToName(maxRow, maxCol); ws.getPageSetup().setPrintArea(area); }這段邏輯的順序很關(guān)鍵必須先autoFitColumns()再取getMaxDataColumn()否則列寬還是模板里的舊值。CellsHelper.cellIndexToName是把「行號(hào)、列號(hào)」翻譯成「A1、H40」這種字符串的工具方法比手寫(xiě)列號(hào)字母轉(zhuǎn)換靠譜。第二個(gè)成因是列寬在容器里被算「寬」了。xlsx 里存的列寬單位是「標(biāo)準(zhǔn)字符數(shù)」渲染時(shí)需要按字體度量換算成像素容器里少了字體文件就會(huì)回退到默認(rèn)字體寬度整體偏移最后一列就被擠出打印區(qū)域。這個(gè)問(wèn)題的表現(xiàn)是「本地正常、服務(wù)器截?cái)唷购?5.1 的中文方框是同一個(gè)根因處理方式也一樣。第三個(gè)是合并單元格跨頁(yè)被切斷。橫向合并的單元格如果正好壓在分頁(yè)線上渲染時(shí)會(huì)被拆成兩半。這種情況沒(méi)法靠參數(shù)修只能調(diào)整打印區(qū)域或者在模板階段就把合并范圍收在單頁(yè)內(nèi)。我一般的做法是模板評(píng)審階段就用 200 DPI 導(dǎo)一次圖人眼看一遍有沒(méi)有跨頁(yè)斷裂比上線后被業(yè)務(wù)反饋強(qiáng)。4. 水印是怎么冒出來(lái)的評(píng)估版限制的判定與正規(guī)消除路徑這是整個(gè)包里最敏感也最容易被問(wèn)的一環(huán)。先把話說(shuō)清楚渲染庫(kù)在未授權(quán)狀態(tài)下導(dǎo)出圖片時(shí)加一條評(píng)估字樣這是產(chǎn)品本身的授權(quán)機(jī)制不是 bug也不是配置項(xiàng)。所謂「去水印」正規(guī)路徑只有一條——拿到授權(quán)并正確加載繞過(guò)授權(quán)去改 jar 包里的字符串屬于侵權(quán)而且這類包通常帶完整性校驗(yàn)改了大概率啟動(dòng)報(bào)錯(cuò)或者行為異常得不償失。4.1 三種典型水印形態(tài)與快速判定評(píng)估狀態(tài)的輸出有幾個(gè)穩(wěn)定特征可以先做判定再?zèng)Q定后續(xù)動(dòng)作形態(tài)出現(xiàn)位置是否授權(quán)問(wèn)題處置方式底部紅色評(píng)估字樣每頁(yè)圖片最下方是加載授權(quán)文件頁(yè)面中部斜向半透明大字覆蓋內(nèi)容區(qū)是加載授權(quán)文件每頁(yè)右上角小角標(biāo)固定偏移位置是加載授權(quán)文件內(nèi)容整體偏移、底部被裁位置不定否打印區(qū)域/頁(yè)邊距問(wèn)題判定方法很樸素用同一份 xlsx在加載授權(quán)前后各導(dǎo)一次圖肉眼比對(duì)。如果兩次圖的差異只在上述固定位置那就是授權(quán)如果差異在內(nèi)容區(qū)那是渲染參數(shù)問(wèn)題別往授權(quán)上賴。還有一種情況要單獨(dú)提導(dǎo)出的 PDF 干凈、導(dǎo)出的 PNG 有水印。這種一般是不同輸出路徑走了不同的編碼實(shí)現(xiàn)個(gè)別版本上確實(shí)存在差異但結(jié)論不變——沒(méi)授權(quán)就是沒(méi)授權(quán)換個(gè)格式只是換個(gè)地方出現(xiàn)。4.2 License 的加載時(shí)機(jī)為什么本地沒(méi)事、上線就有這是最高頻的一個(gè)坑本地 IDE 里跑得好好的打成 jar 部署到服務(wù)器就帶水印日志里干干凈凈什么異常都沒(méi)有。原因基本都是這一行// 錯(cuò)誤寫(xiě)法jar 包內(nèi)運(yùn)行時(shí)相對(duì)路徑指向的是工作目錄不是 classpath license.setLicense(license.xml);打成可執(zhí)行 jar 之后license.xml被壓在 jar 內(nèi)部FileInputStream那種相對(duì)路徑解析指向的是進(jìn)程工作目錄文件根本不存在拋出的異常又被catch吞了于是靜默降級(jí)成評(píng)估版。正確寫(xiě)法是從 classpath 讀流import com.aspose.cells.License; import java.io.InputStream; public final class LicenseHolder { private static volatile boolean loaded false; public static synchronized void init() { if (loaded) { return; } // 從 classpath 根目錄讀取jar 內(nèi) jar 外都能命中 try (InputStream in LicenseHolder.class.getResourceAsStream(/license.xml)) { if (in null) { throw new IllegalStateException(license.xml 不在 classpath 根目錄); } new License().setLicense(in); loaded true; } catch (Exception e) { // 拋出去讓啟動(dòng)失敗而不是帶著水印跑一整年 throw new IllegalStateException(授權(quán)加載失敗, e); } } }幾個(gè)細(xì)節(jié)try-with-resources保證流關(guān)閉setLicense只讀取一次讀完后流可以關(guān)volatile加synchronized是防并發(fā)重復(fù)初始化雖然重復(fù)調(diào)用本身無(wú)害但能省掉一次無(wú)謂的 IO最關(guān)鍵的是異常必須往外拋——授權(quán)失敗的靜默降級(jí)是所有「線上帶水印」問(wèn)題的共同源頭寧可讓?xiě)?yīng)用起不來(lái)。Spring 項(xiàng)目里在PostConstruct或ApplicationRunner里調(diào)用一次LicenseHolder.init()就夠了注意要在任何一次產(chǎn)出圖片的調(diào)用之前完成。熱部署場(chǎng)景比如某些開(kāi)發(fā)容器會(huì)重建 classloader下靜態(tài)標(biāo)記會(huì)被重置這種情況老老實(shí)實(shí)每次用之前判一下loaded為 false 就重新初始化。還有一點(diǎn)授權(quán)文件不要放進(jìn)src/main/resources/public這類會(huì)被靜態(tài)資源映射出去的目錄也不要打進(jìn)前端產(chǎn)物。它就應(yīng)該是 classpath 根目錄下一個(gè)安靜的文件。4.3 不引入商業(yè)庫(kù)時(shí)的替代渲染鏈路如果項(xiàng)目預(yù)算卡死、或者只是內(nèi)部小工具那就別硬上商業(yè)庫(kù)了走第二條鏈路用無(wú)頭辦公套件轉(zhuǎn) PDF 再轉(zhuǎn)圖效果同樣能打。# 第一步xlsx - pdf--headless 保證無(wú) GUI 環(huán)境下可運(yùn)行 soffice --headless \ --convert-to pdf \ --outdir ./pdf \ ./input.xlsx # 第二步pdf 每頁(yè) - png-r 控制 DPI與前面的分辨率概念一致 pdftoppm -png -r 200 ./pdf/input.pdf ./out/sheet參數(shù)說(shuō)明--headless必須加否則在沒(méi)有顯示服務(wù)的容器里會(huì)直接退出--convert-to pdf后面可以跟過(guò)濾器參數(shù)微調(diào)紙張和邊距一般默認(rèn)就夠pdftoppm的-r是 DPI-png指定輸出格式輸出文件會(huì)自動(dòng)帶上頁(yè)碼后綴。這條鏈路的問(wèn)題也得提前知道單次轉(zhuǎn)換有 2-5 秒的進(jìn)程冷啟動(dòng)并發(fā)高了 CPU 直接打滿所以必須用固定大小的進(jìn)程池去跑別在請(qǐng)求線程里同步調(diào)容器鏡像要裝中文字體否則一樣是方框轉(zhuǎn)換結(jié)果受套件版本影響同一個(gè)文件在不同版本上邊距可能差幾個(gè)像素做像素比對(duì)時(shí)要留容差。5. 五條線上翻車(chē)記錄Excel 截圖服務(wù)的排查清單下面這五條都是我在實(shí)際服務(wù)里遇到過(guò)的現(xiàn)象、原因、解決按順序?qū)懹龅筋愃瓢Y狀可以直接對(duì)號(hào)入座。5.1 中文全部變成方框現(xiàn)象本地 Windows 開(kāi)發(fā)機(jī)出圖完全正常部署到 Linux 容器后所有中文變成豆腐塊方框數(shù)字和英文不受影響。原因渲染時(shí)按字體名去系統(tǒng)里找字體容器基礎(chǔ)鏡像只帶了西文字體找不到中文字體就回退到內(nèi)置默認(rèn)字體默認(rèn)字體沒(méi)有中文字形。這不是編碼問(wèn)題別去查 UTF-8。解決兩步走。鏡像里裝字體同時(shí)代碼里顯式指定字體目錄雙保險(xiǎn)。# Dockerfile 片段裝 fontconfig 并把字體拷進(jìn)系統(tǒng)目錄 apt-get update apt-get install -y fontconfig mkdir -p /usr/share/fonts/truetype/app cp ./fonts/*.ttf /usr/share/fonts/truetype/app/ fc-cache -fv// 啟動(dòng)時(shí)注冊(cè)字體目錄第二個(gè)參數(shù) true 表示遞歸掃描子目錄 FontConfigs.setFontFolder(/usr/share/fonts/truetype/app, true); // 如果知道模板里指定的具體字體名再釘一層默認(rèn)字體防止回退 FontConfigs.setDefaultFontName(Microsoft YaHei);fc-cache -fv這步別省緩存不刷新的話字體裝了也可能找不到。驗(yàn)證方法是先跑一次導(dǎo)出看圖里的中文實(shí)在不確定就臨時(shí)在容器里執(zhí)行fc-list | grep -i cjk能看到字體名就說(shuō)明裝進(jìn)去了。5.2 大表導(dǎo)出直接 OOM現(xiàn)象一張二十萬(wàn)行的對(duì)賬表導(dǎo)出時(shí)堆內(nèi)存幾分鐘內(nèi)漲到上限進(jìn)程 OOM 退出偶爾不退出但產(chǎn)出的 PNG 是一張純白圖。原因開(kāi)啟了setOnePagePerSheet(true)等于要求把整表壓進(jìn)一張位圖。按 3.1 的算法寬高都會(huì)被拉到極限單張位圖占用幾個(gè) GB 是常態(tài)堆里放不下就直接掛。純白圖的成因是位圖尺寸超過(guò)了底層圖像庫(kù)的上限返回了一張空?qǐng)D但沒(méi)拋異常。解決三重限制一起上。行數(shù)超閾值就強(qiáng)制分頁(yè)、限制最大像素尺寸、降 DPI。// 行數(shù)保護(hù)超過(guò)閾值不走「整表一頁(yè)」 int maxRow ws.getCells().getMaxDataRow(); boolean tooLarge maxRow 200; opts.setOnePagePerSheet(!tooLarge); if (tooLarge) { opts.setHorizontalResolution(96); // 大表降 DPI 省內(nèi)存 opts.setVerticalResolution(96); }另外導(dǎo)出前后打一行已用區(qū)域尺寸的日志出問(wèn)題時(shí)第一眼就能看出是不是尺寸失控比事后 dump 堆?？臁?.3 并發(fā)下偶發(fā)空白圖或花屏現(xiàn)象單線程跑一百次全對(duì)用線程池壓到 8 并發(fā)偶爾出現(xiàn)空白 PNG或者圖片下半截是花的。原因Workbook和SheetRender都不是線程安全的多個(gè)線程共享同一個(gè)實(shí)例內(nèi)部狀態(tài)互相踩另一個(gè)常見(jiàn)原因是輸出文件名沖突兩個(gè)任務(wù)寫(xiě)同一個(gè)路徑后寫(xiě)的截?cái)嗲耙粋€(gè)。解決一任務(wù)一實(shí)例輸出路徑帶唯一標(biāo)識(shí)。// 每個(gè)任務(wù)獨(dú)立加載不要緩存 Workbook 復(fù)用 Workbook wb new Workbook(inputPath); String outName String.format(out/%s_%s_p%d.png, UUID.randomUUID(), ws.getName(), page); render.toImage(page, outName);注意new Workbook(inputPath)這個(gè)動(dòng)作本身開(kāi)銷(xiāo)不大百毫秒級(jí)別為了省這點(diǎn)開(kāi)銷(xiāo)去做實(shí)例池池化非線程安全的對(duì)象是給自己挖坑。真要優(yōu)化優(yōu)化的是線程池大小和單機(jī)并發(fā)數(shù)不是復(fù)用 Workbook。5.4 右邊界總少一列現(xiàn)象業(yè)務(wù)反饋「表格最后一列看不到」人工打開(kāi) xlsx 明明是完整的。原因三種可能按概率排——打印區(qū)域沒(méi)覆蓋到最后一列setOnlyArea(true)開(kāi)著但打印區(qū)域是模板遺留值列寬自適應(yīng)沒(méi)跑導(dǎo)致最后一列被擠出頁(yè)面。解決按 3.3 的順序處理先autoFitColumns()再用getMaxDataColumn()重設(shè)打印區(qū)域最后才渲染。改完拿一張「列數(shù)剛好卡在邊界」的測(cè)試表跑一遍別用列數(shù)很寬的表驗(yàn)證——寬表會(huì)把問(wèn)題掩蓋掉因?yàn)榭s放下最后一列總能擠進(jìn)去一點(diǎn)。5.5 水印只在服務(wù)器出現(xiàn)現(xiàn)象IDE 里跑出來(lái)干干凈凈打 jar 部署后每張圖底部都有紅字日志無(wú)異常。原因見(jiàn) 4.2授權(quán)文件用相對(duì)路徑讀、異常被吞。開(kāi)發(fā)階段 IDE 的工作目錄是項(xiàng)目根目錄license.xml就在那兒所以能讀到打 jar 之后工作目錄變了文件在 jar 內(nèi)相對(duì)路徑失效。解決改成 classpath 讀流異常不吞并且在應(yīng)用啟動(dòng)完成后打一行授權(quán)狀態(tài)日志。最省事的自檢是啟動(dòng)時(shí)導(dǎo)一張 1x1 的測(cè)試圖檢查輸出文件尺寸和內(nèi)容區(qū)是否為空白——評(píng)估水印會(huì)占掉底部一條尺寸特征很明顯。6. 從能出圖到敢上線像素級(jí)校驗(yàn)與并發(fā)壓測(cè)的兩個(gè)抓手出圖這件事最怕的不是報(bào)錯(cuò)是「不報(bào)錯(cuò)但不對(duì)」。所以我習(xí)慣在上線前加一道自動(dòng)驗(yàn)收用像素統(tǒng)計(jì)代替肉眼。6.1 用像素統(tǒng)計(jì)做自動(dòng)驗(yàn)收思路很簡(jiǎn)單把圖轉(zhuǎn)灰度統(tǒng)計(jì)接近白色245的像素占比再統(tǒng)計(jì)寬高比。全白圖的白占比接近 1.0被嚴(yán)重壓縮的圖寬高比會(huì)明顯偏離紙張比例。from PIL import Image import numpy as np def check_png(path, min_ratio0.02, max_ratio0.98): img Image.open(path).convert(L) arr np.array(img) h, w arr.shape ink_ratio float((arr 245).mean()) # 非白像素占比即「有內(nèi)容的比例」 aspect w / h problems [] if ink_ratio min_ratio: problems.append(f疑似空白圖 ink{ink_ratio:.4f}) if ink_ratio max_ratio: problems.append(f疑似花屏 ink{ink_ratio:.4f}) if not (0.6 aspect 1.8): problems.append(f寬高比異常 aspect{aspect:.2f}) return problems for p in [out/sheet1_p0.png, out/sheet1_p1.png]: print(p, check_png(p) or OK)閾值我給的是經(jīng)驗(yàn)值正常表格的非白像素占比一般在 3%-40% 之間低于 2% 基本可以判定為空白頁(yè)可能是空白頁(yè)沒(méi)過(guò)濾高于 98% 說(shuō)明整張被填滿了通常是花屏或渲染溢出。寬高比同理A4 橫向約 1.41A4 縱向約 0.71超出 0.6-1.8 這個(gè)區(qū)間就該人工看一眼。這套檢查塞進(jìn) CI 很容易準(zhǔn)備三張固定測(cè)試表普通表、寬表、空表每次構(gòu)建跑一遍導(dǎo)出加校驗(yàn)任何一項(xiàng)失敗就攔住。比人工點(diǎn)開(kāi)看可靠得多而且成本幾乎為零。6.2 線程池與內(nèi)存上限的配合并發(fā)這塊有個(gè)粗算公式單張圖內(nèi)存 ≈ 寬 × 高 × 4 字節(jié)再乘以同時(shí)在渲染的任務(wù)數(shù)就是瞬時(shí)峰值。假設(shè) 200 DPI 的 A4 橫向約 2338 × 1654 × 4 ≈ 15 MB8 并發(fā)就是 120 MB加上 Workbook 本身的內(nèi)存一般是文件體積的 5-15 倍一張 5 MB 的 xlsx 就是 25-75 MB。所以-Xmx1g跑 8 并發(fā)并不寬裕。我的經(jīng)驗(yàn)配比是-Xmx設(shè) 2g 的情況下固定線程池大小取 4 到 6單任務(wù)超時(shí)設(shè) 30 秒超時(shí)直接返回降級(jí)圖比如一張帶「預(yù)覽生成中」的靜態(tài)占位圖。線程池用固定大小而不是緩存池緩存池在流量尖峰時(shí)會(huì)瞬間拉起幾十個(gè)線程瞬間把堆打滿這類 OOM 的現(xiàn)場(chǎng)往往連堆棧都留不下來(lái)。從那以后我每次接這類截圖需求都會(huì)強(qiáng)制走一遍「授權(quán)自檢 三張測(cè)試表 像素校驗(yàn) 4 并發(fā)壓測(cè)」這四步哪怕項(xiàng)目再小也不跳。跳過(guò)哪一步后面就會(huì)在哪一步被業(yè)務(wù)找回來(lái)。這份 zip 里主要是 jar 包和兩個(gè)示例工程拿到后先按 2.2 的install:install-file裝進(jìn)本地倉(cāng)庫(kù)跑通 2.3 的 main再按 4.2 把授權(quán)加載改對(duì)基本就能接進(jìn)自己的服務(wù)里了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取