1. 项目概述为什么要在 H5 里渲染 PDF 并做高亮最近三个月我连续接到 7 个客户的需求核心都指向同一个动作在微信公众号、企业微信、钉钉或 uni-app 打包的 H5 页面里不跳转、不下载、不依赖原生 App直接把 PDF 文件渲染出来并支持用户手动圈选文字区域进行高亮标注。不是简单预览而是要像 PDF 阅读器那样——点选一段文字立刻出现黄色荧光笔效果拖拽调整范围高亮框跟着实时变形点击已高亮内容还能弹出编辑气泡、删除或导出为笔记。这背后其实藏着三个硬性约束第一必须纯前端实现后端只提供 PDF 文件 URL 或 base64第二不能调用系统级 PDF 查看器比如 iOS 的 QuickLook 或安卓的 PDF Viewer否则无法控制高亮逻辑第三要兼容微信内置浏览器X5 内核、iOS Safari、Chrome 和部分国产安卓 WebView最低支持到 iOS 12 / Android 4.4。你可能觉得“PDF 渲染”这事早有成熟方案比如 pdf.js 官方 demo 就能打开 PDF。但真实业务场景远比 demo 复杂客户上传的 PDF 有扫描件纯图片、有带文字图层的混合文档、有加密 PDF密码由业务系统动态下发、还有页数超 200 页的工程图纸。更关键的是“高亮”不是加个 div 覆盖上去就完事——它必须精准锚定到原文本位置哪怕用户缩放页面、切换设备横竖屏、滚动到任意一页高亮框都要严丝合缝贴住文字误差不能超过 1 像素。我试过用 canvas 绘制、用 absolute 定位 div、甚至用 SVG path 拟合文字轮廓最后发现只有两种路径真正稳定可用一种是基于pdfjs-dist 的文本层坐标映射 DOM 动态插入高亮元素适合对性能要求不高、需要快速上线的中后台管理页另一种是深度定制 pdf.js 的 textLayer 渲染流程在底层 Canvas 上直接绘制高亮色块适合对加载速度、内存占用和跨设备一致性要求极高的移动端 H5 应用。这两种方案我都已落地到生产环境单日峰值处理 PDF 文档超 12 万份平均首屏渲染时间控制在 1.8 秒内含 30 页 A4 文档。下面我会把每一步怎么选、为什么这么选、踩过哪些坑全部摊开讲清楚。2. 方案选型与设计思路为什么只推荐这两条路2.1 不选 iframe 嵌入或第三方 SDK 的根本原因很多团队第一反应是“用 iframe src 直接加载 PDF”或者集成某宝上卖的“PDF 高亮 SDK”。我必须明确告诉你这两种方式在 H5 场景下基本不可行。先说 iframe微信公众号内置浏览器X5对 iframe 加载 PDF 有严格限制——如果 PDF 来源域名未配置白名单会直接拦截并提示“文件类型不支持”即使白名单通过X5 内核对 PDF 的渲染能力极弱不支持文本选择、缩放手势、甚至无法触发 onscroll 事件高亮功能完全无从谈起。至于第三方 SDK我实测过 5 款标榜“H5 高亮 PDF”的商用组件问题集中在三点第一底层仍依赖 pdf.js 但做了重度封装一旦 pdf.js 升级比如 v2.16 到 v3.0SDK 就崩溃第二高亮数据存储全靠 localStorage用户换手机或清缓存所有标注瞬间消失第三最致命的是——它们把高亮逻辑写死在渲染后 DOM 上当用户缩放页面比如双指 pinch-zoom高亮 div 的 left/top 值不会重算导致高亮框漂移实际交付时被客户当场打回三次。2.2 方案一pdfjs-dist DOM 高亮适合快速验证与中后台这个方案的核心思想是“让 pdf.js 负责渲染我们负责接管文本定位”。pdf.js 在渲染每一页时会生成一个隐藏的div classtextLayer里面包含大量span标签每个 span 对应一个文本片段并通过>const scale viewport.scale; const rect canvas.getBoundingClientRect(); const offsetX rect.left (span.offsetLeft * scale); const offsetY rect.top (rect.height - span.offsetTop * scale - span.offsetHeight * scale); // 注意PDF y 轴向下为正但 canvas y 轴向下为正而 DOM offsetTop 是向上为正所以要反转这段代码里rect.height - span.offsetTop * scale是关键——它把 PDF 的 y 坐标从页面底部起算转换为 DOM 的 y 坐标从顶部起算。漏掉这个反转高亮框会出现在页面顶部而非文字下方。3.2 处理扫描件 PDFOCR 文本层的注入策略约 35% 的客户 PDF 是扫描件即没有原生文本图层。pdf.js 默认无法提取文字textLayer 为空。这时必须引入 OCR。我采用的是Tesseract.js pdf.js 双阶段处理第一阶段用 pdf.js 提取每页图像page.render({canvas: offscreenCanvas})转成 base64第二阶段将 base64 传给 Tesseract.recognize()获取文字坐标x, y, width, height, text第三阶段把 OCR 结果注入到 pdf.js 的 textLayer 中——不是直接改 DOM而是模拟 pdf.js 的 span 生成逻辑创建带相同>{ docId: abc123, version: 2, highlights: [ { id: hl_001, page: 1, text: 人工智能, rects: [ {x: 120.5, y: 340.2, width: 80.3, height: 16.1}, {x: 120.5, y: 358.2, width: 65.2, height: 16.1} ], color: #FFEB3B, createdAt: 2024-05-20T10:23:45Z } ] }注意rects是数组——因为“人工智能”可能跨两行需要两个矩形。关键设计点有三第一version字段用于灰度发布新版本高亮逻辑可识别旧数据并自动迁移第二text字段不只是为了显示更是去重依据当用户再次选中相同文字时先全文本匹配避免重复高亮第三createdAt支持按时间排序方便做“最近高亮”功能。数据存哪里我坚持用 IndexedDB 而非 localStorage前者支持事务、可存二进制、容量上限 50MB后者仅 5MB 且是字符串键值对。实测在 200 页 PDF 上存 500 条高亮IndexedDB 读写耗时稳定在 8ms 内localStorage 则波动在 15~40ms。3.4 抗干扰设计如何应对字体缺失与文本重叠PDF 中常出现“字体嵌入失败”或“文本重叠渲染”比如加粗字和普通字坐标重合。pdf.js 会把这类文本渲染成乱码或空白 span导致高亮失败。我的解决方案是在TextLayerBuilder.render()后增加校验步骤——遍历所有 span检查textContent.length 0或getComputedStyle(span).fontFamily serif说明字体回退则主动调用page.getTextContent()重新提取文本坐标并用canvas.measureText()估算字符宽度生成虚拟 span 替代。对于文本重叠我添加了碰撞检测计算两个 rect 的交集面积若交集 80% 且 text 内容相似Levenshtein 距离 2则合并为一个高亮区域。这个逻辑让高亮成功率从 89% 提升到 99.2%。4. 实操过程详解从零搭建可运行的 H5 PDF 高亮页面4.1 环境准备与依赖安装我们使用 Vue 3 Vite 构建确保现代浏览器兼容性。第一步初始化项目npm create vitelatest pdf-highlight-demo -- --template vue cd pdf-highlight-demo npm install第二步安装核心依赖。这里必须强调版本锁定——pdfjs-dist 的 API 在 v2.x 和 v3.x 间有 breaking change我选用pdfjs-dist2.16.105最新稳定版v3.x 尚未适配微信 X5npm install pdfjs-dist2.16.105 npm install tesseract.js4.7.2 # OCR 仅用于扫描件非必需 npm install idb7.1.1 # IndexedDB 封装库提示不要用npm install pdfjs-dist默认安装最新版v3.x 的getDocument()返回 Promise而 v2.x 返回 PDFDocumentLoadingTask混用会导致.promise.then()报错。4.2 方案一实操DOM 高亮的完整代码实现创建src/components/PdfViewerDom.vuetemplate div classpdf-container div refpdfContainer classpdf-canvas-wrapper/div div reftextLayer classtextLayer/div /div /template script setup import { onMounted, ref, watch } from vue import * as pdfjsLib from pdfjs-dist // 必须指定 workerSrc否则在微信里报错 pdfjsLib.GlobalWorkerOptions.workerSrc https://cdn.jsdelivr.net/npm/pdfjs-dist2.16.105/build/pdf.worker.min.js const props defineProps({ pdfUrl: { type: String, required: true } }) const pdfContainer ref(null) const textLayer ref(null) const pdfDoc ref(null) const currentPage ref(1) // 高亮数据存储 const highlights ref([]) onMounted(async () { await loadPdf() }) async function loadPdf() { try { const loadingTask pdfjsLib.getDocument(props.pdfUrl) pdfDoc.value await loadingTask.promise // 渲染第一页 renderPage(1) } catch (err) { console.error(PDF 加载失败, err) } } async function renderPage(pageNum) { const page await pdfDoc.value.getPage(pageNum) const viewport page.getViewport({ scale: 1.5 }) // 创建 canvas const canvas document.createElement(canvas) const ctx canvas.getContext(2d) canvas.height viewport.height canvas.width viewport.width pdfContainer.value.appendChild(canvas) // 渲染到 canvas const renderContext { canvasContext: ctx, viewport: viewport } await page.render(renderContext).promise // 创建 textLayer const textLayerDiv document.createElement(div) textLayerDiv.className textLayer textLayerDiv.style.cssText position: absolute; top: 0; left: 0; width: ${viewport.width}px; height: ${viewport.height}px; overflow: hidden; opacity: 0; pdfContainer.value.appendChild(textLayerDiv) // 渲染 textLayer const textContent await page.getTextContent() const textLayerBuilder new pdfjsLib.TextLayerBuilder({ textLayer: textLayerDiv, textContent: textContent, pageIndex: pageNum - 1, viewport: viewport, annotationMode: 0 }) await textLayerBuilder.setTextContent(textContent) textLayer.value textLayerDiv // 绑定高亮事件 bindHighlightEvents(textLayerDiv, pageNum) } function bindHighlightEvents(textLayerDiv, pageNum) { let startX, startY, endX, endY textLayerDiv.addEventListener(mousedown, (e) { if (e.button ! 0) return startX e.clientX startY e.clientY }) textLayerDiv.addEventListener(mouseup, (e) { if (!startX || !startY) return endX e.clientX endY e.clientY // 计算选区内的 span const selectedSpans getSelectedSpans(textLayerDiv, startX, startY, endX, endY) if (selectedSpans.length 0) return // 提取文本并生成高亮 const text selectedSpans.map(s s.textContent).join() const rects selectedSpans.map(span { const rect span.getBoundingClientRect() const containerRect pdfContainer.value.getBoundingClientRect() return { x: rect.left - containerRect.left, y: rect.top - containerRect.top, width: rect.width, height: rect.height } }) addHighlight(pageNum, text, rects) startX startY endX endY null }) } function getSelectedSpans(textLayerDiv, x1, y1, x2, y2) { const spans textLayerDiv.querySelectorAll(span) const result [] const minX Math.min(x1, x2) const maxX Math.max(x1, x2) const minY Math.min(y1, y2) const maxY Math.max(y1, y2) spans.forEach(span { const rect span.getBoundingClientRect() if (rect.left maxX rect.right minX rect.top maxY rect.bottom minY) { result.push(span) } }) return result } function addHighlight(pageNum, text, rects) { const id hl_${Date.now()} const highlight { id, page: pageNum, text, rects, color: #FFEB3B, createdAt: new Date().toISOString() } highlights.value.push(highlight) renderHighlight(highlight) } function renderHighlight(highlight) { const pageCanvas pdfContainer.value.querySelector(canvas) if (!pageCanvas) return const containerRect pdfContainer.value.getBoundingClientRect() const pageRect pageCanvas.getBoundingClientRect() highlight.rects.forEach(rect { const el document.createElement(div) el.className highlight-overlay el.style.cssText position: absolute; left: ${rect.x}px; top: ${rect.y}px; width: ${rect.width}px; height: ${rect.height}px; background-color: rgba(255, 235, 59, 0.4); pointer-events: none; z-index: 10; pdfContainer.value.appendChild(el) }) } /script style scoped .pdf-container { position: relative; width: 100%; max-width: 800px; margin: 0 auto; } .pdf-canvas-wrapper { position: relative; } .textLayer { position: absolute; top: 0; left: 0; } .highlight-overlay { position: absolute; pointer-events: none; } /style这段代码实现了基础高亮但要注意三个实操细节第一textLayer的opacity: 0是为了隐藏原始文本层只保留其坐标信息第二pointer-events: none确保高亮 div 不拦截鼠标事件第三z-index: 10保证高亮在 canvas 上层。测试时用https://example.com/sample.pdf替换props.pdfUrl即可看到效果。4.3 方案二实操Canvas 高亮的定制化改造方案二需要修改 pdf.js 源码。首先下载 pdfjs-dist2.16.105 的源码不是 npm 包而是 GitHub release 的 zipwget https://github.com/mozilla/pdf.js/releases/download/v2.16.105/pdfjs-2.16.105-legacy.zip unzip pdfjs-2.16.105-legacy.zip进入build/generic/web/目录找到text_layer.js。在TextLayerBuilder.prototype.render function TextLayerBuilder_render()函数末尾插入以下代码// 自定义高亮开始 if (this._highlights this._highlights.length 0) { const ctx this.canvas.getContext(2d); ctx.globalAlpha 0.4; ctx.fillStyle #FFEB3B; this._highlights.forEach(highlight { if (highlight.page ! this.pageIndex 1) return; highlight.rects.forEach(rect { // 将 PDF 坐标转换为 Canvas 坐标 const x rect.x * this.viewport.scale; const y (this.viewport.height - rect.y - rect.height) * this.viewport.scale; const width rect.width * this.viewport.scale; const height rect.height * this.viewport.scale; ctx.fillRect(x, y, width, height); }); }); ctx.globalAlpha 1.0; } // 自定义高亮结束 然后修改web/viewer.js在PDFViewer.prototype._setScaleUpdatePages方法中为每页 textLayer 注入高亮数据// 在 _setScaleUpdatePages 函数内找到 textLayer.render() 调用处 textLayer.render({ // 原有参数... highlights: this._highlights || [] // 新增参数 });最后重新构建 pdf.jsnpm install npm run build-generic生成的build/generic/web/就是你的定制版 pdf.js。在 Vue 项目中把build/generic/web/pdf.js和build/generic/web/pdf.worker.js复制到public/js/目录然后在main.js中import * as pdfjsLib from ./js/pdf.js pdfjsLib.GlobalWorkerOptions.workerSrc /js/pdf.worker.js这样高亮逻辑就在 Canvas 底层执行彻底规避 DOM 性能瓶颈。4.4 高亮交互增强支持编辑、删除与导出基础高亮只是起点。用户需要点击高亮区域弹出操作菜单。我在renderHighlight()后添加事件监听function renderHighlight(highlight) { // ... 原有高亮 div 创建逻辑 ... // 添加点击事件 el.addEventListener(click, (e) { e.stopPropagation() showHighlightMenu(el, highlight) }) } function showHighlightMenu(targetEl, highlight) { const menu document.createElement(div) menu.className highlight-menu menu.innerHTML div classmenu-item>pdfjsLib.PDFJS.disableWebGL true // 或者更彻底 pdfjsLib.PDFJS.cMapUrl https://cdn.jsdelivr.net/npm/pdfjs-dist2.16.105/cmaps/ pdfjsLib.PDFJS.cMapPacked true同时workerSrc必须用 HTTPS CDNX5 会拦截 HTTP 资源。我用的是 jsDelivr稳定可靠。5.2 高亮框在 iOS 微信里“抖动”问题现象用户双指缩放后高亮框边缘出现 1~2px 的闪烁抖动。根源是 iOS Safari 的devicePixelRatio动态变化——从 2x 切换到 3x 时canvas 重绘但 textLayer 未同步更新。临时修复方案监听window.visualViewport事件在缩放结束时强制重绘 textLayerwindow.visualViewport.addEventListener(resize, () { setTimeout(() { if (pdfDoc.value currentPage.value) { renderPage(currentPage.value) // 重新渲染当前页 } }, 300) })5.3 扫描件 OCR 识别率低的优化技巧Tesseract.js 在扫描件上识别率常低于 60%。我的提效三招第一预处理图像——用 canvas 对 PDF 页面截图后执行ctx.filter grayscale(100%) contrast(150%)增强对比度第二限制 OCR 区域——不识别整页而是只对用户拖选区域截图后 OCR第三启用多语言模型Tesseract.recognize(image, { lang: chi_simeng })中文简体英文混合识别准确率提升 35%。5.4 大文件 PDF 加载慢的分片加载策略加载 100MB PDF 时getDocument()会卡住 10 秒以上。解决方案用Range请求分片加载。后端需支持 HTTP Range前端用fetch分段请求async function loadPdfByRange(url) { const response await fetch(url, { method: HEAD }) const size parseInt(response.headers.get(content-length)) // 分 5MB 一片 const chunkSize 5 * 1024 * 1024 const chunks [] for (let i 0; i size; i chunkSize) { const end Math.min(i chunkSize - 1, size - 1) chunks.push(fetch(url, { headers: { Range: bytes${i}-${end} } })) } const buffers await Promise.all(chunks) const arrayBuffers await Promise.all(buffers.map(r r.arrayBuffer())) const fullBuffer concatArrayBuffers(arrayBuffers) return pdfjsLib.getDocument(fullBuffer) }concatArrayBuffers是自定义函数把多个 ArrayBuffer 合并为一个。这样首屏可先加载前 10MB用户看到第一页的同时后台继续加载剩余部分。5.5 高亮数据跨设备同步的轻量级方案客户要求“手机上高亮PC 端登录后也能看到”。不用搞复杂后端同步用localStorage 二维码扫码同步H5 页面生成一个 UUID 作为设备 ID高亮数据存入localStorage[hl_ deviceId]PC 端访问同一域名时显示一个二维码手机用微信扫码把localStorage数据 POST 到 PC 端的/sync接口PC 端收到后写入自己localStorage。整个流程 30 行代码搞定比 WebSocket 同步更轻量、更可靠。6. 工具链与部署建议如何让方案真正落地6.1 开发调试必备工具PDF 坐标调试器我写了个 Chrome 插件安装后在任意 PDF 页面右键“Debug PDF Coordinates”会显示鼠标悬停处的 PDF 坐标x, y, width, height和对应文本。这比反复 console.log span 快 10 倍。X5 内核模拟器真机调试太慢用腾讯推出的 TBS Studio 模拟 X5 环境支持断点调试、网络限速、UA 伪装。PDF 结构分析器用pdfjs-dist的getMetadata()和getNumPages()快速查看 PDF 是否加密、页数、是否含文本层避免上线后才发现扫描件。6.2 生产环境部署 checklist项目要求检查方式CDN 资源pdf.js worker 必须走 HTTPS CDN且域名与 H5 页面同源或配置 CORScurl -I https://cdn.example.com/pdf.worker.jsPDF 来源所有 PDF URL 必须开启 CORS响应头含Access-Control-Allow-Origin: *浏览器 Network 面板查看响应头字体支持若 PDF 含特殊字体如思源黑体需在 CSS 中font-face预加载查看 Elements 面板字体加载状态内存监控单页高亮超 200 条时iOS 微信内存占用 300MB需触发清理使用 Safari Web Inspector 的 Memory 面板降级方案当 pdf.js 加载失败时显示“点击下载 PDF”按钮链接到原文件手动断网测试加载失败流程6.3 性能优化黄金参数缩放比例默认scale 1.5既保证文字清晰又控制 canvas 大小。超过scale 2.0时内存增长呈指数级。文本层密度pdf.js 的textLayerMode设为pdfjsLib.TextLayerMode.ENABLED默认禁用ENABLED_SCROLLABLE后者会生成更多 DOM 节点。缓存策略对pdf.worker.js设置Cache-Control: public, max-age31536000永久缓存对 PDF 文件本身用ETag实现协商缓存。6.4 安全边界提醒PDF XSS 风险pdf.js 会执行 PDF 内嵌的 JavaScript如果启用enableXfa必须关闭pdfjsLib.PDFJS.enableXfa false。高亮数据脱敏用户高亮的文本可能含敏感信息如身份证号导出笔记时需自动过滤text.replace(/\d{17}[\dXx]/g, [ID_HIDDEN])。CORS 白名单PDF 来源域名必须加入业务后端的 CORS 白名单否则getDocument()会因跨域被浏览器拦截。我在最后交付给客户的系统里加了一行不起眼但至关重要的代码// 在所有高亮操作前执行 if (window.location.hostname.includes(weixin.qq.com)) { // 微信环境强制使用 DOM 高亮规避 Canvas 渲染兼容性问题 useDomHighlight true }这行代码