ARTICLE · 1373275
PDF 预览别再塞 iframe 了!EmbedPDF 3.0 把查看器、无头组件和引擎一次给全
大家好,我是 01。
做后台、合同、发票、知识库的产品,几乎都躲不开 PDF 预览。
最省事的做法是丢一个 <iframe>:浏览器自带阅读器,零代码。但它的界面由浏览器决定,工具栏去不掉,样式改不了,想加个“盖章”“驳回”按钮更是无从下手。
再进一步是用 pdf.js 自己搭:渲染、分页、缩放、搜索、文字选择、批注层,一层层补下来,最后相当于在项目里养了一个 PDF 阅读器。
EmbedPDF 想省掉这段重复劳动。它是一个开源的 JavaScript PDF 查看器,GitHub 上 4.6k star,Apache-2.0 协议。2026 年 11 月初,它发布了 3.0 版本,按官方的说法,是“从 PDF 引擎开始的一次重写”。

3.0 改了什么
2.x 时代的 EmbedPDF 更像一个“能嵌进页面的 PDF 组件”。3.0 把它拆成了三层,每一层单独可用:
• 完整查看器:一个标签或一个组件,工具栏、侧边栏、搜索、批注全都带 • 无头组件:同样的插件,但不带界面,UI 由你自己写 • 独立引擎:只处理 PDF 本身,打开、读取、渲染、修改、保存
这次重构还有两个连带变化。一是包名全换了:原来的 @embedpdf/snippet、@embedpdf/react-pdf-viewer 等,统一成 @embedpdf/viewer 加各框架包。二是引擎换了实现:浏览器里跑 PDFium 的 WebAssembly 版本,放在 Web Worker 里,不卡主线程。
三种用法,按你想要的掌控程度选
三种方式共用同一套引擎和插件,所以可以先用查看器上线,后面再逐步换成无头方案,不用推倒重来。
一行标签跑起来
原生项目里,从 CDN 引入,写一个自定义标签就行:
<embedpdf-viewer
src="https://www.embedpdf.com/pdfs/welcome.pdf"
style="height: 100vh"
></embedpdf-viewer>
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@embedpdf/viewer@3/dist/embedpdf.js"
></script>标签会撑满你给的容器,所以必须有高度:固定值、100vh,或者 flex 布局里剩下的空间都行。
React、Vue、Svelte、Angular 各有对应的包,用法一致:
npm install @embedpdf/viewer-reactimport { PDFViewer } from "@embedpdf/viewer-react";
export function App() {
return<PDFViewer src="/files/contract.pdf" style={{ height: "100vh" }} />;
}对应的包名是 @embedpdf/viewer-vue、@embedpdf/viewer-svelte、@embedpdf/viewer-angular。
常用配置
EmbedPDF 3.0 的配置不写进组件属性里,而是一个普通对象:主题色、开哪些功能、自定义图标、命令、工具栏布局,全在这份数据里。
export const config = {
theme: { accent: "#7c3aed" },
features: { measurement: true, forms: false },
commands: [
{
id: "acme:send",
label: "发送签署",
run: ({ documentId }) =>
fetch(`/api/send/${documentId}`, { method: "POST" }),
},
],
layout: (layout) => layout.add("acme:send", { to: "main", section: "end" }),
};自己加的命令和内置按钮享受同等待遇:有 tooltip,工具栏放不下时会自动收进“更多”菜单,键盘也能访问。
想在代码里跟查看器对话,监听 epdf:ready 事件,然后从 viewer.get() 按名字取插件:
element.addEventListener("epdf:ready", () => {
const { viewer } = element;
viewer.documents.onOpened(() =>
viewer.get("search").search({ text: "总金额" }),
);
});无头组件
如果 PDF 只是产品界面的一部分,完整查看器的工具栏反而碍事。无头模式提供同样的能力,但不渲染任何界面。
React 里最小的组合长这样:
import { Viewer, DocumentGate } from "@embedpdf/react/runtime";
import { Stage, stagePlugin } from "@embedpdf/react/stage";
import { RenderLayer, renderPlugin } from "@embedpdf/react/render";
import { localEngine } from "@embedpdf/engine";
const engine = localEngine();
const plugins = [stagePlugin(), renderPlugin()];
export function App() {
return (
<Viewer
engine={engine}
plugins={plugins}
initialDocuments={[{ source: { kind: "url", url: "/demo.pdf" } }]}
>
<DocumentGate fallback={<p>正在打开…</p>}>
<Stage style={{ height: 600 }}>{() => <RenderLayer />}</Stage>
</DocumentGate>
</Viewer>
);
}这套结构分五部分:引擎负责读 PDF,<Viewer> 启动引擎并管理文档,插件各管一个功能,图层画在页面里,hooks 把你自己的界面接进去。
插件是按需引入的。只注册 stage 和 render,你的包里就不会出现批注、表单、搜索的代码。官方列了二十多个插件,从搜索、批注、表单、签名到页面编辑、缩略图、多文档标签页,用哪个装哪个。
独立引擎
最底层是 @embedpdf/engine。不渲染界面,只提供 PDF 能力:
import { localEngine } from "@embedpdf/engine";
const engine = localEngine();
const response = await fetch("/files/invoice.pdf");
const doc = await engine.open({
kind: "bytes",
bytes: await response.arrayBuffer(),
});
const { pages } = await doc.pages.list();
const page = doc.page(pages[0].ref);
const image = await page.render.image({
viewport: { kind: "width", width: 800 },
});
const { url } = await image.objectUrl();
const { text } = await page.text.get();
const { matches } = await doc.search.query({ text: "total" });批注也是同一套 API:拿到搜索结果的四个角坐标,直接建一个高亮;改完用 download() 拿回新的 PDF 字节。
引擎在浏览器里通过 Web Worker 跑 WebAssembly,不阻塞页面;引擎包在 Node 里也有原生构建,覆盖 macOS、Linux、Windows。服务端做批量处理、生成缩略图,可以复用同一套接口。
功能清单
官方把功能做成了“默认全开、可逐项关闭”:
• 批注:高亮、下划线、删除线、手绘、便签、文本框、图形、印章、带回复的评论 • 表单与签名:填写、创建表单字段,手写、打字或上传签名,校验签名 • 密文:标记后从文件里真正删除,而不只是盖一层 • 测量:按图纸比例算距离、周长、面积 • 页面:旋转、移动、插入、复制、删除,每一步可撤销 • 阅读:搜索、文字选择、缩略图、大纲、附件、快照、打印、下载、多文档标签页 • 多语言:希伯来语、阿拉伯语开箱支持从右到左排版
迁移和生态
从 2.x 升级,主要是换包名和配置键。官方迁移指南逐个列出了对应关系,2.x 的文档也保留在 v2.embedpdf.com,老项目可以慢慢迁。
EmbedPDF 背后的公司是 CloudPDF。开源版把 PDF 放在用户浏览器里打开;CloudPDF 则把引擎放到服务器上,PDF 不离开服务端,页面按需传到前端。两者共用同一个查看器,切换引擎只需要换个 localEngine() 为 cloudEngine()。
需要注意,CloudPDF 的 server 部分不是 Apache-2.0,而是 Fair Core License:源码可读可改,但运行需要授权。开源的是 @embedpdf/* 全家桶,这点别混淆。
注意事项
WASM 要自己托管
查看器包会带上 PDFium 的 WebAssembly 文件,构建时需要让这些资源从你自己的站点提供。用 CDN 引入最省事,走打包器就要按文档配置资源路径和工作线程。部署到有严格 CSP 的环境,也要放行 Worker 和 WASM。
包体不小
PDF 引擎不是几百 KB 的脚本。首屏就加载完整引擎,对轻量页面来说是负担。建议按需加载:先渲染页面骨架,用户真的要看 PDF 时再动态引入。
它不是“万能 PDF 阅读器”
纯前端方案有天然边界:加密 PDF、权限受限文档、超大文件,都要额外处理。真要做服务端权限、协作、水印,还是得配后端。
迭代很快
3.0 发布到 3.2 只隔了 5 天。功能推进快是好事,但生产项目建议锁死版本,升级前看一遍 changelog。
适合谁
• 后台系统:合同、发票、工单预览,要工具栏又要自己的按钮 • SaaS 产品:PDF 是产品界面的一部分,UI 必须统一 • 文档类应用:批注、表单、签名、密文一条龙 • 服务端处理:用 Node 版引擎做拆分、加水印、生成缩略图
写在最后
EmbedPDF 3.0 最大的变化不是加了什么功能,而是把“PDF 查看器”拆成了三个可组合的层次:想快就用现成组件,想控就上无头插件,只想处理文件就直接用引擎。
它替掉的是 pdf.js 之上那层又一层自己写的胶水代码。至于值不值得换,先打开在线 Demo 点两下,比看十篇介绍都直接。
官网:https://www.embedpdf.com
在线 Demo:https://www.embedpdf.com/demo
GitHub:https://github.com/embedpdf/embed-pdf-viewer















































































