前端在线预览PDF/Word/Excel/PPT：从pdf.js到LibreOffice方案对比

1. 为什么“在线预览”四个字能逼疯前端：需求拆解与方案全景

我之前在做企业内部OA系统的时候，产品经理提了一个需求：“所有上传的合同、方案、报表，都要能在浏览器里直接打开预览，不能下载。” 我当时心想，这不简单吗？一个 <iframe> 不就完事了？结果真正动手才发现，“前端在线预览PPT、Excel、Word、Pdf等文件”这句话背后，藏着一整座大山。

先别急着找代码，我们得先把需求拆明白。所谓在线预览，本质上是解决一个矛盾：浏览器原生只认识 HTML、CSS、JS、图片和 PDF（严格说是浏览器的内置 PDF 插件认识），而 Office 三件套的 .docx、.xlsx、.pptx 本质上都是 ZIP 压缩包里面塞了一堆 XML 和媒体资源，浏览器不可能直接渲染。所以所有在线预览方案，本质上都是在这条链路上找突破口：

code复制原始文件 -> 某种转换或解析 -> 浏览器能渲染的格式（HTML/Canvas/图片/PDF）

基于这个链路，市面上所有方案可以归成三大类：

这三大类不是互相替代的关系，而是互补关系。PDF 可以用第一类轻松搞定，docx 用第二类效果一般但够用，pptx 用第二类基本是灾难，必须靠第三类兜底。很多人踩坑就是因为拿一个方案去套所有文件格式，最后被某个格式折磨到怀疑人生。

我个人的建议是：动手之前先花半小时把文件格式按“PDF / Word / Excel / PPT”四类拆开，分别定方案，而不是想找一个“万能预览组件”。 这个行业里不存在一个开源组件能完美渲染所有 Office 格式，谁告诉你有的，要么是商业付费服务，要么是过度包装。

还有一点很多人忽略：在线预览不只是“渲染出来”那么简单，还涉及权限控制、加载性能、跨域访问、文件安全问题。 比如你辛辛苦苦接好了预览，结果一个没注意，用户绕过预览页直接访问原文件 URL 就把文件下载走了，那产品经理的需求就白做了。所以后面每个方案我都会把安全和权限控制也讲清楚。

2. PDF预览：浏览器原生能力和pdf.js的取舍实战

2.1 零依赖方案：embed、iframe与object标签

先看最简单的 PDF 预览方案，不需要任何依赖，浏览器天然支持：

html复制<!-- 方式一：embed -->
<embed src="http://your-domain.com/contract.pdf" type="application/pdf" width="100%" height="600px" />

<!-- 方式二：iframe -->
<iframe src="http://your-domain.com/contract.pdf" style="width:100%;height:600px;border:none;"></iframe>

<!-- 方式三：object -->
<object data="http://your-domain.com/contract.pdf" type="application/pdf" width="100%" height="600px">
  <p>当前浏览器不支持PDF预览，请下载后查看</p>
</object>

这三个标签本质上都是调用浏览器内置的 PDF 查看器（Chrome 系用的是 PDFium，Firefox 用的是 pdf.js 内核）。优点是不用写任何业务代码，缺点也很多：移动端浏览器（尤其 iOS Safari）对 embed 和 object 的支持很差，甚至会直接弹出下载而不是预览；不同浏览器的工具栏长相不一样，你没法统一 UI；更关键的是，你没办法控制用户的复制、打印、翻页等行为，这在企业场景里意味着“没有权限控制”。

所以这个方案我一般只在“内部工具、临时查看、对体验没要求”的场景用。比如我们内部的一个日志导出功能，导出的 PDF 直接用 iframe 套一下，用户能看就行，不值得为它接入一套重型方案。

2.2 真正能落地的方案：pdf.js的正确接入姿势

如果对 PDF 预览有“自定义工具栏”“缩放”“翻页”“禁止下载”等需求，那答案只有一个：pdf.js。它是 Mozilla 官方维护的开源项目，用纯 JS 把 PDF 文件解析后逐页绘制到 Canvas 上，兼容性吊打所有浏览器内置方案，也是目前整个前端生态里 PDF 预览的事实标准。

接入方式有 CDN 和 npm 两种，我推荐用 npm 包管理依赖，方便版本锁定和后续升级：

bash复制npm install pdfjs-dist

然后在你的项目入口文件里配置 Worker。这一步非常关键，很多小伙伴第一次用的时候渲染报错，十有八九是 Worker 没配。pdf.js 的解析核心在一个单独的 Worker 线程里跑，如果 Worker 没加载，它就会 fallback 到主线程，要么报错要么卡死页面：

js复制import * as pdfjsLib from 'pdfjs-dist';

// 关键：配置 Worker 脚本地址
// Vite 项目用这种方式
pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.min.mjs',
  import.meta.url
).toString();

// Webpack 项目可以这样写
// pdfjsLib.GlobalWorkerOptions.workerSrc = require('pdfjs-dist/build/pdf.worker.min.js');

注意，不同版本的 pdfjs-dist 在 workerSrc 的路径上有差异，老版本（2.x）是 .js，新版本（3.x、4.x）统一是 .mjs，如果你直接复制老教程的代码，大概率会踩坑。

接下来是核心渲染逻辑，我这里直接给你一个能用的 renderPdf 函数：

js复制async function renderPdf(pdfUrl, container) {
  // 1. 加载PDF文档
  const loadingTask = pdfjsLib.getDocument(pdfUrl);
  const pdf = await loadingTask.promise;

  // 2. 循环渲染每一页
  for (let pageNum = 1; pageNum <= pdf.numPages; pageNum++) {
    const page = await pdf.getPage(pageNum);
    
    // 根据设备像素比计算合适的缩放，否则在高分屏上会模糊
    const viewport = page.getViewport({ scale: 1.5 });
    
    const canvas = document.createElement('canvas');
    canvas.width = viewport.width;
    canvas.height = viewport.height;
    canvas.style.cssText = 'display:block;margin:0 auto 16px;box-shadow:0 2px 8px rgba(0,0,0,0.15);';
    
    container.appendChild(canvas);
    
    const context = canvas.getContext('2d');
    const renderContext = {
      canvasContext: context,
      viewport: viewport,
    };
    
    await page.render(renderContext).promise;
  }

  return pdf.numPages;
}

这个函数简而言之就是：getDocument 解析文件 -> getPage 拿到每一页 -> getViewport 算出尺寸 -> render 画到 Canvas。整个过程是异步的，开发者可以自己控制进度条。

我一般还会加一个 scale 的自适应逻辑：用容器宽度除以 PDF 页面的原始宽度，得到一个能刚好铺满容器的缩放比例。固定写死 1.5 在小屏幕上会溢出，在大屏幕上又偏小。真实项目里建议这样算：

js复制const baseViewport = page.getViewport({ scale: 1 });
const scale = Math.min(container.clientWidth / baseViewport.width, 3);
const viewport = page.getViewport({ scale });

上限 3 是为了防止用户在大屏上请求超大清晰度，导致 Canvas 内存爆炸。别小看这个细节，我之前有个客户上传了一张高清的施工图 PDF，某几页的宽高特别大，如果无脑放大，浏览器直接白屏。

2.3 我踩过的PDF大坑：字体、跨域和性能

pdf.js 看着简单，实际落地全是坑，我把最有价值的三个写出来。

第一个坑：自定义字体乱码。 不少 PDF 内部嵌入了非标准字体，或者用了中文字体子集，pdf.js 默认的 cMapUrl 和 standardFontDataUrl 没有配置，渲染出来就是方框或乱码。解决方法是把 pdfjs-dist 里的 cmaps 目录和 standard_fonts 目录放到静态资源目录，然后：

js复制const loadingTask = pdfjsLib.getDocument({
  url: pdfUrl,
  cMapUrl: '/cmaps/',
  cMapPacked: true,
  standardFontDataUrl: '/standard_fonts/'
});

这个问题在 3.x 以上版本表现得很隐晦：它不是大范围乱码，而是偶尔有几个字符显示不对，排查起来特别费劲。建议项目一开始就把这两个目录配好，别等上线了再补。

第二个坑：跨域访问。 pdf.js 的 getDocument 本质上是 fetch 文件，所以同样受 CORS 限制。如果你的 PDF 文件和前端页面不在同一个域名下，后端必须返回 Access-Control-Allow-Origin: * 的响应头。但很多文件服务器的这个头没配，就会白屏报 file origin does not match viewer's。

这时候有一个绕过技巧：前端用 fetch 把 PDF 拉回来变成 Blob，再通过 URL.createObjectURL 生成临时链接传给 getDocument：

js复制const response = await fetch(pdfUrl, { headers: { Authorization: `Bearer ${token}` } });
const blob = await response.blob();
const objectUrl = URL.createObjectURL(blob);
// 注意：getDocument直接传Blob对象也是可以的
const loadingTask = pdfjsLib.getDocument(await blob.arrayBuffer());

这个方案还有个额外的好处：它能在请求头里带 Authorization token，这让 PDF 可以被“权限保护”起来——你不再需要把文件 URL 直接暴露给浏览器，而是通过一个有鉴权的接口拉数据。但代价是内存：大 PDF 直接读成 ArrayBuffer 再渲染，对内存的压力不小，200MB 的超大 PDF 会直接把页面打崩。我的建议是：正常业务文件（50MB 以内）用 Blob 方案，超过这个体量的先做文件压缩或切片，而不是硬扛。

第三个坑：懒加载与页面数量。 一个 50 页的 PDF 用上面的 for 循环一次性全渲染，用户要等很久。正确做法是只渲染可视区域的页面，可以用 IntersectionObserver 监听每个 canvas 是否进入视口，进入后再触发展开渲染。或者退一步，先渲染前 3 页给用户看，后面的加一个“点击继续加载”的按钮，这在企业场景里完全够用。

3. Word、Excel、PPT预览的三条路线：Office Viewer、前端解析库与后端转换

3.1 最快但有条件的方案：微软Office Online Viewer

如果只是想要“能预览就行”，不想写太多代码，那微软官方提供了一个免费的在线预览服务：Office Online Viewer。前端只需要拼一个 URL，然后用 iframe 包裹：

code复制https://view.officeapps.live.com/op/view.aspx?src=encodeURIComponent(文件公网URL)

举个例子，假设你的文件是 https://yourdomain.com/file/1.docx，那么预览地址就是：

js复制const fileUrl = 'https://yourdomain.com/file/1.docx';
const viewerUrl = 'https://view.officeapps.live.com/op/view.aspx?src=' + encodeURIComponent(fileUrl);

放进 iframe 里就能看到带 Office 官方工具栏的预览界面，支持 Word、Excel、PPT 三种格式，渲染效果还不错，尤其对复杂的 .docx 排版保留度很高，比任何开源前端解析库都强。

但这个方案有一个致命限制：文件 URL 必须是公网可访问的 HTTPS 地址。因为微软的服务器需要自己去你这个 URL 上把文件下载下来再渲染，如果你的文件在内网，或者在需要登录鉴权的系统里，那这个方案直接作废。另外，有些地区访问微软这个服务很不稳定，加载速度慢、白屏现象时有发生。

所以我的定性结论是：Office Online Viewer 只适合公网展示型产品，不适合企业内部系统。 如果你做的是一个面向公众的“产品说明书在线预览”功能，文件都放在 CDN 上，那用它是性价比最高的方案，一行代码都不用自己写。但如果你做的是 OA 系统、合同管理这类内部应用，趁早放弃。

3.2 纯前端解析：docx-preview、SheetJS、pptxjs的组合拳

纯前端解析的意思是：把 Office 文件拿到浏览器里，用 JS 解包，然后把内容渲染成 HTML 或 Canvas。这个方案的优点是文件不出浏览器，安全性和隐私性最好；缺点是每种格式都要单独一个库，而且解析效果参差不齐。

Word 用 docx-preview。 这个库能把 .docx 渲染成 HTML，排版还原度在开源库里算第一梯队，支持分页、分节、表格、图片，只要不是特别奇葩的 Word 文档基本都能看。用法如下：

bash复制npm install docx-preview

js复制import { renderAsync } from 'docx-preview';

const response = await fetch('http://your-domain.com/file.docx', {
  headers: { Authorization: 'Bearer ' + token }
});
const blob = await response.blob();

// container是页面上的一个div
const container = document.getElementById('previewContainer');
await renderAsync(blob, container, null, {
  className: 'docx-preview',
  inWrapper: true,
  ignoreWidth: false,
  ignoreHeight: false,
  ignoreFonts: false,
  breakPages: true,    // 按页分割，模拟Word分页效果
  ignoreLastRenderedPageBreak: true,
  experimental: false,
  useBase64URL: true,  // 图片转base64，避免加载外部资源
});

用的时候注意几个点：breakPages: true 会在每页外面套一个 .docx-wrapper，方便你按页做滚动翻页；useBase64URL: true 会把文档里的图片转成 base64 内联，避免相对路径图片加载失败。性能方面，一个 100 页的 docx，渲染耗时大概 2-4 秒，用户还能接受；但如果文档里嵌套了大量复杂表格，卡顿会明显，建议加一个 loading 状态。

Excel 用 SheetJS（也叫 xlsx）。 这个库是前端解析 Excel 的鼻祖，学名 xlsx：

bash复制npm install xlsx

js复制import * as XLSX from 'xlsx';

const response = await fetch('http://your-domain.com/file.xlsx');
const buffer = await response.arrayBuffer();
const workbook = XLSX.read(buffer, { type: 'array' });

// 默认取第一个Sheet
const firstSheet = workbook.Sheets[workbook.SheetNames[0]];
const html = XLSX.utils.sheet_to_html(firstSheet);

document.getElementById('previewContainer').innerHTML = html;

sheet_to_html 会输出一个标准的 HTML 表格，基本能满足数据查看需求。但有两个痛点得提前心理建设：第一，样式基本全丢，背景色、边框、字号统统不保留，只保留单元格里的数据；第二，公式不会自动计算，如果 Excel 里有 =SUM(A1:A10) 这种公式，用这个库读出来是公式字符串，不是计算结果，除非业务上能接受，否则很尴尬。

PPT 用 pptxjs 基本是坑。 我试过 GitHub 上最热门的几个纯前端 PPT 解析库，比如 pptxjs、js-pptx，效果都一言难尽：要么排版错乱，要么动画全丢，要么图片位置跑偏，而且这些库大多停留在“能用 demo 打开”的阶段，bug 一堆，作者已经几年不维护了。我的真实建议是：PPT 不要走纯前端解析路线，直接放弃这个选项。

3.3 一劳永逸的笨办法：后端转PDF再交给pdf.js

在碰了一鼻子灰之后，我得出了一个结论：与其在前端死磕各格式的解析器，不如在后端把 Office 文件统一转成 PDF，然后前端只需要面对 PDF 这一个格式，用上面第 2 章写的 pdf.js 方案就行。这是目前企业级系统里最稳定、最通用的方案。

后端转换工具有很多，我用得最顺手的是 LibreOffice（开源、免费、跨平台），这是转换引擎，你得在服务器上装 LibreOffice 软件，然后用命令行调用它。

bash复制# 单文件转换
soffice --headless --convert-to pdf --outdir /data/upload/preview /data/upload/file.docx

# 批量转换可以写个循环
for file in /data/upload/original/*.docx; do
  soffice --headless --convert-to pdf --outdir /data/upload/preview "$file"
done

如果后端是 Java，更优雅的方式是用 JODConverter 这个库，它封装了 LibreOffice 的调用，可以直接在代码里传文件流、拿文件流。如果后端是 Node.js，可以用 libreoffice-convert 这个 npm 包，它内部也是调 soffice 命令。

js复制// Node.js 示例
const libreConvert = require('libreoffice-convert');

const input = await fs.promises.readFile('input.pptx');
const output = await new Promise((resolve, reject) => {
  libreConvert.convert(input, '.pdf', undefined, (err, done) => {
    if (err) return reject(err);
    resolve(done);
  });
});

await fs.promises.writeFile('output.pdf', output);

这个方案有三个明显的优势。第一，渲染效果最接近 Office 原版，LibreOffice 对 docx、xlsx、pptx 的兼容性远超所有前端解析库；第二，前端逻辑统一，只需要写一遍 pdf.js 渲染逻辑，不用为每种格式维护不同代码；第三，权限控制更好做，转换后的 PDF 是服务端生成的，原始文件 URL 可以完全隐藏。

但它也有代价。最明显的是服务器成本：LibreOffice 转 PDF 非常吃 CPU，一个 20MB 的 pptx 转出来可能要占满一核 CPU 几十秒，并发量大的话必须做队列，否则服务器直接卡死。其次是中文字体问题：服务器上如果没有安装中文字体，转换出来的 PDF 全是一堆方框。Linux 服务器上至少得装好字体库：

bash复制# Debian/Ubuntu
apt-get install -y fonts-noto-cjk fonts-noto-cjk-extra fontconfig

装完字体之后，fc-cache -f 刷新一下字体缓存。

我的经验是，生产环境一定要做一个预览文件缓存目录：第一次转换成功后把 PDF 存下来，文件名用原始文件的 MD5 命名，下次请求直接读缓存，不要再转一次。这个优化能把 90% 的转换请求直接拦截掉，对服务器压力是数量级的下降。

4. 选型建议：不同业务形态的最优解与我的最终结论

4.1 内部管理系统怎么选

如果你做的是企业内部 OA、合同管理、知识库这类系统，用户量大、网络环境封闭、文件涉及保密要求高，那最优解基本是固定的：

• PDF：直接用 pdf.js，走 Blob + 鉴权接口的方案，不要用浏览器内置 iframe。
• Word / Excel：后端 LibreOffice 转 PDF 后再用 pdf.js 展示，不推荐前端解析库，因为企业文档格式往往很复杂，前端库还原度不够。
• PPT：必走后端转 PDF，前端只做展示。如果产品经理非要 PPT 带动画效果展示，那就让他去找商业组件，开源方案没有靠谱的。

这套组合拳的成本主要在服务器上，建议后端做一个独立的预览服务，部署在主服务之外，转档请求丢进消息队列异步处理。用户点预览时先走“如果缓存存在直接返回，不存在则提交转换任务，前端轮询状态”的逻辑。

4.2 公网SaaS产品怎么选

如果你的文件本来就是公开的、放在 CDN 上，那用系统自带的方案最省钱：

• PDF：pdf.js，因为要控制 UI 和交互。
• Word / Excel / PPT：可以用微软 Office Online Viewer，一行 iframe 搞定，渲染效果还特别好。但前提是你的文件 URL 必须公网 HTTPS 可访问，而且对加载速度的波动要能容忍。如果产品对首屏加载速度要求很高，那还是得走后端转 PDF 的方案，因为 Office Viewer 在境外服务器，国内访问网络链路长，体验确实一般。

4.3 混合方案与开源项目参考

如果不想自己从头造轮子，行业内也有一些现成的开源或商业方案可以参考。开源领域最知名的是 KkFileView，它是一个完整的文档预览服务，基于 OpenOffice/LibreOffice 转换，内置了 pdf.js、docx-preview 等前端渲染组件，部署一个 Spring Boot 应用就能通过 URL 参数接入预览：

code复制http://your-ip:8012/onlinePreview?url=文件地址

它的思路和我前面讲的一致：服务端把文件统一转成 PDF，然后前端加载。KkFileView 的优势是开箱即用，省去自己写转换模块的功夫；劣势是重货依赖 OpenOffice 的渲染质量，碰到复杂文档偶尔翻车，而且它默认的预览页样式偏老，前端团队往往要二次开发覆盖。

我还有一个小建议：把“预览模块”设计成可替换的。 我的做法是封装一个 PreviewEngine 接口，内部有 pdf.js 实现和 Office Online Viewer 实现，业务层只管传文件名和 URL，具体走哪条渲染路径由配置项控制。这样后期想切换方案，只需改一行配置，不用动业务代码。

最后分享一个我自己的体会：在线预览这个需求，做“能用”很容易，做“好用”很难。PDF 是里面最简单的一环，但它也是最容易让人误判难度的切入点——你以为所有文件都像 PDF 一样“给个 iframe 就够了”，结果转头被 PPT 打得满地找牙。我现在的原则很简单：能走后端转换的，绝不前端硬解析；能统一成 PDF 的，绝不直接渲染 Office 格式。 这套思路救了我很多次，也希望能给你省几天的调研时间。