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