本地預(yù)覽 docx、xlsx、pdf 這類需求我這兩年在后臺(tái)管理系統(tǒng)、合同平臺(tái)、報(bào)表工具里反復(fù)接到過。最有意思的一次是客戶明確提要求文件不能上傳到服務(wù)器必須全在瀏覽器里解析渲染。當(dāng)時(shí)第一反應(yīng)是這不是給自己找麻煩嗎但真做下來發(fā)現(xiàn)純前端解析這條路不僅能走通還能省掉一整套文件轉(zhuǎn)換服務(wù)。這篇就把 PDF、DOCX、XLSX 三種格式在 Vue 項(xiàng)目里的完整落地方案拆開講包含庫的選型理由、構(gòu)建工具的配合細(xì)節(jié)、性能取舍以及我實(shí)際踩過的那些坑。適合手里正卡在預(yù)覽功能上的前端同學(xué)也適合想搞清楚瀏覽器到底能解析多少 Office 格式的技術(shù)負(fù)責(zé)人。1. 為什么我最后選了純前端解析這條路接到預(yù)覽需求時(shí)多數(shù)團(tuán)隊(duì)的第一反應(yīng)是后端轉(zhuǎn) PDF 或轉(zhuǎn)圖片前端只負(fù)責(zé)顯示一張圖。這個(gè)方案聽起來省事實(shí)際做起來賬并不好算。1.1 服務(wù)端轉(zhuǎn)換方案的三筆隱性成本第一筆是服務(wù)器資源。LibreOffice 無頭模式轉(zhuǎn)一份 20 頁帶圖表的 docx在 2 核 4G 的機(jī)器上大概要 3 到 8 秒并發(fā)上來之后 CPU 直接打滿你得單獨(dú)部署一個(gè)轉(zhuǎn)換服務(wù)還要做隊(duì)列和超時(shí)控制。第二筆是保真度損耗docx 轉(zhuǎn) PDF 之后字體替換、行距偏移、表格錯(cuò)位是家常便飯用戶拿著原始文件和預(yù)覽頁面對不上投訴就來了。第三筆是隱私和合規(guī)合同、體檢報(bào)告、財(cái)務(wù)流水這類文件很多客戶在合同里就寫死了不得離開終端設(shè)備你一轉(zhuǎn)就是違規(guī)。純前端方案把這三筆賬一次性抹平文件從頭到尾留在內(nèi)存里解析耗時(shí)花在用戶自己的機(jī)器上服務(wù)器只承擔(dān)靜態(tài)資源分發(fā)。代價(jià)也很明確就是前端要引入幾個(gè)體積不小的解析庫以及要接受預(yù)覽效果和 Office 原生打開有差異這件事。提示純前端預(yù)覽的核心價(jià)值在于不上傳和即時(shí)反饋如果你的場景對像素級保真要求極高比如打印級排版校對那還是老老實(shí)實(shí)走服務(wù)端轉(zhuǎn)換不要硬扛。1.2 三種格式對應(yīng)三套完全不同的解析邏輯很多人以為預(yù)覽文件是一件事其實(shí) PDF、DOCX、XLSX 在瀏覽器里是三套獨(dú)立的玩法。PDF 是渲染型的。它本質(zhì)上是一份指令列表告訴你在這里畫一條線、在那里貼一張圖、用這個(gè)字體渲染這串字符。pdfjs-dist 做的事就是把這份指令在 Canvas 上重放一遍。它不關(guān)心內(nèi)容語義只管畫得像不像。DOCX 是結(jié)構(gòu)型的。它其實(shí)是一個(gè) zip 包里面塞了一堆 XMLword/document.xml存正文word/styles.xml存樣式word/media/存圖片。解析它等于要把 OOXML 那套復(fù)雜的樣式繼承體系翻譯成 HTML 和 CSS。這個(gè)翻譯過程注定有損耗因?yàn)?Word 的排版模型和瀏覽器的盒模型根本不是一回事。XLSX 是數(shù)據(jù)型的。它同樣是 zip但重點(diǎn)是xl/worksheets/sheet1.xml里的單元格值和xl/sharedStrings.xml里的共享字符串。你要做的是把稀疏的單元格坐標(biāo)還原成二維表格。這里最難的不是讀數(shù)據(jù)而是處理合并單元格、列寬、日期格式這些看起來是樣式、實(shí)際影響可讀性的東西。理解了這三種差異選型思路就清楚了PDF 用 pdfjs-distDOCX 用 docx-previewXLSX 用 SheetJS三套庫分工明確不要指望一個(gè)庫通吃。1.3 輸入形態(tài)統(tǒng)一成 ArrayBuffer 是省事的關(guān)鍵這三個(gè)庫對輸入的接受度不太一樣pdfjs 接受 URL、Uint8Array、ArrayBufferdocx-preview 接受 Blob、ArrayBuffer、Uint8ArraySheetJS 的read接受 array、binary、base64、buffer 等類型靠type參數(shù)區(qū)分。我最后統(tǒng)一的做法是不管外界傳進(jìn)來的是File、Blob還是ArrayBuffer都在組件入口處轉(zhuǎn)成ArrayBuffer然后按需切片。async function toArrayBuffer(input) { if (input instanceof ArrayBuffer) return input if (input instanceof Blob) return await input.arrayBuffer() throw new Error(不支持的文件輸入類型) }這么做有兩個(gè)好處。一是各個(gè)渲染分支的參數(shù)寫法統(tǒng)一了不用在每個(gè)庫里判斷類型。二是ArrayBuffer是純內(nèi)存對象沒有 URL 生命周期問題不會(huì)像URL.createObjectURL那樣忘了 revoke 就泄漏。代價(jià)是同一份數(shù)據(jù)可能被多個(gè)庫各持有一份引用超大文件要注意內(nèi)存后面第 5 節(jié)會(huì)講怎么釋放。2. PDFpdfjs-dist 在 Vue 里的正確打開方式pdfjs-dist 是三個(gè)庫里最容易出問題的一個(gè)因?yàn)樗蕾?Web Worker而 Worker 的加載方式和你的構(gòu)建工具強(qiáng)相關(guān)。我見過太多人卡在第一步就沒往前走。2.1 Worker 加載失敗是最高頻的第一道坎裝完庫直接import * as pdfjsLib from pdfjs-dist然后調(diào)getDocument控制臺(tái)大概率會(huì)甩一個(gè)Setting up fake worker failed或者 404。原因是 pdfjs 把解析邏輯放在pdf.worker.js里主線程只是調(diào)度Worker 文件必須能被瀏覽器單獨(dú)請求到。Vite 項(xiàng)目里我推薦用?url后綴讓構(gòu)建工具把文件處理成靜態(tài)資源import * as pdfjsLib from pdfjs-dist import PdfWorker from pdfjs-dist/build/pdf.worker.min.mjs?url pdfjsLib.GlobalWorkerOptions.workerSrc PdfWorkerWebpack 5 項(xiàng)目寫法不同要用new URL語法pdfjsLib.GlobalWorkerOptions.workerSrc new URL( pdfjs-dist/build/pdf.worker.min.mjs, import.meta.url ).toString()這里有個(gè)版本坑必須提醒pdfjs-dist 3.x 的 worker 文件是.js4.x 之后改成了.mjsESM 模塊。如果你從網(wǎng)上抄了一段 3.x 的代碼裝到 4.x 上路徑對不上一樣 404。另外 Vite 的預(yù)構(gòu)建有時(shí)候會(huì)把 worker 也一起打包反而搞壞路徑加一句配置更保險(xiǎn)// vite.config.js export default defineConfig({ optimizeDeps: { exclude: [pdfjs-dist] } })2.2 Canvas 渲染的三個(gè)參數(shù)決定了清晰度Worker 配好之后渲染一頁 PDF 的代碼本身很短但有幾個(gè)參數(shù)直接決定成品質(zhì)量const pdf await pdfjsLib.getDocument({ data: buffer }).promise const page await pdf.getPage(1) const viewport page.getViewport({ scale: 1.5 }) const canvas canvasRef.value const ctx canvas.getContext(2d) const dpr window.devicePixelRatio || 1 canvas.width Math.floor(viewport.width * dpr) canvas.height Math.floor(viewport.height * dpr) canvas.style.width ${Math.floor(viewport.width)}px canvas.style.height ${Math.floor(viewport.height)}px await page.render({ canvasContext: ctx, viewport, transform: dpr ! 1 ? [dpr, 0, 0, dpr, 0, 0] : null }).promisescale控制邏輯尺寸縮放功能就靠它用戶點(diǎn)放大就是scale * 1.2重新渲染。devicePixelRatio決定物理像素密度不處理的話在高分屏上文字邊緣會(huì)發(fā)虛。transform是把 DPR 縮放應(yīng)用到繪制上下文上很多人只改了canvas.width卻忘了transform結(jié)果畫布變大了但內(nèi)容還是原尺寸右下角一片空白。注意縮放后必須重新調(diào)用render不能靠 CSStransform: scale()糊弄。CSS 縮放會(huì)讓已經(jīng)柵格化的位圖被拉伸字跡立刻變糊而且文字層的位置也會(huì)跟著錯(cuò)位。2.3 多頁渲染要做懶加載而不是一次性鋪開一份 50 頁的 PDF如果一進(jìn)來就把 50 個(gè) Canvas 全渲染出來內(nèi)存占用輕松上 G頁面直接卡死。我的做法是給每一頁占一個(gè)容器容器高度按第一頁的 viewport 預(yù)估然后用IntersectionObserver監(jiān)聽只有進(jìn)入視口前后一定范圍才真正渲染。const observer new IntersectionObserver((entries) { entries.forEach((entry) { const index Number(entry.target.dataset.page) if (entry.isIntersecting) { renderPage(index) } }) }, { rootMargin: 200px 0px })rootMargin給 200px 是為了讓用戶滑動(dòng)時(shí)提前渲染避免看到白屏。同時(shí)我給已渲染的頁做了數(shù)量上限比如同時(shí)只保留 10 頁的 Canvas 內(nèi)容超出范圍的頁調(diào)用page.cleanup()并把 Canvas 寬高置零把位圖內(nèi)存還回去。這一招在移動(dòng)端特別管用不做的話 iOS Safari 很容易因?yàn)閮?nèi)存超限直接刷新頁面。2.4 文字層不是可有可無的裝飾只渲染 Canvas 的話PDF 里的文字是畫上去的用戶沒法選中、沒法搜索、沒法復(fù)制。要恢復(fù)這些能力得額外渲染一個(gè)文字層用page.getTextContent()拿到每個(gè)文本片段的內(nèi)容和變換矩陣然后生成一堆絕對定位的透明span蓋在 Canvas 上。pdfjs 4.x 提供了TextLayer類比自己手寫省事const textContent await page.getTextContent() const textLayer new pdfjsLib.TextLayer({ textContentSource: textContent, container: textLayerDiv.value, viewport }) await textLayer.render()對應(yīng)的 CSS 里文字層容器要position: absolute; inset: 0;里面的 span 用color: transparent;選中時(shí)的背景色通過::selection自定義。字體大小需要用--scale-factor這個(gè) CSS 變量來配合否則文字位置會(huì)和 Canvas 上的實(shí)際位置對不齊。這一塊調(diào)試起來比較費(fèi)勁我的經(jīng)驗(yàn)是先把 Canvas 渲染對準(zhǔn)了再弄文字層不要兩個(gè)一起調(diào)。3. DOCXdocx-preview 的樣式還原與它的脾氣DOCX 預(yù)覽的難點(diǎn)從來不是能不能顯示內(nèi)容而是顯示得像不像。我試過三條路線最后穩(wěn)定在 docx-preview 上。3.1 三條解析路線各自的適用場景第一條是mammoth.js。它走的是語義轉(zhuǎn)換路線把 Word 的Heading 1轉(zhuǎn)成h1、把Strong轉(zhuǎn)成strong輸出的 HTML 非常干凈。但它會(huì)主動(dòng)丟棄大量排版信息表格邊框、段落縮進(jìn)、頁邊距基本都沒了。如果你的需求是把文檔內(nèi)容提取出來展示在移動(dòng)端mammoth 是首選如果是讓用戶看到和 Word 里一樣的效果它不合適。第二條是docx-preview。它走的是像素級還原路線直接解析 OOXML把每個(gè)段落、每個(gè) run 的樣式都翻譯成內(nèi)聯(lián) CSS連頁眉頁腳、分頁符、腳注都能處理。代價(jià)是輸出 DOM 非常龐大一份 10 頁文檔能生成幾千個(gè)節(jié)點(diǎn)而且它對某些復(fù)雜排版比如文本框、藝術(shù)字支持有限。第三條是自研。用 JSZip 解開 docx自己解析document.xml再自己寫渲染邏輯。我試過一周之后放棄了——OOXML 的樣式繼承鏈太深styles.xml里的樣式可以被document.xml里的直接格式覆蓋還有basedOn的繼承關(guān)系工作量遠(yuǎn)超預(yù)期。除非你有非常特殊的定制需求否則不建議走這條。3.2 renderAsync 的 options 里哪幾個(gè)必須調(diào)docx-preview 的主 API 是renderAsync第四個(gè)參數(shù)是一堆開關(guān)默認(rèn)值并不適合所有場景import { renderAsync } from docx-preview await renderAsync(blob, containerRef.value, undefined, { className: docx-preview, inWrapper: true, ignoreWidth: false, ignoreHeight: true, ignoreFonts: false, breakPages: true, renderHeaders: true, renderFooters: true, renderFootnotes: true, ignoreLastRenderedPageBreak: true, useBase64URL: true, experimental: true })ignoreWidth我留成了false讓 docx-preview 按文檔里的紙張寬度設(shè)置元素寬度這樣表格和頁邊距才是對的。但副作用是內(nèi)容寬度可能超過容器需要外層包一個(gè)overflow-x: auto的滾動(dòng)容器。ignoreHeight我改成了true。因?yàn)?Word 里的分頁高度是固定的 A4 高度瀏覽器里按這個(gè)高度切頁會(huì)出現(xiàn)大片空白或者內(nèi)容被截?cái)嚓P(guān)掉之后讓內(nèi)容自然流動(dòng)更合理。renderHeaders和renderFooters看需求。如果只是給用戶快速看內(nèi)容關(guān)掉能省不少 DOM。如果是合同類文件頁眉里的合同編號、頁腳里的頁碼是有意義的那就打開。useBase64URL建議開啟。默認(rèn)情況下 docx-preview 會(huì)把圖片轉(zhuǎn)成 blob URL文檔切換頻繁時(shí)容易泄漏用 base64 雖然會(huì)讓 DOM 體積大一些但至少?zèng)]有生命周期問題。如果文檔里圖片特別多特別大那還是用 blob URL 并在組件卸載時(shí)統(tǒng)一 revoke。3.3 中文文檔跑版的兩個(gè)真實(shí)原因中文 docx 預(yù)覽最常被吐槽的是字變了、行距不對、換行位置不一樣。這基本不是庫的 bug而是兩個(gè)客觀原因。第一個(gè)是字體缺失。Word 文檔里寫的是宋體仿宋_GB2312方正小標(biāo)宋這類字體名但用戶的瀏覽器所在系統(tǒng)不一定裝了這些字體瀏覽器只能回退到默認(rèn)字體字形寬度一變換行位置全亂。我的處理方式是給預(yù)覽容器指定一個(gè)字體棧兜底.docx-preview { font-family: SimSun, Songti SC, Microsoft YaHei, sans-serif; line-height: 1.6; }同時(shí)把ignoreFonts保持false讓文檔自己的字體設(shè)置生效——裝了字體的用戶能看到原樣沒裝的用戶至少有合理回退。第二個(gè)是行距計(jì)算基準(zhǔn)不同。Word 的行距是按行這個(gè)排版單位算的瀏覽器是按line-height的倍數(shù)算的兩者對同一份w:spacing的解讀有細(xì)微差異。這個(gè)沒法完美解決只能接受。我一般會(huì)在預(yù)覽區(qū)頂部加一行小字說明預(yù)覽效果與實(shí)際排版可能存在細(xì)微差異把用戶預(yù)期先降下來。3.4 大文檔的性能處理docx-preview 是同步解析整份文檔的主線程會(huì)阻塞。一份 30 頁帶 50 張圖的文檔解析加渲染能卡住兩三秒。我做了兩件事緩解。一是渲染前先顯示骨架屏并且用setTimeout讓出一次事件循環(huán)保證 loading 狀態(tài)能先畫出來。二是用requestIdleCallback或者 Web Worker 做預(yù)解析——不過 docx-preview 內(nèi)部依賴 DOM不能直接扔進(jìn) Worker所以我的做法是把 JSZip 解壓和 XML 解析這部分提前放到 Worker 里拿到 XML 字符串之后再回主線程渲染。這個(gè)改造有點(diǎn)重只有在對大文檔體驗(yàn)要求很高時(shí)才值得做。4. XLSX把二維數(shù)據(jù)還原成表格而不是一堆字符串Excel 預(yù)覽我見過最多的錯(cuò)誤實(shí)現(xiàn)是拿sheet_to_json轉(zhuǎn)出對象數(shù)組然后v-for渲染成table。結(jié)果是日期變成一串 4 萬多的數(shù)字合并單元格全散開列寬全一樣。這里面的細(xì)節(jié)值得單獨(dú)講一節(jié)。4.1 read 和 sheet_to_json 的參數(shù)決定了數(shù)據(jù)質(zhì)量import * as XLSX from xlsx const wb XLSX.read(buffer, { type: array, cellDates: true, cellStyles: true, cellNF: true, sheetStubs: true }) const ws wb.Sheets[wb.SheetNames[0]] const rows XLSX.utils.sheet_to_json(ws, { header: 1, raw: false, defval: , blankrows: true })cellDates: true是必須的。不開這個(gè)參數(shù)日期列讀出來就是 Excel 序列號比如 45123因?yàn)?xlsx 存儲(chǔ)日期用的就是從 1900 年 1 月 1 日起的天數(shù)。開了之后 SheetJS 會(huì)按單元格的格式判斷轉(zhuǎn)成 JS Date。raw: false配合cellNF: true也很有用。它讓 SheetJS 按照單元格的數(shù)字格式輸出字符串百分比顯示成12.5%、貨幣帶上符號、保留位數(shù)也按格式來。但要注意raw: false之后數(shù)字都變字符串了如果后續(xù)要做數(shù)值排序或者統(tǒng)計(jì)得單獨(dú)再讀一份raw: true的數(shù)據(jù)。我的做法是同時(shí)保留兩份展示用格式化后的排序按原始值。header: 1表示按行輸出數(shù)組而不是對象。這在預(yù)覽場景下更通用因?yàn)楹芏啾砀竦谝恍胁皇潜眍^或者有合并的大標(biāo)題按對象輸出反而會(huì)丟數(shù)據(jù)。4.2 合并單元格必須自己算 rowspan 和 colspansheet_to_json完全不管合并單元格它只在左上角單元格返回值其余位置是空。要正確渲染得用ws[!merges]手動(dòng)處理function buildMergeMap(merges []) { const spanMap new Map() const skipSet new Set() merges.forEach((m) { const key ${m.s.r}:${m.s.c} spanMap.set(key, { rowspan: m.e.r - m.s.r 1, colspan: m.e.c - m.s.c 1 }) for (let r m.s.r; r m.e.r; r) { for (let c m.s.c; c m.e.c; c) { if (r m.s.r c m.s.c) continue skipSet.add(${r}:${c}) } } }) return { spanMap, skipSet } }渲染時(shí)遇到在skipSet里的單元格直接continue跳過遇到在spanMap里的就給td加上對應(yīng)的rowspan和colspan。這套邏輯不復(fù)雜但不寫就是會(huì)錯(cuò)。列寬用ws[!cols]行高用ws[!rows]。列寬的字段是wch字符寬度或wpx像素寬度優(yōu)先用wpx沒有的話按wch * 7 5估算成像素。行高一般用hpx取不到就統(tǒng)一給 28px。4.3 大數(shù)據(jù)量下我放棄了虛擬滾動(dòng)改用分頁一萬行的 Excel 太常見了。如果直接渲染一萬個(gè)tr瀏覽器的布局計(jì)算會(huì)直接把頁面凍住十幾秒。我一開始上的是虛擬滾動(dòng)但表格虛擬滾動(dòng)有個(gè)硬傷行高不是固定的內(nèi)容換行的行長不一樣一旦行高動(dòng)態(tài)變化虛擬滾動(dòng)的定位就全亂了。后來我換成固定行高 分頁。每頁渲染 200 行用table-layout: fixed鎖死列寬超出寬度的文本用text-overflow: ellipsis截?cái)嗍髽?biāo)懸停用原生title屬性顯示完整內(nèi)容。這個(gè)方案看起來土但實(shí)際體驗(yàn)非常好翻頁幾乎瞬間完成滾動(dòng)順滑還省掉了虛擬滾動(dòng)那一堆邊界情況處理。實(shí)測數(shù)據(jù)供參考在 2021 款 MacBook Pro 上一個(gè) 8MB 的 xlsx 文件約 6 萬行、12 列XLSX.read耗時(shí)約 2.1 秒sheet_to_json轉(zhuǎn)換約 0.4 秒渲染首屏 200 行約 60 毫秒。這兩秒多的解析時(shí)間是省不掉的所以我一定會(huì)給一個(gè)明確的進(jìn)度提示而不是轉(zhuǎn)個(gè)圈讓用戶干等。4.4 樣式還原不了那就舍掉必須坦白SheetJS 社區(qū)版的cellStyles拿不到完整的填充色、字體色、邊框這些視覺樣式。想要完整樣式得用商業(yè)版或者換 exceljs 從底層 XML 里摳——但那會(huì)讓整個(gè)解析流程復(fù)雜度翻好幾倍。我的取舍是只還原影響可讀性的結(jié)構(gòu)性樣式也就是合并單元格、列寬、行高、對齊方式、數(shù)字格式、加粗。填充色和邊框統(tǒng)一用一套干凈的表格 CSS 代替反而比原來花花綠綠的表看著舒服。提示對齊方式從ws[cell].s.alignment.horizontal取社區(qū)版能拿到一部分。如果取不到就按數(shù)據(jù)類型猜——數(shù)字右對齊、文本左對齊、布爾和錯(cuò)誤值居中這個(gè)規(guī)則和 Excel 默認(rèn)可視行為基本一致。5. 落地到 Vue 組件統(tǒng)一入口、按需加載與資源清理講完三種格式各自的實(shí)現(xiàn)真正讓代碼可控的是把它們收進(jìn)一個(gè)統(tǒng)一的 Vue 組件里。我用的是 Vue 3 的script setup但思路在 Options API 和 Vue 2 里同樣適用。5.1 一個(gè)組件管三種格式的接口設(shè)計(jì)對外只暴露最少的接口內(nèi)部自己做分派script setup import { ref, watch, onBeforeUnmount, nextTick } from vue const props defineProps({ file: { type: [File, Blob, ArrayBuffer], required: true }, fileName: { type: String, default: }, zoom: { type: Number, default: 1 } }) const emit defineEmits([loaded, error]) const wrapperRef ref(null) const loading ref(false) function detectType(name, buffer) { const ext name.split(.).pop()?.toLowerCase() if (ext pdf) return pdf if (ext docx) return docx if (ext xlsx || ext xls) return xlsx return sniffMagic(buffer) } /scriptsniffMagic是兜底用的魔數(shù)檢測主要防兩種臟情況用戶把.doc改名成.docx或者文件名被后端處理丟了擴(kuò)展名。PDF 的魔數(shù)是開頭 5 個(gè)字節(jié)%PDF-docx 和 xlsx 都是 zip開頭 4 字節(jié)都是PK\x03\x04要再深入一步——讀[Content_Types].xml里的內(nèi)容類型區(qū)分或者直接在字節(jié)流里搜word/和xl/這兩個(gè)路徑片段。后者簡單粗暴但足夠用。這里有個(gè)真實(shí)的坑input typefile拿到的File對象是只讀的但ArrayBuffer可以被讀取任意次而不消耗。所以我在組件內(nèi)部第一步就把File轉(zhuǎn)成ArrayBuffer存起來避免切換格式或者重渲染時(shí)文件已經(jīng)被讀走了。這個(gè)在 Streams API 場景下尤其重要。5.2 動(dòng)態(tài) import 把首屏體積壓下來三個(gè)庫的打包體積加起來接近 2MBpdfjs-dist 約 400KBdocx-preview 約 300KBxlsx 約 900KB。如果全塞進(jìn)首屏 bundle頁面加載會(huì)非常難看。我的做法是全部改成動(dòng)態(tài) import在真正需要渲染時(shí)才加載對應(yīng)庫async function renderPdf(buffer) { const pdfjsLib await import(pdfjs-dist) const workerUrl (await import(pdfjs-dist/build/pdf.worker.min.mjs?url)).default pdfjsLib.GlobalWorkerOptions.workerSrc workerUrl // ...渲染邏輯 }配合 Vite 的build.rollupOptions.output.manualChunks把這三個(gè)庫拆到獨(dú)立 chunk瀏覽器緩存粒度也更細(xì)——用戶第二次打開同一個(gè)頁面這些 chunk 直接命中緩存。xlsx 這個(gè)庫可以額外說一下體積優(yōu)化。npm 上的xlsx包是完整版包含讀寫能力和所有格式支持。如果你只需要讀 xlsx不需要寫、不需要讀 xls 老格式、不需要 ods可以用它的精簡構(gòu)建xlsx/dist/xlsx.mini.min.js體積能砍掉一大半。我一般會(huì)在項(xiàng)目里鎖定版本號因?yàn)檫@個(gè)包在小版本之間偶爾會(huì)有 API 行為變化。5.3 卸載時(shí)的資源清理清單預(yù)覽組件最容易出問題的場景是用戶在一個(gè)列表頁里連續(xù)點(diǎn)開十份文件。如果不清理內(nèi)存會(huì)一路漲上去。我列了一份卸載清單每次切換文件或組件銷毀時(shí)都執(zhí)行資源類型釋放方式不釋放的后果PDF 文檔對象pdf.destroy()Worker 常駐內(nèi)存多份文檔疊加PDF 頁面對象page.cleanup()頁面位圖占用不回收Canvas 位圖canvas.width 0; canvas.height 0大尺寸位圖駐留顯存Blob URLURL.revokeObjectURL(url)內(nèi)存泄漏頁面越用越卡未完成的渲染任務(wù)renderTask.cancel()切換文件時(shí)報(bào)錯(cuò)控制臺(tái)刷屏IntersectionObserverobserver.disconnect()觀察器持續(xù)持有 DOM 引用renderTask.cancel()這個(gè)特別重要。用戶在渲染一份大 PDF 的過程中切換到另一個(gè)文件原來的渲染任務(wù)還在跑新任務(wù)又開始了兩者共用一個(gè) Canvas 上下文會(huì)拋出Cannot use the same canvas during multiple render() operations這樣的錯(cuò)誤。我在每次渲染前都先檢查有沒有未完成的任務(wù)有就取消掉。5.4 移動(dòng)端的額外注意事項(xiàng)移動(dòng)端有三個(gè)和桌面端不同的地方。一是iOS 的內(nèi)存上限。Safari 對單個(gè)標(biāo)簽頁的 Canvas 內(nèi)存有硬限制超了會(huì)直接白屏刷新。所以移動(dòng)端我把同時(shí)渲染的 PDF 頁數(shù)從 10 頁壓到 3 頁圖片也做降采樣。二是手勢縮放沖突。用戶雙指縮放時(shí)瀏覽器會(huì)縮放整個(gè)頁面同時(shí)我又在做 Canvas 重繪兩者打架。解決辦法是在預(yù)覽容器上加touch-action: pan-x pan-y禁掉瀏覽器的默認(rèn)縮放自己用按鈕控制縮放比例。三是軟鍵盤和橫豎屏切換。Excel 預(yù)覽的寬表格在豎屏下必然要橫向滾動(dòng)我會(huì)在檢測到屏幕寬度小于 768px 時(shí)自動(dòng)切到一個(gè)卡片式的降級展示——每行顯示成一張小卡片字段名和值上下排列可讀性反而比橫向滾動(dòng)的表格好得多。6. 我踩過的幾個(gè)坑和對應(yīng)的排查路徑前面講了方案這一節(jié)專門講排錯(cuò)。我按現(xiàn)象 → 排查路徑 → 根因 → 修復(fù)的結(jié)構(gòu)寫方便你照著復(fù)現(xiàn)。6.1 worker 404 的三層排查法現(xiàn)象控制臺(tái)報(bào)Setting up fake worker failed: Cannot load script at ...PDF 渲染不出來。排查路徑是這樣的第一步打開 Network 面板過濾worker關(guān)鍵字看有沒有一個(gè) 404 的請求。有 404 說明路徑不對沒請求說明配置壓根沒生效。第二步如果有請求但 404看請求的 URL 長什么樣。如果是http://localhost:5173/node_modules/pdfjs-dist/...那是?url后綴沒加Vite 把它當(dāng)源碼處理了。如果是一個(gè)帶 hash 的路徑但請求不到那是構(gòu)建產(chǎn)物路徑錯(cuò)了檢查base配置。第三步如果壓根沒有請求檢查GlobalWorkerOptions.workerSrc是不是在調(diào)用getDocument之前就賦值了。這個(gè)賦值必須放在最前面晚一步都會(huì) fallback 到 fake worker。根因基本就是這三種路徑?jīng)]處理、構(gòu)建配置干擾、賦值時(shí)序不對。我把這三步寫成了一個(gè)團(tuán)隊(duì)內(nèi)的排查清單新人踩這個(gè)坑基本五分鐘能解決。6.2 打包后體積翻倍的重復(fù)打包問題現(xiàn)象本地 dev 環(huán)境正常npm run build之后產(chǎn)物里出現(xiàn)了兩份 pdfjs 代碼體積比預(yù)期大一倍。排查方式是跑npx vite-bundle-visualizer或者rollup-plugin-visualizer看 chunk 圖里有沒有重復(fù)模塊。根因通常是同時(shí)用了靜態(tài) import 和動(dòng)態(tài) import。比如某個(gè)工具文件里import * as pdfjsLib from pdfjs-dist靜態(tài)引入了組件里又await import(pdfjs-dist)動(dòng)態(tài)引入Rollup 會(huì)把兩份都留下。修復(fù)就是全局搜一遍把所有靜態(tài)引入改成動(dòng)態(tài)引入或者反過來全部靜態(tài)引入但配置manualChunks拆包。注意optimizeDeps.exclude加上之后dev 環(huán)境的依賴預(yù)構(gòu)建不處理這個(gè)包冷啟動(dòng)會(huì)慢一點(diǎn)這是正常代價(jià)。6.3 頁面越用越卡一次 blob URL 泄漏的完整定位現(xiàn)象預(yù)覽頁面打開十幾次文件之后切換文件明顯變慢打開 DevTools 的 Memory 面板做堆快照發(fā)現(xiàn)有一堆Blob對象沒被回收。定位過程先做一次 GC拍快照切換到下一個(gè)文件再拍一次對比兩次快照之間新增且未釋放的對象。找到引用鏈之后發(fā)現(xiàn)是 docx-preview 內(nèi)部為圖片生成的 blob URL組件卸載時(shí)沒人 revoke。修復(fù)方案是加一個(gè) URL 收集器const blobUrls new Set() function trackBlobUrl(blob) { const url URL.createObjectURL(blob) blobUrls.add(url) return url } function releaseAll() { blobUrls.forEach((url) URL.revokeObjectURL(url)) blobUrls.clear() } onBeforeUnmount(releaseAll)更省事的辦法是前面提到的useBase64URL: true直接不用 blob URL但代價(jià)是 DOM 體積變大。我現(xiàn)在的策略是文檔里的圖片少于 20 張就用 base64超過就走 blob URL 主動(dòng)回收。6.4 加密文件和損壞文件的優(yōu)雅降級用戶上傳一份加了密碼的 PDFgetDocument會(huì) reject如果不處理就是控制臺(tái)一片紅加白屏。pdfjs 提供了密碼回調(diào)const task pdfjsLib.getDocument({ data: buffer, onPassword: (callback, reason) { // reason 為 1 表示需要密碼為 2 表示密碼錯(cuò)誤 const pwd window.prompt(reason 1 ? 請輸入文件密碼 : 密碼錯(cuò)誤請重新輸入) if (pwd) callback(pwd) else task.destroy() } })自己做一個(gè)密碼輸入框比prompt體驗(yàn)好得多但思路一樣把密碼交給回調(diào)讓 pdfjs 自己解。損壞文件更簡單三個(gè)庫都會(huì)拋異常用 try/catch 統(tǒng)一包住給用戶一個(gè)文件無法解析請確認(rèn)文件是否完整的提示就行。我額外做了一件事把錯(cuò)誤對象打上用戶可見的標(biāo)記方便客服定位問題時(shí)能區(qū)分文件壞了和代碼崩了。這兩種情況給用戶的提示文案應(yīng)該完全不同——前者讓用戶換文件后者讓用戶刷新重試。最后分享一個(gè)我項(xiàng)目里用得最多的經(jīng)驗(yàn)。瀏覽器端解析這件事最大的風(fēng)險(xiǎn)不是技術(shù)實(shí)現(xiàn)而是用戶預(yù)期。用戶拿著 Word 打開的效果來對比你的預(yù)覽頁面任何差異都會(huì)被當(dāng)成 bug。所以我現(xiàn)在做這類功能一定會(huì)在第一版就把差異說明和下載原文件兩個(gè)入口放在顯眼位置——讓用戶隨時(shí)能回到原生程序里查看比你在前端死磕像素級還原要?jiǎng)澦愕枚唷?