簡(jiǎn)介面向Web前端開發(fā)者的PDF在線預(yù)覽實(shí)踐資料以PDF.js為核心覆蓋從庫(kù)引入、文檔加載、Canvas渲染到多頁瀏覽、縮放控制、進(jìn)度提示、文本選擇等關(guān)鍵能力并涉及Web Worker后臺(tái)解析與性能優(yōu)化思路適合有一定JavaScript基礎(chǔ)的讀者快速上手瀏覽器內(nèi)PDF查看場(chǎng)景。壓縮包共402個(gè)文件、整體約3.06MB完整示例代碼與靜態(tài)資源均整理在內(nèi)包含可直接運(yùn)行的HTML演示頁、配套JavaScript腳本、CSS樣式以及SVG/PNG/GIF界面元素和支撐PDF字體映射的bcmap、properties文件其中bcmap與properties數(shù)量較多是PDF.js正確渲染字體所必需目錄層級(jí)規(guī)整便于逐項(xiàng)查閱。已有3142人學(xué)習(xí)下載。除基礎(chǔ)用法外還能了解分塊加載、服務(wù)端預(yù)解碼等進(jìn)階方案實(shí)際開發(fā)時(shí)可借助演示頁面快速驗(yàn)證API調(diào)用順序與Canvas渲染細(xì)節(jié)并根據(jù)業(yè)務(wù)需要調(diào)整導(dǎo)航、縮放與加載策略對(duì)從零構(gòu)建或改造在線PDF預(yù)覽功能均有直接參考價(jià)值。1. 在線看 PDF用 JavaScript 把文件渲染進(jìn)網(wǎng)頁用 JavaScript 實(shí)現(xiàn)在線查看 PDF 文件聽起來是個(gè)常規(guī)需求真正做起來坑不少。瀏覽器自帶的預(yù)覽在不同內(nèi)核下表現(xiàn)差異很大——有的不支持、有的樣式完全不受控制、有的直接白屏。這個(gè)項(xiàng)目做的事情是把 PDF 渲染收攏進(jìn)一套可控的前端方案里通過開源渲染內(nèi)核把 PDF 解析成 Canvas 像素輸出支持翻頁、縮放、旋轉(zhuǎn)、全屏等交互能直接嵌入管理后臺(tái)、文檔系統(tǒng)或移動(dòng)端 H5。適合誰一類是給后臺(tái)系統(tǒng)加在線預(yù)覽 PDF功能的開發(fā)者另一類是正在調(diào)研前端 PDF 渲染方案、想看清完整實(shí)現(xiàn)鏈路的技術(shù)選型者。讀完你能搞懂項(xiàng)目怎么跑、核心鏈路長(zhǎng)什么樣還能拿到一份真實(shí)業(yè)務(wù)里趟出來的踩坑清單。2. 技術(shù)選型與項(xiàng)目結(jié)構(gòu)渲染內(nèi)核加業(yè)務(wù)殼的兩層拆法2.1 為什么不自研解析器也別用瀏覽器原生預(yù)覽PDF 格式遠(yuǎn)看是個(gè)文檔近看是一套復(fù)雜的對(duì)象系統(tǒng)交叉引用表、對(duì)象流、字體子集、圖像壓縮、內(nèi)容流指令……想從零解析再渲染工程量不低于寫一個(gè)輕量級(jí)排版引擎。商業(yè)項(xiàng)目里做這種自研基本是給自己挖坑所以我拿到這個(gè)需求的第一反應(yīng)就是找現(xiàn)成的渲染內(nèi)核把所有精力花在業(yè)務(wù)交互上。業(yè)界成熟的做法是直接用開源的 PDF 渲染內(nèi)核它的標(biāo)準(zhǔn) API 覆蓋了解析、渲染、文本提取全鏈路而且持續(xù)在維護(hù)字體兼容性這是自研很難追上的。瀏覽器原生預(yù)覽是另一個(gè)極端。它確實(shí)零成本但不同內(nèi)核的表現(xiàn)差異很大有的直接把 PDF 當(dāng)作附件下載有的雖然能在新標(biāo)簽頁打開卻完全沒有交互控制能力你既拿不到渲染進(jìn)度也改不了工具欄樣式更是完全隨緣。對(duì)產(chǎn)品而言這種黑匣子式體驗(yàn)無法接受——你沒法告訴用戶上次保存的批注存在哪也沒法統(tǒng)計(jì)多少人翻到了第幾頁。換句話說原生預(yù)覽適合內(nèi)部快速看一眼文件不適合作為產(chǎn)品的正式功能交付。這個(gè)項(xiàng)目采用了兩層拆法底層是一個(gè)開源 PDF 渲染內(nèi)核負(fù)責(zé)把 PDF 字節(jié)流解析成頁面對(duì)象再繪制到 Canvas 上上層是一個(gè)業(yè)務(wù)殼負(fù)責(zé)工具欄、翻頁、縮放、懶加載這些交互邏輯。兩層之間只通過幾個(gè)簡(jiǎn)單函數(shù)通信好處是內(nèi)核升級(jí)不影響業(yè)務(wù)代碼業(yè)務(wù)加功能也不用去碰渲染邏輯。我拆過的多個(gè)前端項(xiàng)目里這種內(nèi)核與業(yè)務(wù)解耦的組織方式是最容易維護(hù)的。我整理過一個(gè)方案對(duì)比表方便你做決定方案渲染質(zhì)量交互可控性集成成本典型問題瀏覽器原生預(yù)覽高低最低各內(nèi)核行為不統(tǒng)一樣式不可控第三方預(yù)覽服務(wù) iframe中低中存在上傳隱私風(fēng)險(xiǎn)受服務(wù)商限制開源渲染內(nèi)核 Canvas高高較高需要處理 Worker、內(nèi)存、跨域結(jié)論很直接如果你的產(chǎn)品對(duì)交互有要求或者要嵌在自家后臺(tái)里統(tǒng)一體驗(yàn)第三檔是唯一合理的選擇。選型定下來之后剩下的問題就變成了怎么把內(nèi)核的能力包裝成好用的業(yè)務(wù)功能。2.2 整體架構(gòu)Worker 線程、Canvas 渲染層、業(yè)務(wù)交互層拿我拆過的這個(gè)項(xiàng)目來說架構(gòu)可以分成三層往下看。第一層是文檔解析層。PDF 解析是大計(jì)算量活如果跑在主線程上用戶會(huì)明顯感到頁面卡頓尤其是有幾十頁、每頁都是高清掃描圖的那種文件。因此項(xiàng)目把解析工作全部放進(jìn)了 Worker 線程主線程只拿到解析好的頁面對(duì)象和元數(shù)據(jù)翻頁時(shí)再按需向 Worker 請(qǐng)求數(shù)據(jù)。這樣做的直接收益是用戶拖動(dòng)滾動(dòng)條時(shí)主線程始終是空閑的界面不會(huì)出現(xiàn)假死狀態(tài)。這個(gè)設(shè)計(jì)是整個(gè)項(xiàng)目能流暢跑大文件的前提。第二層是渲染層。每個(gè) PDF 頁面最終通過 Canvas 繪制出來。渲染層維護(hù)一個(gè)頁面對(duì)象池記錄哪些頁面已經(jīng)渲染過、哪些還在渲染中、哪些因?yàn)殡x開視口需要釋放資源。這里有個(gè)細(xì)節(jié)Canvas 的寬高是按設(shè)備像素比換算過的而不是直接用 PDF 的邏輯尺寸否則在 Retina 屏幕上會(huì)明顯模糊。這個(gè)細(xì)節(jié)做不做體驗(yàn)差距是肉眼可辨的——做過的人再看標(biāo)準(zhǔn)屏?xí)X得怎么那么糊。第三層是交互層。工具欄的縮放、旋轉(zhuǎn)、翻頁按鈕都在這層它不直接操作內(nèi)核 API而是通過一個(gè)狀態(tài)對(duì)象當(dāng)前頁碼、當(dāng)前縮放比、旋轉(zhuǎn)角度下發(fā)指令渲染層根據(jù)狀態(tài)變化決定重繪哪些頁面。三層之間是單向依賴交互層 → 渲染層 → 解析層。反向調(diào)用是被禁止的這保證了內(nèi)核替換時(shí)只需要重寫解析層和渲染層的對(duì)接部分業(yè)務(wù)殼一行都不用動(dòng)。數(shù)據(jù)流大致是這樣的用戶點(diǎn)擊下一頁 → 交互層更新狀態(tài)對(duì)象 → 渲染層讀取新頁碼向解析層要頁面對(duì)象 → 解析層從 Worker 拉取數(shù)據(jù) → 渲染層繪制 Canvas → 交互層更新頁碼顯示。整個(gè)鏈路清晰出問題的時(shí)候順著鏈路一層層查比在一個(gè)巨型文件里找要快得多。維護(hù)這份依賴關(guān)系的時(shí)候記住一個(gè)原則狀態(tài)只往下傳事件只往上拋。2.3 目錄結(jié)構(gòu)逐層拆解項(xiàng)目解壓后第一眼看到的目錄是這樣的pdf-viewer/ ├── index.html # 應(yīng)用入口頁承載畫布和工具欄 ├── package.json # 依賴聲明與腳本命令 ├── vite.config.js # 構(gòu)建配置含 dev 代理和 worker 配置 ├── public/ │ └── pdf.worker.min.js # 渲染內(nèi)核的 Worker 文件必須靜態(tài)可訪問 ├── src/ │ ├── main.js # 入口邏輯掛載應(yīng)用、讀取 PDF 地址 │ ├── viewer.js # 業(yè)務(wù)殼狀態(tài)管理與工具欄綁定 │ ├── render.js # 渲染層頁面繪制、縮放、旋轉(zhuǎn) │ ├── lazyLoad.js # 懶加載觸發(fā)與頁面對(duì)象池管理 │ ├── toolbar.js # 工具欄 UI 與事件綁定 │ └── style.css # 布局樣式 └── samples/ └── demo.pdf # 本地測(cè)試用示例文件每個(gè)文件的職責(zé)很單一。main.js 負(fù)責(zé)啟動(dòng)它只做兩件事讀取 URL 里的 file 參數(shù)調(diào)用 openPdf然后把文檔句柄交給 viewer.js。viewer.js 是全局狀態(tài)的中樞所有頁面共享的當(dāng)前頁碼、縮放比例、旋轉(zhuǎn)角度都存在這里它同時(shí)也負(fù)責(zé)把工具欄的按鈕事件翻譯成狀態(tài)變更。render.js 是整條渲染鏈路的執(zhí)行者所有 Canvas 繪制邏輯都在里面。lazyLoad.js 管性能用 IntersectionObserver 決定什么時(shí)候渲染、什么時(shí)候釋放。toolbar.js 管交互按鈕的 HTML 結(jié)構(gòu)和點(diǎn)擊綁定都在這里。你如果只想改按鈕樣式動(dòng) toolbar.js 和 style.css 就夠了想改渲染清晰度去 render.js 里找 scale 相關(guān)邏輯想支持新的操作比如批注核心是給 viewer.js 加狀態(tài)字段然后在 render.js 里加繪制分支。這種狀態(tài)驅(qū)動(dòng)渲染的設(shè)計(jì)讓每個(gè)新功能都變成加狀態(tài) 畫一筆而不是推倒重來。這也是我推薦照著這個(gè)結(jié)構(gòu)做二次開發(fā)的原因——文件少邊界清晰新手看一遍源碼就知道該改哪里。2.4 核心依賴與配置項(xiàng)目依賴非?？酥普嬲芷饋肀匦璧闹挥袃蓚€(gè)一個(gè)開源 PDF 渲染內(nèi)核庫(kù)提供 getDocument、getPage、render 等標(biāo)準(zhǔn) API一個(gè)構(gòu)建工具這里用的是 Vite。其余都是開發(fā)輔助。package.json 里核心部分大致是這樣{ name: pdf-viewer, version: 1.0.0, scripts: { dev: vite, build: vite build, preview: vite preview }, dependencies: { pdfjs-dist: latest }, devDependencies: { vite: latest } }這里說明一下package.json 里寫 latest 是為了不鎖版本實(shí)際項(xiàng)目里你應(yīng)該在 npm install 之后讓它落一個(gè)具體版本號(hào)。為什么強(qiáng)調(diào)鎖版本因?yàn)殇秩緝?nèi)核的主庫(kù)和 Worker 文件是配套發(fā)布的版本不一致會(huì)在運(yùn)行時(shí)直接報(bào)錯(cuò)而且它升級(jí)頻繁小版本之間行為可能變化不鎖版本等于把自己的線上功能交給別人的發(fā)版節(jié)奏決定。vite.config.js 里通常要做兩件事配 base 路徑部署在子目錄時(shí)需要配開發(fā)代理把 PDF 資源的請(qǐng)求轉(zhuǎn)發(fā)到測(cè)試文件服務(wù)器。生產(chǎn)環(huán)境的跨域問題則靠 Nginx 的同源部署或后端網(wǎng)關(guān)的 CORS 配置來解決。提示W(wǎng)orker 文件的處理是整個(gè)項(xiàng)目最容易翻車的點(diǎn)。把 node_modules 里對(duì)應(yīng)版本的 worker 文件復(fù)制到 public 目錄是常見做法但別忘了每次升級(jí)內(nèi)核后重新復(fù)制否則版本一 mismatch線上立刻白屏。3. 核心模塊拆解一個(gè) PDF 頁面從字節(jié)流到屏幕像素的完整鏈路3.1 文檔加載getDocument 與 Worker 線程整個(gè)項(xiàng)目的第一步是加載 PDF 文檔。渲染內(nèi)核提供的標(biāo)準(zhǔn)入口是 getDocument它接受一個(gè) URL、一個(gè) ArrayBuffer 或者一個(gè) Uint8Array。項(xiàng)目里用的是 URL 方式代碼長(zhǎng)這樣// src/main.js import * as pdfjsLib from pdfjs-dist; // 關(guān)鍵點(diǎn)Worker 路徑必須在任何 getDocument 調(diào)用之前設(shè)置 pdfjsLib.GlobalWorkerOptions.workerSrc /pdf.worker.min.js; export async function openPdf(sourceUrl) { const loadingTask pdfjsLib.getDocument({ url: sourceUrl, // 禁用自動(dòng)預(yù)取避免大文件把內(nèi)存撐爆 disableAutoFetch: true, // 控制預(yù)取頁數(shù)的分塊大小配合懶加載使用 rangeChunkSize: 65536, }); try { const pdf await loadingTask.promise; console.log(文檔加載成功共 ${pdf.numPages} 頁); return pdf; } catch (err) { console.error(PDF 加載失敗, err); throw err; } }這段代碼里有幾個(gè)值得展開說的點(diǎn)。第一workerSrc 必須是一個(gè)靜態(tài)可訪問的絕對(duì)或相對(duì)路徑瀏覽器會(huì)用這個(gè)路徑去創(chuàng)建 Worker 線程。如果路徑 404整個(gè)加載會(huì)在第一步就失敗而且報(bào)錯(cuò)信息比較抽象不熟悉的人容易在業(yè)務(wù)代碼里瞎找。第二getDocument 返回的是一個(gè) loadingTask 對(duì)象上面有 promise 屬性也有 cancel 方法用于中斷加載——如果用戶打開一個(gè)上百兆的 PDF 后立即關(guān)掉你應(yīng)該調(diào)用 cancel 而不是干等否則網(wǎng)絡(luò)連接和解析線程會(huì)一直占著資源。第三disableAutoFetch 和 rangeChunkSize 是一對(duì)組合前者讓內(nèi)核不要一口氣把整個(gè)文件拉下來后者控制在按需加載時(shí)每個(gè)范圍塊的大小。這個(gè)組合對(duì)網(wǎng)絡(luò)體驗(yàn)影響很大局域網(wǎng)內(nèi)可以調(diào)大塊大小減少請(qǐng)求次數(shù)公網(wǎng)弱網(wǎng)環(huán)境則應(yīng)該調(diào)小。參數(shù)說明參數(shù)默認(rèn)值作用什么時(shí)候該改url無PDF 地址或數(shù)據(jù)源必填disableAutoFetchfalse關(guān)閉整文件預(yù)取大文件場(chǎng)景設(shè)為 truerangeChunkSize內(nèi)核決定分塊拉取的單塊大小網(wǎng)絡(luò)差時(shí)調(diào)小局域網(wǎng)內(nèi)可調(diào)大password無加密 PDF 的密碼處理帶密碼的文檔時(shí)傳入加載完成后拿到的 pdf 對(duì)象就是整個(gè)文檔的句柄后面所有操作——取頁、取元數(shù)據(jù)、取大綱——都從它出發(fā)。這個(gè)對(duì)象本身不直接渲染任何東西只是數(shù)據(jù)入口理解這一點(diǎn)對(duì)后面排查性能問題有幫助。3.2 Canvas 頁面渲染像素級(jí)細(xì)節(jié)與清晰度控制拿到文檔句柄后下一步是把某一頁畫到 Canvas 上。這是整條鏈路里最核心的函數(shù)// src/render.js let currentScale 1.5; // 全局縮放基準(zhǔn)值1 100% export async function renderPage(pdf, pageNumber, canvas, rotation 0) { // 1. 從文檔句柄中取頁面對(duì)象 const page await pdf.getPage(pageNumber); // 2. 按縮放比和旋轉(zhuǎn)角度計(jì)算視口 const baseViewport page.getViewport({ scale: currentScale, rotation }); // 3. 考慮設(shè)備像素比讓 Canvas 物理尺寸匹配屏幕實(shí)際像素 const dpr window.devicePixelRatio || 1; const viewport { width: baseViewport.width * dpr, height: baseViewport.height * dpr, }; // 4. 設(shè)置 Canvas 尺寸并繪制 canvas.width viewport.width; canvas.height viewport.height; canvas.style.width ${baseViewport.width}px; canvas.style.height ${baseViewport.height}px; const ctx canvas.getContext(2d); ctx.setTransform(dpr, 0, 0, dpr, 0, 0); const renderTask page.render({ canvasContext: ctx, viewport: baseViewport, }); await renderTask.promise; return page; }這段代碼是整個(gè)項(xiàng)目里最容易被改壞的地方我拆開說。第一步 getPage 是異步的因?yàn)閮?nèi)核需要去 Worker 線程請(qǐng)求頁面的內(nèi)容流網(wǎng)絡(luò)慢的時(shí)候這一步可能會(huì)等一兩秒。第二步 getViewport 返回一個(gè)描述該頁面在屏幕上占多大區(qū)域的對(duì)象scale 參數(shù)直接決定渲染尺寸1 就是 100%2 就是 200%頁面變模糊還是變清晰全看它。第三步是高分屏適配的關(guān)鍵Canvas 的物理尺寸要按 devicePixelRatio 放大否則 Retina 屏上文字邊緣全是鋸齒看著像沒加載完。第四步的 setTransform 做了對(duì)應(yīng)縮放保證繪制坐標(biāo)不混亂——如果少了這一步繪制出來的內(nèi)容位置會(huì)整體偏移尤其在高分屏上會(huì)錯(cuò)位得離譜。有件事要特別提醒page.render 返回的 renderTask 可以在中途 cancel。用戶在快速翻頁時(shí)前幾頁可能還沒畫完就離開視口了此時(shí)應(yīng)該調(diào) cancel 并釋放這個(gè)頁面的資源而不是等它慢慢畫完。項(xiàng)目里對(duì)這個(gè)問題做了一個(gè)渲染任務(wù)表// src/render.js const renderTasks new Map(); // pageNumber - { task, page } export function cancelRendering(pageNumber) { const entry renderTasks.get(pageNumber); if (entry) { entry.task.cancel(); // 中斷繪制 entry.page.cleanup(); // 釋放頁面對(duì)象持有的資源 renderTasks.delete(pageNumber); } }這張表的意義在于它把正在渲染的頁面變成了可管理的集合而不是散落在各個(gè)回調(diào)里的匿名任務(wù)。排查問題的時(shí)候只要看這張表里有哪些 pageNumber就知道當(dāng)前哪些頁面還占著資源。這也是我建議所有用到 Canvas 渲染的組件都該有的基礎(chǔ)設(shè)施。3.3 翻頁與懶加載IntersectionObserver 的實(shí)戰(zhàn)用法PDF 和普通網(wǎng)頁不一樣頁面數(shù)量可能幾百頁一次性全渲染會(huì)把瀏覽器直接拖垮。項(xiàng)目里用的是近處渲染、遠(yuǎn)處釋放的策略核心實(shí)現(xiàn)基于 IntersectionObserver// src/lazyLoad.js export function setupLazyRender(container, getPdf, getCanvasFor) { const observer new IntersectionObserver((entries) { entries.forEach(async (entry) { if (entry.isIntersecting) { const pageNum Number(entry.target.dataset.pageNum); const canvas getCanvasFor(pageNum); // 只渲染還沒渲染過的頁面 if (!canvas.dataset.rendered) { await renderPage(getPdf(), pageNum, canvas); canvas.dataset.rendered true; } observer.unobserve(entry.target); // 渲染完就停止觀察 } }); }, { root: container, rootMargin: 200px 0px, // 提前 200px 預(yù)渲染減少滾動(dòng)空白等待 threshold: 0.1, }); // 把所有頁面容器都掛上觀察 const placeholders container.querySelectorAll(.pdf-page); placeholders.forEach((el) observer.observe(el)); }這套做法的核心思想是用占位換時(shí)間每個(gè) PDF 頁面在 DOM 里先放一個(gè)占位容器容器上有>// src/toolbar.js render.js 的協(xié)作邏輯 export function updateViewerState(change) { const state getViewerState(); if (change.scaleDelta) { // 支持 50% 到 300% 的縮放范圍 state.scale clamp(state.scale change.scaleDelta, 0.5, 3); } if (change.rotationDelta) { // 每次旋轉(zhuǎn) 90 度取模保證在 0/90/180/270 之間循環(huán) state.rotation (state.rotation change.rotationDelta 360) % 360; } // 重繪所有已渲染的可見頁面 const visiblePages getVisiblePageNumbers(); visiblePages.forEach(async (pageNum) { const canvas getCanvasFor(pageNum); const page await getPdf().getPage(pageNum); await renderPageWithState(page, canvas, state); }); } function clamp(value, min, max) { return Math.min(Math.max(value, min), max); }縮放這里有個(gè)體驗(yàn)細(xì)節(jié)渲染是異步的如果用戶連續(xù)點(diǎn)擊放大按鈕會(huì)觸發(fā)多次渲染前一次還沒結(jié)束后一次就來了。項(xiàng)目里用了一個(gè)渲染中計(jì)數(shù)器如果前一次還在進(jìn)行中后一次請(qǐng)求會(huì)強(qiáng)制 cancel 掉前一個(gè) renderTask保證最終效果是最后點(diǎn)擊的那次。這個(gè)永遠(yuǎn)以最后一次操作為準(zhǔn)的策略在頻繁交互場(chǎng)景下非常關(guān)鍵能避免頁面閃爍和內(nèi)存堆積。做交互開發(fā)的都知道連續(xù)點(diǎn)擊下的競(jìng)態(tài)問題是最容易翻車的點(diǎn)之一。旋轉(zhuǎn)的邏輯也不復(fù)雜每次旋轉(zhuǎn) 90 度重新計(jì)算 viewport 后 Canvas 的寬高會(huì)自動(dòng)變化。布局層需要監(jiān)聽這個(gè)變化來調(diào)整頁面容器的高度否則容器高度不變就會(huì)出現(xiàn)上下留白。項(xiàng)目里用 ResizeObserver 監(jiān)聽每個(gè) Canvas 容器的尺寸變化然后動(dòng)態(tài)設(shè)置外層元素高度這樣旋轉(zhuǎn)后頁面布局不會(huì)亂。如果你要支持連續(xù)旋轉(zhuǎn)記得用取模運(yùn)算把角度限定在 0/90/180/270 四個(gè)值里不然旋轉(zhuǎn)十幾次之后角度就累積成上千了。4. 跑起來從克隆到線上部署的完整操作4.1 環(huán)境準(zhǔn)備與依賴安裝這個(gè)項(xiàng)目跑起來的門檻不高你只需要滿足三個(gè)條件Node.js 版本別太老建議 18 及以上這是構(gòu)建工具的最低要求、一個(gè)包管理器npm、pnpm、yarn 都行、能聯(lián)網(wǎng)裝依賴。這是我通常會(huì)做的第一步檢查node -v npm -v輸出正常就直接裝依賴。在項(xiàng)目根目錄執(zhí)行npm install裝的過程如果出現(xiàn)網(wǎng)絡(luò)超時(shí)多半是 registry 的問題換成國(guó)內(nèi)鏡像再裝一次就行。等安裝完成有個(gè)容易被忽略的操作確認(rèn) Worker 文件是否已經(jīng)就位。檢查一下 public 目錄下有沒有 pdf.worker.min.js 這個(gè)文件沒有就手動(dòng)從 node_modules 里復(fù)制cp node_modules/pdfjs-dist/build/pdf.worker.min.js public/這一步?jīng)Q定你后面會(huì)不會(huì)白屏別跳過。Windows 用戶把命令換成 copy 即可效果一樣。還有個(gè)小建議裝完之后順手看一眼 node_modules/pdfjs-dist/package.json 里的版本號(hào)記住它后面排查 worker 版本不匹配時(shí)要靠這個(gè)對(duì)照。4.2 啟動(dòng)開發(fā)服務(wù)器一切就緒后執(zhí)行npm run devVite 會(huì)起一個(gè)本地開發(fā)服務(wù)器默認(rèn)端口 5173。瀏覽器打開控制臺(tái)提示的地址你會(huì)看到頁面框架和一個(gè)工具欄。如果 URL 沒帶 PDF 地址參數(shù)頁面會(huì)嘗試加載 samples/demo.pdf 作為示例文件所以第一次啟動(dòng)一定能看到內(nèi)容不用額外準(zhǔn)備。如果你手上有一個(gè)現(xiàn)成的 PDF 想測(cè)試可以通過 URL 參數(shù)指定http://localhost:5173/?file/samples/demo.pdfmain.js 里有一段邏輯會(huì)讀取 file 參數(shù)然后把它作為 getDocument 的輸入源。開發(fā)階段用這個(gè)方式換測(cè)試文件非常方便不用改代碼。如果端口被占用Vite 會(huì)自動(dòng)換一個(gè)端口并在終端提示直接用新地址即可也可以手動(dòng)指定端口npm run dev -- --port 8080。開發(fā)服務(wù)器默認(rèn)開了熱更新改工具欄按鈕的文字會(huì)即時(shí)刷新但改 render.js 里涉及 Worker 配置的部分可能需要手動(dòng)刷新一次因?yàn)?Worker 的初始化不太參與熱更新。這個(gè)區(qū)別知道就行別在熱更新不生效的時(shí)候浪費(fèi)時(shí)間反復(fù)改代碼。4.3 生產(chǎn)構(gòu)建與部署開發(fā)調(diào)試通過后構(gòu)建生產(chǎn)版本npm run build構(gòu)建產(chǎn)物會(huì)輸出到 dist 目錄。部署時(shí)有個(gè)關(guān)鍵點(diǎn)dist 里的 pdf.worker.min.js 必須和 index.html 在同一個(gè)靜態(tài)服務(wù)下且路徑匹配。如果你把應(yīng)用部署在子路徑下比如 /tools/pdf-viewer/需要同步修改 workerSrc 的路徑為相對(duì)子路徑的形式// vite.config.js 里配置 base同時(shí) workerSrc 也跟著變 pdfjsLib.GlobalWorkerOptions.workerSrc ${import.meta.env.BASE_URL}pdf.worker.min.js;這段代碼利用 Vite 注入的 BASE_URL 環(huán)境變量自動(dòng)拼接正確的資源路徑部署到任何子路徑都不用手改。Nginx 的典型配置長(zhǎng)這樣注意把 PDF 文件的請(qǐng)求和頁面請(qǐng)求指向正確的目錄server { listen 80; server_name example.com; root /var/www/pdf-viewer/dist; index index.html; location /pdf/ { proxy_pass http://pdf-file-server/; } }location /pdf/ 這段是把 PDF 文件的請(qǐng)求轉(zhuǎn)發(fā)到文件服務(wù)器同時(shí)不設(shè) CORS 限制因?yàn)闉g覽器端是跨域請(qǐng)求。如果你的 PDF 和頁面放在同一臺(tái)機(jī)器上直接把 location 指向本地文件目錄也行。部署完記得清一下瀏覽器緩存靜態(tài)資源頻繁迭代時(shí)最容易出現(xiàn)改了代碼線上還是舊的這種玄學(xué)問題。4.4 驗(yàn)證清單啟動(dòng)完成后我習(xí)慣按下面這份清單過一遍確認(rèn)核心功能都正常打開示例 PDF第一頁完整渲染文字邊緣清晰無鋸齒。點(diǎn)擊下一頁第二頁出現(xiàn)在視口中滾動(dòng)時(shí)預(yù)渲染的頁面沒有白屏。連續(xù)點(diǎn)擊放大到 200%頁面重繪無閃爍Canvas 沒有拉伸模糊。旋轉(zhuǎn) 90 度后頁面容器高度自適應(yīng)沒有巨大留白。打開一個(gè) 100 頁以上的 PDF快速滾動(dòng)整個(gè)文檔瀏覽器內(nèi)存沒有持續(xù)暴漲。無痕窗口打開同樣的 URL確認(rèn) Worker 文件加載成功Network 面板能看到 pdf.worker.min.js 返回 200。任何一項(xiàng)異常優(yōu)先去查是不是 Worker 路徑、跨域配置或者版本不匹配的問題這三者占了 80% 的故障原因。逐項(xiàng)排查的順序建議是先看 Network 請(qǐng)求是否全部 200再看控制臺(tái)有沒有報(bào)錯(cuò)關(guān)鍵字worker、CORS、version最后才去看業(yè)務(wù)代碼。注意驗(yàn)證時(shí)一定要開無痕窗口因?yàn)闉g覽器擴(kuò)展尤其是翻譯類、截圖類插件會(huì)干擾 Canvas 渲染和 Worker 通信容易誤判為項(xiàng)目 bug。這個(gè)教訓(xùn)我是在一次演示前十分鐘才深刻領(lǐng)會(huì)的。5. 避坑指南五條血淚經(jīng)驗(yàn)每一條都真實(shí)踩過5.1 白屏且控制臺(tái)報(bào) Worker 加載失敗現(xiàn)象頁面打開后一片空白控制臺(tái)提示無法加載 worker 文件或者直接報(bào) API version mismatch。原因十有八九是 workerSrc 路徑不對(duì)。我見過把 worker 文件放到 src 目錄下的也見過版本拷貝錯(cuò)的還有直接把 node_modules 里的路徑當(dāng)靜態(tài)資源引用的。這個(gè)文件必須通過靜態(tài)服務(wù)器以資源方式訪問不能走模塊導(dǎo)入——你把它當(dāng)模塊 import構(gòu)建工具也不知道該往哪放。解決檢查 public 目錄下有沒有 pdf.worker.min.js確認(rèn)它與主庫(kù)版本一致。然后打開瀏覽器 Network 面板搜 worker 文件名看實(shí)際請(qǐng)求 URL 返回 200 還是 404。返回 404 就修路徑返回 200 還報(bào)錯(cuò)就核對(duì)版本號(hào)。最快的驗(yàn)證方式是在瀏覽器地址欄直接訪問 worker 文件的 URL能顯示一坨壓縮 JS 代碼就說明路徑是對(duì)的。5.2 跨域報(bào)錯(cuò)導(dǎo)致 PDF 加載失敗現(xiàn)象本地開發(fā)一切正常部署到線上后getDocument 加載遠(yuǎn)程 PDF 時(shí)報(bào)跨域錯(cuò)誤控制臺(tái)顯示 CORS policy 相關(guān)報(bào)錯(cuò)。原因PDF 文件放在另一臺(tái)服務(wù)器比如專門的文件服務(wù)該服務(wù)器沒有返回 CORS 響應(yīng)頭。很多人以為 Worker 是后臺(tái)線程就可以繞過瀏覽器安全模型實(shí)際上 Worker 里發(fā)起的請(qǐng)求同樣受同源策略約束。解決兩個(gè)辦法。第一個(gè)是在文件服務(wù)器上配置 Access-Control-Allow-Origin: *內(nèi)網(wǎng)文件服務(wù)可以這么做公網(wǎng)要按業(yè)務(wù)收緊。第二個(gè)是讓前端先 fetch 該文件拿到 ArrayBuffer再交給 getDocument。第二種繞開了跨域限制但會(huì)多占一份內(nèi)存超大文件不推薦。項(xiàng)目里默認(rèn)用第一種配合 Nginx 配置最省事。如果兩種都不行檢查一下是不是部署時(shí)把 PDF 請(qǐng)求代理到了錯(cuò)誤的后端地址。5.3 大 PDF 頁面渲染卡頓滾動(dòng)像幻燈片現(xiàn)象打開一個(gè) 50MB、每頁都是高清圖片的 PDF快速滾動(dòng)時(shí)頁面明顯卡頓甚至瀏覽器長(zhǎng)時(shí)間無響應(yīng)。原因頁面對(duì)象和 Canvas 紋理都沒有及時(shí)釋放。只做懶加載不做事后釋放內(nèi)存會(huì)隨著滾動(dòng)位置不斷膨脹最后觸發(fā)頻繁 GC一 GC 就卡。還有可能是 disableAutoFetch 沒開內(nèi)核在后臺(tái)把整個(gè)文件都預(yù)取了一遍流量和內(nèi)存一起浪費(fèi)。解決在渲染一個(gè)新頁面之前主動(dòng)回收所有離開視口很遠(yuǎn)的頁面。項(xiàng)目里維護(hù)了一張頁面使用時(shí)間表每次渲染標(biāo)記當(dāng)前時(shí)間戳定時(shí)檢查并調(diào)用 page.cleanup() 釋放超過閾值的頁面。同時(shí)確認(rèn) disableAutoFetch 已開啟讓內(nèi)核只加載臨近范圍的數(shù)據(jù)。如果單頁尺寸特別大還可以考慮把 Canvas 的分辨率上限設(shè)一個(gè)值超過就不按 dpr 放大犧牲一點(diǎn)清晰度換流暢度。5.4 文字渲染正常但部分符號(hào)和中文變成亂碼現(xiàn)象大部分 PDF 文字渲染正常但某些字符顯示成方塊或亂碼尤其在標(biāo)題和特殊符號(hào)上。原因PDF 內(nèi)嵌字體子集不完整字體的字符映射表在解析時(shí)出了問題。這種情況常見于從某些辦公軟件導(dǎo)出的 PDF字體被裁剪得只剩部分字形。另一個(gè)可能性是渲染內(nèi)核版本太老對(duì)某些字體格式支持不全。解決先升級(jí)渲染內(nèi)核到最新版本字體支持是持續(xù)修復(fù)的版本升級(jí)能解決大多數(shù)問題。如果還不行打開系統(tǒng)原生預(yù)覽對(duì)比測(cè)試原生也亂碼說明文件本身有問題只能讓業(yè)務(wù)方換導(dǎo)出方式原生正常而項(xiàng)目里亂碼重點(diǎn)排查內(nèi)核版本和 Worker 是否匹配再檢查 PDF 里嵌入的字體子集是不是被某些壓縮工具處理過。5.5 移動(dòng)端雙指縮放無響應(yīng)頁面滾動(dòng)沖突現(xiàn)象手機(jī)上打開預(yù)覽器雙指縮放頁面時(shí)觸發(fā)的是頁面滾動(dòng)而不是 PDF 縮放內(nèi)容也沒有完整適配屏幕。原因?yàn)g覽器的觸摸默認(rèn)行為把雙指手勢(shì)當(dāng)作滾動(dòng)Canvas 上繪制的內(nèi)容無法直接接收觸摸事件。移動(dòng)端沒有 hover 狀態(tài)工具欄的可點(diǎn)擊區(qū)域也變小了交互體驗(yàn)和桌面端完全不一樣不能用同一套邏輯硬扛。解決在 Canvas 容器上監(jiān)聽 touchstart / touchmove / touchend當(dāng)檢測(cè)到兩指觸屏?xí)r調(diào)用 preventDefault 阻止默認(rèn)滾動(dòng)并把兩指距離的變化換算成縮放比例交給縮放邏輯。同時(shí)給工具欄按鈕設(shè)置至少 44px 的最小觸控尺寸旋轉(zhuǎn)和全屏按鈕放到容易夠到的拇指區(qū)域。測(cè)移動(dòng)端用真機(jī)測(cè)別信模擬器模擬器里的觸摸事件和真機(jī)差異很大很多問題只有真機(jī)才能復(fù)現(xiàn)。6. 二次開發(fā)把這個(gè)預(yù)覽器改成你自己的 PDF 工具這套預(yù)覽器最值錢的地方不是能看 PDF而是它把渲染流程完全暴露給了你所有交互都能定制。我改造時(shí)最先做的是加一個(gè)下載按鈕讓預(yù)覽和下載在同一個(gè)工具欄里完成// 新增下載當(dāng)前文檔 function downloadPdf(pdfDoc, fileName) { pdfDoc.getData().then((data) { const blob new Blob([data], { type: application/pdf }); const link document.createElement(a); link.href URL.createObjectURL(blob); link.download fileName || document.pdf; link.click(); URL.revokeObjectURL(link.href); }); }再進(jìn)一步可以給頁面加上文本選擇能力。渲染內(nèi)核里其實(shí)已經(jīng)解析出了文本內(nèi)容通過 page.getTextContent() 可以拿到每頁的文字和坐標(biāo)信息把它們浮在 Canvas 上方做一個(gè)透明的文本層就能實(shí)現(xiàn)選中復(fù)制。這是做關(guān)鍵詞高亮、批注功能的基礎(chǔ)。我一般會(huì)把這個(gè)文本層的 z-index 設(shè)為 Canvas 之上pointer-events 設(shè)為 auto這樣鼠標(biāo)選中文字時(shí)不會(huì)影響到下面的畫布。性能方面還有一個(gè)值得做的優(yōu)化對(duì)經(jīng)常打開的大文件在關(guān)閉時(shí)強(qiáng)制調(diào)用銷毀邏輯而不是依賴瀏覽器 GC。我在項(xiàng)目里給 viewer 加了一個(gè) destroy 方法統(tǒng)一清理 Worker、頁面對(duì)象、Canvas 上下文和所有觀察器。從那以后我每次接手新的前端項(xiàng)目都會(huì)先問一句這個(gè)組件有沒有對(duì)應(yīng)的銷毀流程沒有的話第一個(gè)任務(wù)就是補(bǔ)上它。這個(gè)小習(xí)慣幫我避開了不知道多少內(nèi)存泄漏的隱形坑。改完這些你的預(yù)覽器就已經(jīng)不是看 PDF 的工具而是一個(gè)可以繼續(xù)往上加批注、加簽章、加文檔對(duì)比的基座了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取