合同、发票、标书、技术文档... 这些场景你一定不陌生。作为前端开发者，PDF 预览功能几乎是每个项目都会遇到的需求。

然而，长期以来这个看似简单的需求，却让无数开发者头疼不已...

😫 那些年，我们踩过的 PDF 坑

还记得你第一次在项目中使用 PDF.js 吗？

npm install pdfjs-dist
配置 worker
处理跨域问题
解决版本兼容...

一顿操作猛如虎，最后可能还是收获一堆报错。Worker 报错、CORS 问题、打包配置复杂... 用过的人都懂，那叫一个酸爽！

传统方案的三大流派

方案	优点	致命缺点
pdf.js	功能相对完整	配置复杂、worker 头疼、打包噩梦
iframe 直接打开	简单	样式不可控、体验差
后端转图片	渲染可控	增加服务器压力、交互性差

难道就没有一个让人省心的方案吗？

---

✨ Enter EmbedPDF — 一个让 PDF 处理重获新生的开源库

最近在刷 Hacker News 时发现了一个宝藏项目——EmbedPDF，用下来的感受就一句话：

"这才是前端该有的 PDF 解决方案。"

🎯 它是什么？

EmbedPDF 是一个开源、框架无关的 Web PDF 查看器解决方案。

你可以把它理解为：

• 比 PDF.js 更现代的 PDF 渲染引擎
• 开箱即用的 PDF 查看组件
• 支持 Vue / React / Svelte / 原生 JS 的全能选手

🔥 核心优势

1. 真正的"全框架支持"

很多库号称支持多框架，实际上只是给 Vue/React 各包了一层，API 完全不同。

EmbedPDF 不一样：

// React
import { PDFViewer } from '@embedpdf/react-pdf-viewer';

// Vue
import { PDFViewer } from '@embedpdf/vue-pdf-viewer';

// Svelte
import { PDFViewer } from '@embedpdf/svelte-pdf-viewer';

// 原生 JS
import { PDFViewer } from '@embedpdf/snippet';

同样的 API，不同的框架——迁移成本几乎为零。

2. 不只是预览，而是"可编辑"

这是 EmbedPDF 和 PDF.js 的核心差异：

功能	PDF.js	EmbedPDF
PDF 预览	✅	✅
文本搜索	⚙️ 需配置	✅ 开箱即用
高亮标注	❌	✅
便签注释	❌	✅
自由文本	❌	✅
内容删除修改	❌	✅

很多业务场景里，"能看"远远不够，标注、审阅、反馈才是刚需。

3. 插件化架构，按需加载

EmbedPDF 采用插件化设计：

搜索功能 → 插件
缩放控制 → 插件
注释系统 → 插件
缩略图导航 → 插件

你需要什么就加载什么，不用像 pdf.js 那样一次性打包所有功能。包体积？当然是越小越好！

4. UI 好看，而且现代

这点虽然不是硬指标，但很现实：

• 默认主题现代简洁
• 支持亮色/暗色模式
• 虚拟化滚动，长文档不卡顿
• 操作流畅，交互体验优秀

---

📦 两种使用方式，总有一款适合你

方式一：Ready-made Viewer（开箱即用）

如果你只是想快速集成一个完整 PDF 查看器，几行代码就能搞定：

npm install @embedpdf/snippet

<!-- Vue 3 示例 -->
<template>
  <PDFViewer
    :config="{ src: 'https://example.com/document.pdf' }"
    :style="{ height: '600px' }"
    @ready="onReady"
  />
</template>

<script setup>
import { PDFViewer } from '@embedpdf/vue-pdf-viewer';

function onReady(registry) {
  console.log('PDF 渲染引擎已就绪!', registry);
}
</script>

// React 示例
import { PDFViewer } from '@embedpdf/react-pdf-viewer';

export default function App() {
  return (
    <PDFViewer
      config={{ src: 'https://example.com/document.pdf' }}
      style={{ height: '600px' }}
      onReady={(registry) => console.log('Ready!', registry)}
    />
  );
}

适合场景：中后台系统、表单附件、企业内部工具

---

方式二：Headless（无 UI，极致自定义）

如果你对 UI 和交互有强定制需求：

import { usePdfiumEngine } from '@embedpdf/engines';
import { RenderLayer, Zoom } from '@embedpdf/react-pdf-viewer';

function CustomViewer() {
  const { openDocument, renderPage } = usePdfiumEngine();
  
  return (
    <div className="custom-layout">
      {/* 搜索是插件 */}
      <SearchPlugin />
      
      {/* 缩放是插件 */}
      <Zoom controls={['in', 'out', 'fit']} />
      
      {/* 渲染层 */}
      <RenderLayer onPageRender={handlePageRender} />
      
      {/* 自定义你的 UI */}
      <MyCustomToolbar />
    </div>
  );
}

适合场景：设计体系统一的项目、复杂业务流程、深度定制场景

---

🏗️ 技术架构解析

EmbedPDF 的底层是基于 PDFium 引擎（Google Chrome 也在用哦！），通过 WebAssembly 运行：

┌─────────────────────────────────────────────────┐
│                  EmbedPDF API                    │
├─────────────────────────────────────────────────┤
│  @embedpdf/vue-pdf-viewer  │  @embedpdf/react-  │
│                             │  pdf-viewer        │
├─────────────────────────────────────────────────┤
│              @embedpdf/engines                    │
│         (High-level PDF Operations)              │
├─────────────────────────────────────────────────┤
│             @embedpdf/pdfium                      │
│         (PDFium WASM Runtime)                    │
└─────────────────────────────────────────────────┘

关键特性：

• 🔄 Web Worker 优化，主线程不被阻塞
• 📱 支持浏览器、Node.js、Serverless 环境
• 💪 完整的 TypeScript 类型支持
• 🎯 统一 API，框架无关

---

🎨 功能一览表

功能	状态	说明
📄 PDF 预览	✅	高性能渲染
🔍 文本搜索	✅	即时定位
🔎 缩放旋转	✅	多种缩放模式
✍️ 高亮注释	✅	多种标注工具
✂️ 内容编辑	✅	删除、修改文本
⚡ 虚拟滚动	✅	长文档不卡顿
🧩 插件扩展	✅	按需加载
🌍 多框架	✅	Vue/React/Svelte
🌙 暗色模式	✅	主题适配
📱 响应式	✅	移动端友好

---

🤔 如何选择？

场景	推荐方案
快速上线、内部工具	Ready-made Viewer
需要深度定制 UI	Headless Components
多技术栈团队	统一使用 EmbedPDF
有复杂 PDF 交互需求	Headless + 自定义插件

---

🚀 快速上手

# 安装核心包
npm install @embedpdf/engines @embedpdf/pdfium

# 安装框架包 (选择你的框架)
npm install @embedpdf/react-pdf-viewer  # React
npm install @embedpdf/vue-pdf-viewer    # Vue
npm install @embedpdf/svelte-pdf-viewer  # Svelte

然后参考官方文档：📚 https://www.embedpdf.com/docs

---

📝 写在最后

如果你：

• ✅ 曾经被 pdf.js 的配置折腾过
• ✅ 不想再维护一堆 worker/loader 配置
• ✅ 希望一个现代、可扩展的 PDF 方案

那么 EmbedPDF 值得你花 5 分钟尝试。

它不是"玩具项目"，从设计理念到功能实现，都明显朝着生产级解决方案在发展。插件化架构、框架无关设计、真正的编辑能力...每一个特性都直击开发痛点。

---

开源协议：MIT License
GitHub：https://github.com/embedpdf/embed-pdf-viewer
官方文档：https://www.embedpdf.com/docs

---

💡 小提示：如果你还在用 PDF.js，不妨给自己半小时时间试试 EmbedPDF。相信我，你会发现相见恨晚。

觉得有用的话，点赞 + 收藏，我们下期见！