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