简介：这份资源面向需要在Web项目中集成文件在线预览能力的开发者，尤其适合前端入门到中级水平、希望不依赖后端即可快速验证效果的人群。它围绕浏览器原生能力与JavaScript脚本，解决PDF、Excel、PPT、DOC、JPG、PNG等常见格式在页面内直接查看的问题，免去用户下载后再打开的繁琐流程。压缩包共6个文件，约238KB，包含HTML示例页、jQuery及媒体预览脚本、说明文档，以及用于测试的图片与文档样本，结构轻量、便于直接运行和二次改造。已有27287人学习下载，说明其在实际开发场景中具有较高参考价值。读者可从中获得一套可运行的预览示例、第三方库的引入方式，以及Office文档借助在线转换服务展示的思路，并据此理解不同格式的适配差异与降级提示写法，为搭建用户友好的文件预览模块提供可复用的起点。

1. 纯前端文件预览：不装插件、不传后端，浏览器里把 PDF 和 Office 文档打开

上周有个做内部管理系统的朋友找我，说他们上传附件后只能给个下载链接，用户点开还得本地装 Office，体验很差。他问我能不能纯前端搞定预览，最好连文件都不出浏览器。我第一反应是：PDF 和图片好办，Office 三件套才是真正的坑。这份 HTML+JS 的在线预览方案就是冲着这个场景来的——用浏览器原生能力和成熟的前端库组合，把 pdf、excel、ppt、doc、jpg、png 这几类最常见的附件格式在页面里直接渲染出来，不依赖后端转码服务，也不需要用户装任何插件。适合正在做 OA、工单、合同管理这类带附件模块的开发者，尤其是前端想自己扛下预览这块、不想为格式转换再搭一套服务的情况。下面我按「能干什么 → 怎么跑 → 怎么改」的顺序把它拆开讲。

2. 技术选型与目录结构：三类格式三条渲染路径

2.1 为什么不是一个库打天下

拿到这个需求，很多人第一反应是找一个「万能预览库」。实际拆下来会发现，这几类格式的渲染原理完全不同，硬塞进一个库反而处处受限。我的判断是按格式分三条路径走，各用各的最优解：

这个分法不是拍脑袋。PDF 是固定版式文档，pdf.js 能把每一页解析成 Canvas 位图，保真度高；图片本身就是浏览器原生支持的，没必要引入任何库；而 Office 文档是流式排版，前端解析要么转成 HTML 近似还原，要么借助在线文档服务的嵌入能力。三条路径的复杂度、失败率、还原度都不一样，分开处理才能各自优化。

2.2 目录结构长什么样

这类纯前端预览项目，结构一般不会太复杂，核心是把「格式判断」和「渲染器」解耦。我按这个思路整理出来的目录大致是这样：

file-preview/ ├── index.html # 入口页面，含文件选择与预览容器 ├── css/ │ └── preview.css # 预览容器、工具栏、分页样式 ├── js/ │ ├── main.js # 入口：绑定事件、调度渲染器 │ ├── detector.js # 根据扩展名/MIME 判断文件类型 │ ├── renderers/ │ │ ├── pdf-renderer.js # pdf.js 封装 │ │ ├── image-renderer.js │ │ └── office-renderer.js │ └── utils.js # 文件读取、错误提示等公共方法 └── lib/ ├── pdf.min.js # pdf.js 主库 └── pdf.worker.min.js # pdf.js 的 worker，必须同目录

关键设计点在于renderers目录：每个渲染器对外暴露统一的render(container, file)接口，main.js只负责判断类型然后调对应的渲染器。这样后面加新格式（比如 svg、txt）只需要新增一个文件，不用动主流程。lib目录单独放第三方库，方便升级和替换。

2.3 类型判断的两种依据

判断文件类型不能只看扩展名，用户改个后缀就能骗过去。稳妥的做法是扩展名和 MIME 双保险：

// detector.js const EXT_MAP = { pdf: 'pdf', jpg: 'image', jpeg: 'image', png: 'image', doc: 'word', docx: 'word', xls: 'excel', xlsx: 'excel', ppt: 'ppt', pptx: 'ppt' }; export function detectType(file) { // 优先用扩展名，兜底用 MIME const ext = file.name.split('.').pop().toLowerCase(); if (EXT_MAP[ext]) return EXT_MAP[ext]; const mime = file.type || ''; if (mime === 'application/pdf') return 'pdf'; if (mime.startsWith('image/')) return 'image'; if (mime.includes('word')) return 'word'; if (mime.includes('sheet') || mime.includes('excel')) return 'excel'; if (mime.includes('presentation') || mime.includes('powerpoint')) return 'ppt'; return 'unknown'; }

EXT_MAP把常见扩展名映射到渲染器类型，detectType先查扩展名，查不到再用file.type兜底。注意file.type在部分系统上可能是空字符串，所以扩展名判断要放在前面。返回unknown时主流程会给出「暂不支持该格式」的提示，而不是白屏。

3. 核心渲染链路：从选文件到画上屏幕

3.1 入口调度：一个 switch 串起所有格式

main.js是整个预览的调度中心。用户选文件后触发change事件，拿到File对象，判断类型，清空容器，调对应渲染器。这段逻辑不复杂，但顺序和异常处理要写对：

// main.js import { detectType } from './detector.js'; import { renderPdf } from './renderers/pdf-renderer.js'; import { renderImage } from './renderers/image-renderer.js'; import { renderOffice } from './renderers/office-renderer.js'; const container = document.getElementById('preview-container'); const fileInput = document.getElementById('file-input'); fileInput.addEventListener('change', async (e) => { const file = e.target.files[0]; if (!file) return; container.innerHTML = ''; // 清空上一次的预览 const type = detectType(file); try { switch (type) { case 'pdf': await renderPdf(container, file); break; case 'image': await renderImage(container, file); break; case 'word': case 'excel': case 'ppt': await renderOffice(container, file, type); break; default: container.innerHTML = '<p class="tip">暂不支持该格式</p>'; } } catch (err) { console.error('[preview] 渲染失败', err); container.innerHTML = '<p class="tip">文件解析失败，请确认文件未损坏</p>'; } });

几个细节值得说：container.innerHTML = ''必须在渲染前执行，否则切换文件时旧内容会残留；整个 switch 包在try/catch里，因为 pdf.js 解析损坏文件时会抛异常，不捕获的话页面直接卡死；await保证异步渲染完成后再处理下一个文件，避免快速切换时渲染错乱。

3.2 PDF 渲染：pdf.js 的分页与缩放

PDF 是这套方案里最核心也最稳的部分。pdf.js 的用法有固定套路：加载文档 → 遍历页 → 每页建 Canvas → 渲染。下面是一个带缩放和分页的完整封装：

// renderers/pdf-renderer.js import * as pdfjsLib from '../lib/pdf.min.js'; // worker 路径必须指向实际文件，否则解析在主线程跑，大文件会卡 pdfjsLib.GlobalWorkerOptions.workerSrc = '../lib/pdf.worker.min.js'; export async function renderPdf(container, file) { const arrayBuffer = await file.arrayBuffer(); const pdf = await pdfjsLib.getDocument({ data: arrayBuffer }).promise; const scale = 1.5; // 缩放系数，1.5 在高分屏上比较清晰 for (let i = 1; i <= pdf.numPages; i++) { const page = await pdf.getPage(i); const viewport = page.getViewport({ scale }); const canvas = document.createElement('canvas'); canvas.className = 'pdf-page'; canvas.width = viewport.width; canvas.height = viewport.height; container.appendChild(canvas); const ctx = canvas.getContext('2d'); await page.render({ canvasContext: ctx, viewport }).promise; } }

getDocument接收{ data: arrayBuffer }，这里用arrayBuffer而不是 URL，是为了支持本地选择的文件，不依赖服务器地址。scale控制清晰度，1.5 是兼顾清晰和性能的折中值，调到 2 以上大文件会明显变慢。viewport决定 Canvas 尺寸，必须和canvas.width/height一致，否则画面会被拉伸。每页渲染完await再进下一页，保证顺序正确。

3.3 图片渲染：最简单但不能省的那几行

图片渲染看起来一行img.src就完事，但有两个坑：一是File对象不能直接赋给src，得先URL.createObjectURL；二是用完必须revokeObjectURL，否则内存泄漏，连续预览几十张图页面就卡了。

// renderers/image-renderer.js export function renderImage(container, file) { return new Promise((resolve, reject) => { const url = URL.createObjectURL(file); const img = new Image(); img.className = 'preview-image'; img.onload = () => { URL.revokeObjectURL(url); // 加载完立即释放 resolve(); }; img.onerror = () => { URL.revokeObjectURL(url); reject(new Error('图片加载失败')); }; img.src = url; container.appendChild(img); }); }

createObjectURL生成的是内存中的临时地址，onload后立刻revoke是标准做法。注意revoke之后img已经完成解码，画面不会消失，但不能再拿这个 URL 做别的用途。onerror里也要释放，否则失败路径同样泄漏。

3.4 Office 文档：前端还原的边界在哪

doc、excel、ppt 是这套方案里最需要说清楚边界的地方。纯前端完整还原 Office 排版几乎不可能，实际项目里通常走两条路：一是用解析库把文档转成 HTML 做近似展示，二是借助在线文档服务的嵌入能力。前者适合内网、对还原度要求不高的场景，后者还原度高但依赖外部服务。

以 docx 转 HTML 为例，常见做法是用mammoth这类库：

// renderers/office-renderer.js import mammoth from '../lib/mammoth.browser.min.js'; export async function renderOffice(container, file, type) { if (type === 'word') { const arrayBuffer = await file.arrayBuffer(); const result = await mammoth.convertToHtml({ arrayBuffer }); // messages 里是转换过程中的警告，比如不支持的样式 if (result.messages.length) { console.warn('[preview] word 转换警告', result.messages); } container.innerHTML = `<div class="doc-body">${result.value}</div>`; return; } // excel / ppt 前端还原成本高，走嵌入或提示下载 container.innerHTML = '<p class="tip">该格式建议下载后查看，或接入在线文档服务</p>'; }

mammoth.convertToHtml接收arrayBuffer，返回{ value, messages }，value是 HTML 字符串，messages是转换警告。这里要诚实：docx 的复杂表格、页眉页脚、图片位置，转出来都会有偏差。excel 和 ppt 的前端还原更麻烦，我的建议是别硬扛，要么接在线文档服务，要么给下载入口。这不是偷懒，是把精力放在真正能保证体验的格式上。

4. 避坑与排查：预览跑不起来的五个真实原因

4.1 PDF 白屏，控制台报 worker 加载失败

现象：选 PDF 后容器空白，控制台出现Setting up fake worker failed或 404。原因：GlobalWorkerOptions.workerSrc路径写错，或者pdf.worker.min.js没和主库放一起。解决：确认 worker 文件实际存在，路径用相对pdf-renderer.js的地址，部署到子目录时尤其容易错。实在排查不出来，可以临时设workerSrc为 CDN 地址验证是不是路径问题。

4.2 大 PDF 渲染时页面卡死

现象：几十页的 PDF 一选，浏览器转圈好几秒，滚动都卡。原因：一次性把所有页都渲染成 Canvas，内存和主线程压力太大。解决：改成懒渲染，只渲染可视区域附近的页，或者先渲染第一页、其余页用占位符，滚动到再渲染。另一个立竿见影的优化是确认 worker 真的生效了，worker 没加载时解析全在主线程跑，卡顿会成倍放大。

4.3 图片预览几张后浏览器变慢

现象：连续预览十几张图，页面越来越卡，任务管理器内存飙升。原因：createObjectURL生成的地址没释放。解决：按 3.3 的写法，在onload和onerror里都调revokeObjectURL。如果图片是异步批量加载的，建议用一个数组记录所有 URL，组件卸载时统一释放。

4.4 Office 文档转出来排版全乱

现象：docx 转 HTML 后表格错位、图片丢失、字体不对。原因：前端解析库对复杂排版支持有限，这是能力边界不是 bug。解决：先明确需求——如果只是「能看个大概」，调大容器宽度、加基础 CSS 重置就能改善不少；如果要求高保真，别在前端硬扛，接在线文档服务或让后端转 PDF 再走 pdf.js。提前和产品对齐预期，比事后返工强。

4.5 本地能预览，部署后 404

现象：开发环境一切正常，传到服务器后 pdf.js 或字体文件 404。原因：静态资源路径是相对路径，部署到带子路径的环境（如/app/preview/）后解析错位。解决：统一用构建工具处理资源路径，或者把lib目录放在和index.html同级并用./lib/...引用。部署前在子目录环境实测一遍，这个血泪经验值得记。

5. 二次开发：把预览器做成可插拔的组件

这套代码真正有价值的地方，不是它能预览几个格式，而是它的结构允许你按需扩展。我一般会做三件事让它更好用。

第一，把渲染器注册表化。现在main.js里是写死的 switch，加格式要改主流程。改成注册表后，新增格式只需注册，不动调度逻辑：

// registry.js const registry = new Map(); export function register(type, renderer) { registry.set(type, renderer); } export async function dispatch(container, file, type) { const renderer = registry.get(type); if (!renderer) throw new Error(`no renderer for ${type}`); await renderer(container, file); } // 使用处 register('pdf', renderPdf); register('image', renderImage); register('word', (c, f) => renderOffice(c, f, 'word'));

registry用Map存类型到渲染函数的映射，dispatch负责查找和调用。这样加 txt、svg、markdown 预览都是新增一个文件加一行注册，主流程零改动。

第二，加统一的加载态和错误态。渲染是异步的，大文件解析期间用户看到白屏会以为坏了。在dispatch前后包一层 loading 遮罩，失败时展示可读的错误信息而不是堆栈。这个改动不大，但对体验提升明显。

第三，验证方法要固定。每次改完渲染器，我固定跑一遍清单：正常文件、损坏文件、超大文件、改过后缀的文件、子目录部署。这五类覆盖了绝大多数线上问题。尤其是「改过后缀的文件」，能验证 2.3 的类型判断是否真的双保险。

最后说个习惯。早些年我做附件预览，图省事把 pdf.js 的 worker 路径写死成开发机的绝对路径，本地跑得飞起，上线当天所有 PDF 全白屏，排查了半天才定位到路径。从那以后我每次接预览类需求，部署前都强制在子目录环境把五类文件各点一遍，确认 worker、字体、静态资源全部 404 清零才敢交付。这份代码你拿去改的时候，也建议先把这套验证清单跑通再动业务逻辑。希望帮到你。

本文还有配套的精品资源，点击获取