在 Vue 3 应用中显示 PDF

在 Vue 3 单页应用中嵌入 PDF 听起来很简单——直到你遇到第一个 CORS 错误,发现浏览器在 Safari 上的渲染效果不同,或者意识到你的 200 页文档正在阻塞主线程。本文介绍开发者实际使用的三种在 Vue 3 中显示 PDF 的实用方法,并诚实地分析每种方法的权衡取舍。

三种核心方法

1. 原生浏览器嵌入:<iframe> 或 <embed>

将 PDF 显示在屏幕上的最快方法是将其交给浏览器内置的 PDF 渲染器。

<template>
  <iframe
    :src="pdfUrl"
    width="100%"
    height="700px"
    style="border: none"
  />
</template>

<script setup lang="ts">
const pdfUrl = '/documents/report.pdf'
</script>

适用场景: 内部工具、管理后台,或任何 UI 一致性不重要且 PDF 来自同源的场景。

实际限制:

• 无法控制工具栏、缩放控件或主题
• 不同浏览器的行为各异——Chrome、Firefox 和 Safari 的渲染方式各不相同
• 移动浏览器通常会下载文件而不是内联显示
• 加载状态对 Vue 组件不可见,因此无法优雅地显示加载动画或处理错误

如果从不同域加载 PDF,浏览器会阻止请求,除非服务器发送正确的 Access-Control-Allow-Origin 头。在后端设置同源代理端点是最干净的解决方案。

2. PDF.js 与 Vue 3:直接集成

PDF.js 是 Mozilla 的开源 PDF 渲染引擎。从 5.x 版本系列开始,它作为 ESM 优先的包发布。你从 build/pdf.mjs 导入,并加载一个单独的 worker(pdf.worker.mjs)以将渲染工作移出主线程。

npm install pdfjs-dist

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'

pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString()

const canvasRef = ref<HTMLCanvasElement | null>(null)

onMounted(async () => {
  const pdf = await pdfjsLib.getDocument('/documents/report.pdf').promise
  const page = await pdf.getPage(1)
  const viewport = page.getViewport({ scale: 1.5 })
  const canvas = canvasRef.value!
  const ctx = canvas.getContext('2d')!
  canvas.height = viewport.height
  canvas.width = viewport.width
  await page.render({ canvasContext: ctx, viewport }).promise
})
</script>

<template>
  <canvas ref="canvasRef" />
</template>

你获得的优势: 完全控制渲染、页面导航、缩放和主题。PDF.js 支持标准注释和 AcroForm 表单字段,尽管表单和注释行为可能取决于渲染配置。

你应该知道的:

• pdfjs-dist 包会为客户端打包增加明显的负载。使用动态 import() 进行懒加载。
• 基于 XFA 的表单(在较旧的政府 PDF 中常见)支持有限,可能无法正确渲染。
• 对于大型文档,当服务器支持 HTTP 范围请求(Accept-Ranges: bytes)时,PDF.js 可以分块获取 PDF,这可以提高大文件的感知性能。
• Worker 配置是 Vite 项目中最常见的设置问题。上面显示的 new URL(..., import.meta.url) 模式可以在构建时正确解析 worker 路径。

3. Vue PDF 封装库

几个维护良好的 Vue 3 组件封装了 PDF.js,并提供更简单的组件 API。vue-pdf-embed 是一个积极维护的选项,它为你处理 worker 设置、页面渲染和响应式 prop 更新。

<script setup lang="ts">
import VuePdfEmbed from 'vue-pdf-embed'
</script>

<template>
  <VuePdfEmbed source="/documents/report.pdf" />
</template>

权衡是用更少的细粒度控制来换取显著减少的样板代码。当你需要快速获得一个可用的 Vue 3 PDF 查看器且不需要自定义渲染管道时,这些封装库是不错的选择。

注意: 一些较旧的包如 vue3-pdf-app 不再积极维护。在采用任何封装库之前,请评估其维护状态以及与 Vite 等现代打包工具的兼容性。

选择正确的方法

总结

对于大多数 Vue 3 应用,决策很简单:对于简单的同源嵌入使用 <iframe>,当你需要一个无需太多设置的可用查看器时选择维护良好的 Vue 封装库,当你需要完全控制大型文档的渲染、导航或性能时直接集成 PDF.js。无论选择哪条路径,都要正确配置 PDF.js worker 并懒加载库。仅这两个步骤就能防止开发者在 Vue 应用中嵌入 PDF 时遇到的最常见问题。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.