企业官网建设流程全解析

做在线文档预览这需求，我入行这些年接过不下十次。每次都是文件管理系统、OA办公流、项目管理后台这类场景，而且无一例外都是vue3+TypeScript的技术栈。你问我为什么这么确定？因为新项目基本没人再开vue2了。但文档预览这件事，真正做起来才发现坑比想象中多——PDF、Word、Excel三种格式，底层结构完全不同，没有一种“一招鲜”的方案能通吃。这篇就把我踩过的坑和最终落地的方案完完整整写出来，直接照着抄就行。

1. 方案选型：先给三种文件“对症下药”

1.1 直接预览还是先转换：一条分水岭

很多朋友上来就搜“在线预览插件”，然后发现网上推荐的无非就那几样：vue-office、docx-preview、pdfjs-dist、SheetJS。但真正设计之前，必须先搞清楚一个问题：你要的是“渲染文件内容”，还是“还原文件原貌”？

这两个目标差着十万八千里。

如果只是渲染内容，PDF可以直接走pdf.js的Canvas渲染内核，Word用mammoth.js把docx解析成HTML展示，Excel用SheetJS把单元格数据读出来画成表格。这条路纯前端搞定，架构简单、部署成本低，缺点也很明显——样式还原度有限，尤其是Excel，合并单元格、条件格式、图表这些复杂元素几乎都会丢。

如果追求原貌还原，“后端转PDF + 前端预览PDF”是业界最稳妥的路线。后端用LibreOffice或者Aspose这类工具，把docx和xlsx统一转成PDF，前端只面对一种格式，渲染效果和Office里看到的基本一致。缺点是每台服务器都要装LibreOffice，转码消耗CPU和内存，在线预览的首次打开速度会慢个两三秒。

我这两种方案都试过。如果你的业务是内部系统、管理后台，用户看个数据、批个流程，直接走方案一，体验足够、成本为零。如果做的是面向客户的合同签署、报表展示，对还原度有硬性要求，那老老实实配后端转换服务。

我的做法是混合的：先做一套前端预览器覆盖80%的常规场景，然后留一个“转换后预览”的接口，要还原度的文件走到后端。

1.2 我为什么抛弃了“全后端转PDF”方案

2019年我刚做文档预览那会儿，第一版就是“后端统一转PDF”。当时理由很简单：前端一个pdf.js搞定所有格式，不用维护三套渲染逻辑。实际跑起来问题一串：

• 后端装LibreOffice要单独写Dockerfile，镜像大了将近1GB，CI构建时间肉眼可见地变慢。
• 用户上传一个50MB的PPT，LibreOffice单线程转换，耗时十几秒是常态，请求超时问题接着冒出来。
• 一个后台页面同时被几百个人打开，后端转码队列瞬间堆满，OSS的多线程并发直接导致CPU报警。

后来想通了：用户不是要求每一页都像素级一致，他只要能在浏览器里看到内容、找到关键信息。满足这个阈值，纯前端方案是性价比最高的。

1.3 最终选型：PDF用渲染内核，Word/Excel走解析渲染

经过对比，我定下了这套技术组合：

这个组合确定后，后面所有边界情况都好办了。遇到老的.doc、.xls扩展名，自动提示“该格式已不支持在线预览，请下载后查看”，要么转成PDF。

2. 环境搭建与PDF预览落地

2.1 初始化Vue3+TypeScript工程

新建项目这一步不多说，直接Vite搞定。这两年我一直用npm create vite@latest走vue-ts模板，比webpack配置直观太多，冷启动秒开。

npm create vite@latest doc-preview-demo -- --template vue-ts cd doc-preview-demo npm install

然后装上今天的主角们：

npm install pdfjs-dist vue-pdf-embed npm install mammoth npm install xlsx

这三个库的生态都很稳定，但是版本兼容性值得盯一下。pdfjs-dist大版本升级时会调整API，比如3.x版本用GlobalWorkerOptions.workerSrc，到Vite工程里还需要配合?url方式导入worker文件。xlsx这个包名在npm上的社区版停在0.18.5，日常解析完全够用，如果遇到CEX（Community Edition）特殊需求，可以去官方CDN拿最新版。

2.2 PDF预览：pdf.js worker是最大的坑

我见过太多人卡在这一步：PDF组件写了，页面也出来了，但控制台哗啦啦报一个“Failed to fetch dynamically imported module”或者“worker-src”错误。为什么？因为pdf.js的解析计算量非常大，它把核心解析逻辑放在单独的Worker线程跑，而Worker文件的路径必须你自己显式指定。

Vite下最省心的写法：

// src/utils/pdf.ts import { GlobalWorkerOptions } from 'pdfjs-dist' import PdfWorker from 'pdfjs-dist/build/pdf.worker.min?url' GlobalWorkerOptions.workerSrc = PdfWorker

这个?url后缀是Vite的静态资源导入语法，构建时会自动复制worker文件到输出目录并把访问路径处理成字符串。

只用裸的pdfjs-dist还不太方便，翻页、页码显示、缩放都要自己封装，所以我一般都再包一层vue-pdf-embed，它把滚动、缩放、翻页这些交互全都做好了。安装完直接在组件里用：

<!-- src/components/PdfViewer.vue --> <script setup lang="ts"> import { ref, watch } from 'vue' import VuePdfEmbed from 'vue-pdf-embed' import { GlobalWorkerOptions } from 'pdfjs-dist' import PdfWorker from 'pdfjs-dist/build/pdf.worker.min?url' GlobalWorkerOptions.workerSrc = PdfWorker const props = defineProps<{ url: string }>() // 文本复制、打印、目录锚点这类能力都封装在组件内部 const pdfSrc = ref(props.url) watch(() => props.url, (val) => { pdfSrc.value = val }) </script> <template> <div class="pdf-container"> <VuePdfEmbed :source="pdfSrc" /> </div> </template>

一个很多人没注意到的小点：pdfjs-dist渲染带中文子集的PDF时，有些字形会显示成乱码方块。原因是PDF内嵌字体包缺失部分cmap映射表。解决方式是在调用渲染时配置cmaps路径：

// 在引入worker后补充 import * as pdfjsLib from 'pdfjs-dist' pdfjsLib.GlobalWorkerOptions.workerSrc = PdfWorker const pdfLoadingTask = pdfjsLib.getDocument({ url: 'xxx.pdf', cMapUrl: 'https://unpkg.com/pdfjs-dist@3.11.174/cmaps/', cMapPacked: true, })

我第一次把这串配置去掉试过，同一个PDF在Chrome上显示正常，Firefox和移动端WebView上字体全变方块了。排障优先级里，字体异常永远优先怀疑cMap配置。

2.3 封装可复用的PDF预览组件

业务中一个文件预览页通常还需要侧边栏显示目录、顶部工具栏显示页码。vue-pdf-embed支持插槽，脚手架搭起来后可以很轻松扩展：

要显示目录，需要用pdfjs的getOutline()方法，返回结果是一棵节点树。处理方式：

const outline = ref<any[]>([]) const pageInstance = ref<InstanceType<typeof VuePdfEmbed>>() async function loadOutline() { const pdf = await pdfjsLib.getDocument({ url: props.url, cMapUrl, cMapPacked: true }).promise outline.value = await pdf.getOutline() ?? [] } function jumpToDest(dest: any) { // dest可能是一个数组，需要由PDF文档解析为具体页码 const target = Array.isArray(dest) ? dest[0] : dest pageInstance.value?.scrollToPage(target) }

需要注意的是getOutline()返回的dest不是页码，而是PDF内部的命名目标或数组目标，直接用会跳错位置。更靠谱的做法是遍历目录时调用pdf.getDestination(item.dest)去拿实际坐标，再用pdf.getPageIndex(destRef)转页码。这块代码比较绕，但目录跳转是PDF阅读器的标配功能，值得写一次。

3. Word在线预览：mammoth.js把DOCX“翻译”成HTML

3.1 为什么docx不能像PDF一样直接渲染

PDF是一张“拍好的照片”，每一页的坐标、字体、图形都定死了，渲染器按坐标画出来就行。docx本质上是个zip压缩包，里面全是XML文件——document.xml描述段落和文字，styles.xml定义样式，media夹着图片。浏览器没法直接画XML，必须有人把它“翻译”成HTML才能展示。

这个“翻译官”就是mammoth.js。它解析WordprocessingML，输出干净的HTML字符串，不依赖庞大渲染器。实测下来，日常文档的标题层级、加粗斜体、列表、表格样式都能准确转换，而且打包体积才26KB，代价几乎可以忽略。

3.2 用mammoth做docx到HTML的转换

mammoth的使用很直接，给它一个ArrayBuffer或者Buffer，它还给你{ value, messages }。value就是渲染用的HTML字符串，messages里记录了转换过程中遇到的样式警告，比如“忽略未知样式xxx”。

// src/utils/word.ts import mammoth from 'mammoth' export async function convertDocxToHtml(file: File | Blob) { const arrayBuffer = await file.arrayBuffer() const result = await mammoth.convertToHtml({ arrayBuffer }) return result.value }

组件内拿到HTML字符串后，用一个div渲染并缓存：

<!-- src/components/WordViewer.vue --> <script setup lang="ts"> import { ref, watch } from 'vue' import { convertDocxToHtml } from '../utils/word' const props = defineProps<{ file: File | Blob }>() const htmlContent = ref('') const isLoading = ref(false) watch(() => props.file, async (file) => { if (!file) return isLoading.value = true try { htmlContent.value = await convertDocxToHtml(file) } finally { isLoading.value = false } }, { immediate: true }) </script> <template> <div class="word-viewer" v-html="htmlContent"></div> </template>

用v-html是最直接的方式，但一定注意：只渲染由后端接口或本地上传文件转换出的HTML，不要直接把不可信的富文本内容塞进这个容器，否则XSS漏洞会教你做人。如果文档来源完全不可控，最好在渲染前做一遍HTML sanitize，或者用sanitize-html库把<script>、onerror这类危险标签清掉。

3.3 图片和样式的兜底处理

mammoth默认会把docx里的图片转成内联的base64 data URL，这样展示HTML时图片自动带上，不用额外加载资源。但一张高清图转换成base64后体积膨胀约33%，几十张图的大文档可能导致HTML字符串几十MB，内存直接报警。

我当时的处理是分两步：先用mammoth的convertToHtml拿到结果，然后用正则把data:image/...;base64,...提取出来，上传到我们自己的OSS换取CDN地址，再替换回HTML。这样页面渲染不卡，流量也走了CDN，成本可控。

// 提取并替换图片的伪代码 const html = result.value const base64Pattern = /<img src="data:image\/[^;]+;base64,([^"]+)"[^>]*>/g // 处理逻辑：异步上传、拿到新地址、replace

还有一种情况：docx里嵌入了“浮于文字上方”的文本框、艺术字这些元素，mammoth转出来会丢失，变成一段普通文本甚至直接没了。这种文件我们内部定义为“复杂版式文档”，直接引导用户下载原文件，不去跟它死磕。

4. Excel在线预览：SheetJS解析加自定义渲染

4.1 直接看xlsx：它是zip包不是图片

Excel文件没办法像PDF那样直接画，因为解压出来的每个XML都只是数据描述。SheetJS做的就是把zip包里的sharedStrings.xml、sheet1.xml这些零件读出来，还原成一个由单元格组成的二维表结构。

SheetJS最巨大的优势是解析速度快。20MB左右的大表，纯前端解析也就一两秒，内存占用可以接受。我在一个报表系统里实测过，XLSX.read大文件时比之前用后端POI解析再走接口返回JSON快多了，省了一轮网络传输。

4.2 用SheetJS读数据并渲染成表格

经典写法：

import * as XLSX from 'xlsx' export function extractExcelHtml(file: File | Blob) { return new Promise((resolve) => { const reader = new FileReader() reader.onload = (e) => { const data = new Uint8Array(e.target?.result as ArrayBuffer) const workbook = XLSX.read(data, { type: 'array', cellDates: true }) // 默认预览第一个工作表 const firstSheet = workbook.Sheets[workbook.SheetNames[0]] const html = XLSX.utils.sheet_to_html(firstSheet) resolve(html) } reader.readAsArrayBuffer(file) }) }

sheet_to_html返回的HTML自带一个<table>结构，浏览器直接渲染就能看到内容。但说实话这个HTML很素，没有表头冻结、没有单元格宽度自适应、没有合并单元格的样式美化，拿到生产环境肯定不够看。我通常在这个基础上做两层加工：

第一层，把返回值里的<table>提取出来，自己写外层容器，加入横向纵向滚动和全屏切换。 第二层，对表头的样式做统一，加个背景色，列宽取内容最大宽度和固定最小值的较大者。

合并单元格这块sheet_to_html会自动带上rowspan、colspan属性，基本不用额外处理。唯一要小心的是合并区域跨行跨列后文本内容只在左上角单元格，没有数据的位置是空的，这个符合Excel本身的展示逻辑。

4.3 日期序列号、合并单元格、公式缓存值

Excel里日期本质上是一个数字，比如44927表示2023年1月1日。如果直接渲染，用户看到一串数字完全懵。解决方式是读取时设置cellDates: true，SheetJS会自动把日期格式的单元格解析成JS Date对象。如果拿到的还是数字，手动转换也有明确公式：

function excelSerialToDate(serial: number): Date { // 25569是1970-01-01在Excel序列号体系中的值 return new Date(Math.round((serial - 25569) * 86400 * 1000)) }

公式单元格要注意：SheetJS默认不计算公式结果，读出来的f字段是公式字符串（比如=SUM(A1:A10)），v字段才是缓存结果。直接在表格里展示公式文本不是好事，对业务用户来说，看到计算后的数字才有意义。我一般在解析前设置：

XLSX.read(data, { type: 'array', cellDates: true, cellFormula: true, cellNF: true, cellText: true })

其中cellNF能拿到数字格式，这样渲染数字时能带上千分位、保留小数位等原始格式。

如果你需要更进一步，比如用户要在浏览器里编辑Excel，那就要上Luckysheet或者Univer了，那是另一个维度的工程量。SheetJS只能做到“读”和“展示”，真要双向编辑，老老实实选专业表格组件。

5. TypeScript类型封装：多格式统一预览入口

5.1 统一文件预览组件架构

业务里文件预览不是单独一个页面，而是对话框里弹出、列表旁边小窗展示、分享链接跳转等等场合都要用。所以我把预览能力封装成一个统一组件FilePreview，外部只传文件信息和文件类型，内部自动路由到对应渲染器。

<!-- src/components/FilePreview.vue --> <script setup lang="ts"> import { computed } from 'vue' import PdfViewer from './PdfViewer.vue' import WordViewer from './WordViewer.vue' import ExcelViewer from './ExcelViewer.vue' type PreviewFileType = 'pdf' | 'docx' | 'xlsx' | 'unsupported' const props = defineProps<{ file: File | Blob fileName: string }>() const fileType = computed<PreviewFileType>(() => { const ext = props.fileName.split('.').pop()?.toLowerCase() if (ext === 'pdf') return 'pdf' if (ext === 'docx') return 'docx' if (ext === 'xlsx') return 'xlsx' return 'unsupported' }) </script> <template> <PdfViewer v-if="fileType === 'pdf'" :file="file" /> <WordViewer v-else-if="fileType === 'docx'" :file="file" /> <ExcelViewer v-else-if="fileType === 'xlsx'" :file="file" /> <div v-else class="unsupported">当前格式暂不支持在线预览，请下载查看</div> </template>

这样调用方只需要关心一件事：把文件对象和文件名传进来。内部怎么解析、怎么渲染、怎么报错，全被隔离在预览器内部。

5.2 类型定义与声明文件

TypeScript项目里这三个库的类型支持情况不太一样：

• pdfjs-dist自带完整类型，不用额外装@types。
• mammoth从1.6.0版本开始自带类型，可用。但老版本需要用@types/mammoth补上。
• xlsx的npm包类型定义比较老，如果编辑器报错，我一般直接写一个env.d.ts做局部声明兜底。

// src/types/shims.d.ts declare module 'xlsx' { export * from 'xlsx/types' }

如果某个库连类型文件都不带，比如某些内部封装模块，就自己声明个模块，导出需要的函数签名：

declare module 'custom-doc-parser' { export function parseDocument(input: ArrayBuffer): Promise<string> }

TypeScript的好处是能把“预览器该接收什么”这件事在编译期就定死。我后来在重构预览组件时，逼着所有渲染器统一实现一个Renderer接口，新增格式只需要追加一个文件实现，不会动其他渲染器的逻辑：

interface FileRenderer { type: PreviewFileType render(file: File): Promise<void> destroy(): void }

5.3 大文件与多文件切换的体验优化

多文件切换这个场景很容易被忽视。预览器在watch到新的文件源时，必须把上一次的解析产物重置掉。我最初写的时候没有处理，结果用户切换文件时页面还残留着上一个文件的渲染内容一闪而过，观感很差。

建议在切换文件时统一进入loading状态，解析完成后再渲染：

// 在统一组件里管理状态 const currentTask = ref<{ status: 'idle' | 'loading' | 'error'; raw?: string }>({ status: 'idle' }) async function switchFile(nextFile: File) { currentTask.value = { status: 'loading' } try { const renderer = getRenderer(fileType.value) await renderer.render(nextFile) currentTask.value = { status: 'idle' } } catch (e) { currentTask.value = { status: 'error' } } }

另外一个细节是取消旧任务。如果用户连点几次切换，之前的异步解析还在跑，返回后却把结果渲染到新文件上。可以维护一个taskId，每次解析前自增，返回后在闭包里比较是否需要丢弃结果。

6. 生产环境踩坑实录与排查思路

6.1 worker加载404：路径与跨域

最典型的场景是构建部署到Nginx后，PDF预览白屏，打开控制台看到pdf.worker.min.js的404。原因一般是Worker文件被放在/assets子路径下，但你的部署路径不是根目录，导致路径拼接出错。

解决方案有两类：

要么不用?url导入，改成一个绝对地址，比如把pdf.worker.min.js拷到public目录下，直接/pdf.worker.min.js引用。

要么用new URL('pdfjs-dist/build/pdf.worker.min.js', import.meta.url).toString()，由Vite在构建时帮你生成正确的资源URL。我倾向于这种，部署到任何子目录都能自适应。

跨域场景则是另一种情况：文件资源在CDN上，PDF预览请求CDN地址时，字体子集加载、worker跨域访问都被浏览器拦截。这种情况老老实实在CDN配置CORS响应头Access-Control-Allow-Origin: *，否则前端怎么调都白搭。

6.2 加密PDF和扫描版PDF

密码保护的PDF，pdf.js默认不支持解密。常规做法是后端接收到加密PDF时调用qpdf之类的命令行工具解除密码，然后再把这个文件提供给前端。直接在前端尝试破解密码既不现实也不合规。

扫描版PDF则是另一个痛点——全是图片，pdf.js渲染出来就是一张张没有文字的图片。用户想复制文字、想搜索内容都做不到。这个需求往上走就是OCR了，前端做Tesseract.js虽然能跑，但识别率和性能对大字库中文文件很不理想。我的建议是遇到扫描件，直接推送后端OCR服务，识别完成后再把可检索的PDF或者文本层交给前端展示。别在前端硬扛。

6.3 大Excel渲染卡顿

Excel解析后sheet_to_html生成的表格如果行数上万，DOM节点数量爆炸，页面滚动会卡成PPT。我实测过，1万行渲染成DOM大约需要800ms，但这个数字翻倍后，浏览器重排重绘的时间会指数级增长。

三种缓解策略：

第一，前端分页。把SheetJS解析出的sheet_to_json数据切成每页几百行，翻页时重新渲染表格。 第二，虚拟滚动。使用vue-virtual-scroller或者@tanstack/vue-virtual这类虚拟列表库，只渲染可视区域的DOM。数据流走sheet_to_json，自己用grid布局渲染单元格，而不是用sheet_to_html。 第三，放弃前端渲染，后端把Excel转成PDF再预览。万一遇到超大文件，这是最保底的做法。

我在实际项目中，凡是超过2万行的报表，都直接走后端转PDF方案。前端无论怎么做虚拟滚动，给用户的体验也只是“能滚动”，而转PDF后用户既能看到完整样式，又可以下载存档，一举两得。

6.4 样式还原度不够怎么办

Word和Excel预览，前端方案的软肋就是复杂样式还原度。

Word里如果用了大量分节符、页眉页脚、批注，mammoth转出来的HTML会丢失这些区域，甚至把批注也丢干净，对用户来说内容少了，这是不能接受的。

Excel更严重，图表、数据透视表、条件格式、筛选箭头，这些都不是简单的XML节点，没法用SheetJS还原。

遇到这类问题不用硬扛。我在系统里设计了一个“还原级别”概念：每个上传文件解析时都抽取一个难度标记——包含图表、包含宏、包含复杂页眉的一类；纯文本、简单表格的二类。一类文件直接引导用户下载原文件，或者走后端LibreOffice转PDF兜底；二类文件前端预览。这样用户看到“不支持预览”时，至少理由充分，不会觉得是系统bug。

6.5 浏览器兼容性提醒

pdf.js的现代版本对浏览器内核有要求，IE11肯定不支持，老的Edge也悬。如果你们系统还要兼容Chromium 70以下的嵌入式WebView，那pdf.js版本选择要慎重，可能得降到2.x时代的老版本。

vue-pdf-embed和mammoth对浏览器要求相对低，但ArrayBuffer、Blob这些API在IE里也是残缺的，统一模板项目里都加了core-js的polyfill才能跑。新项目建议直接规定“Chrome 80+ / Edge / Safari 12+”，省去无休止的兼容性填坑。

我个人在实际操作中的体会是：在线预览最值钱的不是“渲染某个格式”的代码，而是“对文件格式的判断和降级策略”这套机制。PDF做出来不难，难在遇到加密PDF、扫描PDF、超大Excel时知道抄哪套方案。把这套机制设计好，后面加新格式（比如pptx、markdown）都只是往渲染器池里再塞一个文件的问题。

最后再分享一个小技巧：预览组件在onBeforeUnmount钩子里一定记得释放资源，尤其是PDF的pdf.destroy()和工作线程。我见过线上系统预览一百来个PDF之后内存直接飙到1GB的，都是忘了销毁旧实例。组件卸载时把loadingTask.destroy()和worker terminate调用了，内存曲线稳得很。这个细节写进你们的Code Review清单里，能让前端少挨很多顿骂。