Python第一次作业完整指南：环境配置、基础语法与报错排查
2026/9/26 17:39:59
简介：一套基于HTML与JavaScript的浏览器在线预览实现示例，面向需要为Web应用集成文档预览功能的前端开发者，解决PDF、Excel、PPT、DOC、JPG、PNG等常见格式无需下载即可在网页中查看的问题。资源包总共包含6个文件，有一个可直接运行的演示页面、两个精简JS脚本（jQuery库与media预览插件）、一份部署使用说明和两个JPG/PNG测试样张，压缩包大小仅238KB，整体轻量且结构清晰。已有27275人浏览学习，参考价值已得到验证，适合初中级前端工程师快速上手，也可作为教学案例。代码针对不同文件类型给出对应思路：PDF使用object或iframe嵌入，图片直接img预览，Office文档则借助Google Docs Viewer或服务端转换实现兼容；演示页面完整展示了各场景的调用参数与写法，配合使用说明可快速部署到本地项目。通过这套资源，开发者既能掌握原生标签的适用边界，也能了解第三方预览方案的集成方式，在实际项目中少走弯路，快速完成文档预览模块的开发与接入。
1. 浏览器在线预览文件：为什么不能直接打开 Office，却能用 HTML+JS 做
做后台管理系统久了，几乎每个项目都会被问到同一个问题：能不能别下载，直接在浏览器里预览文件？PDF 还好，Excel、PPT、Word 也会被用户塞进来。于是就有了这个标题下我最常用的一套实现——HTML+JS 完成浏览器在线预览文件，支持 pdf、excel、ppt、doc、jpg、png 这些格式。它在解决什么？你不需要先下载再打开，也不一定需要付费组件，甚至不需要一开始就上重量级后端。它的边界也很明确：图片和 PDF 是浏览器原生能渲染的，而 Excel、PPT、Doc 必须走“转换”或“外包给预览服务”的路线。下面会给你能直接复制的代码，也会把真正跑生产时躲不开的坑标出来。适合正在做网盘、OA、ERP、知识库，又被“文件在线预览”卡住的前后端工程师。
2. 选型与整体方案：先分清哪些格式能“直接打开”
2.1 浏览器的原生渲染边界：jpg/png/pdf 和 office 不是同一类问题
先说结论：jpg、png、pdf 是“浏览器原生可以预览”的，excel、ppt、doc 是“必须想办法”的。
图片：<img>一放就能显示，浏览器内部由解码器把 JPEG/PNG 转成位图。关键点是图片的 URL 从哪里来：本地文件用URL.createObjectURL(file)生成一个内存 Blob URL；已上传到服务器，就用服务器的绝对地址。这个 URL 的有效期与页面生命周期相同，不手动释放会一直占内存。
PDF：浏览器内置了 PDF 插件或渲染器。用<iframe>、<object>、<embed>嵌入一个 PDF 地址时，浏览器会把渲染结果画出来。以谷歌浏览器为例，它自带 PDF Viewer，如果你没有改过开关，iframe 打开.pdf会直接显示文件内容，并且出现顶部的工具条。但并不是所有浏览器都允许在 iframe 里渲染 PDF，有的会把 PDF 当成下载资源，弹出下载框而不是显示内容。这个差异和浏览器设置、部署协议、HTTP 响应头强相关，不是 JS 能完全控制的事。
Excel/PPT/Doc：这些是 OLE 或 Office Open XML 格式，浏览器内核并没有实现 Word、Excel 的排版引擎，也没有注册对应的渲染控件。直接把.docx或.xlsx丢给 iframe，大概率看到文件二进制内容或触发下载。有人尝试用前端解析库，把 docx 转成 HTML、把 xlsx 转成表格，这能覆盖一部分场景，但复杂样式、页眉页脚、批注、宏、旧.doc格式全部容易翻车。所以在这个标题的实现里，真正难的并不是“写 JS”，而是先把 Office 文件转成浏览器能吃的格式，再交给 HTML+JS 渲染。
2.2 三条主流路线与适用场景：在线服务 vs 前端解析 vs 服务端转换
常见做法是三条路线。
路线一：在线预览服务。微软 Office Online Viewer、Google Docs Viewer 这类服务，接收一个src参数指向文件的公网 URL，然后返回一个可嵌入的 HTML 页面。前端要做的事就是拼 URL：在iframe的src里写一个带src=参数的地址。优点是开发量极低，几行代码就能看到效果，也不用管 Office 的兼容细节。缺点很要命：文件必须能被公网访问，只要你的服务器在内网或者没有外网出口，这条路直接走不通；第三方服务对文件大小一般有限制，而且数据会经过第三方服务器，涉密文件基本不用考虑。
路线二：前端 JS 解析库。用 SheetJS 读取 xlsx 并渲染成表格，用 Mammoth.js 把 docx 转成 HTML，PPT 可以用 pptxjs 这类库做播放器。优点是部署简单，不依赖外网，数据不出服务器；缺点是格式兼容面积普遍不大。我自己试过用 SheetJS 处理一个带合并单元格、条件格式的 Excel，结果样式补了三天才勉强可用。更麻烦的是 xls、doc、ppt 这种旧格式几乎没有靠谱的纯前端解析库，最后还是要交给后端先转换。所以这条路线只适合“文件格式固定、样式简单”的长期方案，不适合拿来做通用预览。
路线三：服务端格式转换。在服务器上装 LibreOffice 或者 OnlyOffice，把上传的 doc、excel、ppt 统一转成 PDF，前端复用 PDF 预览链路。这是生产环境里我见得最多也最推荐的一条路。优点是完全可控，可以离线部署，能覆盖新旧 office 格式，转换后的 PDF 还能缓存；缺点是占服务器资源，转换有延迟，LibreOffice 对 PPT 动画、复杂字体渲染做不到和 Office 完全一致。
三条路线的取舍可以看这张表：
| 路线 | 保密性 | 开发量 | 大文件支持 | 复杂样式还原 |
|---|---|---|---|---|
| 在线预览服务 | 低，文件经第三方 | 极低，前端拼接 URL | 中，受服务限制 | 中 |
| 前端纯 JS 解析 | 高，数据不出本地 | 中，引库后要补样式 | 低，浏览器内存受限 | 低 |
| 服务端转换 PDF | 高，完全内网 | 中高，需维护转换进程 | 高，可调超时和缓存 | 中高 |
选型建议很直白：个人项目、演示 Demo、内部非敏感文件，用路线一先跑通；数据敏感且文件简单，用路线二；要交付生产环境，老老实实按“后端转 PDF + 前端预览 PDF”设计。比盲目上一个商业组件省钱，也比纯前端解析省心。如果你的团队已经有 OnlyOffice Docs 在跑，也可以直接用它的预览接口，但独立部署复杂度和运维成本要高很多。对大多数后台系统，LibreOffice 转 PDF 是性价比最高的方案。转 PDF 还有一个隐藏优势：前端只用维护一套 PDF 渲染器，后续要支持 CAD 或 AI 文件，也只用把它们转成 PDF，不用为每种格式单独写一套 UI。
2.3 最小架构：HTML+JS 做分发，后端只干两件事
按这个思路，前端预览器其实是一个调度器：前端读取文件 → 识别类型 → 图片和 PDF 自己渲染，Office 文件交给后端转换接口或第三方预览服务。后端只做两件事：保存文件并提供可访问 URL；把 Office 文件转成 PDF。
做最小验证时，后端甚至不需要写多少逻辑。先用一个静态文件服务把上传的文件丢到磁盘目录，返回http://your-server/files/abc.docx给前端。Office 转换暂时不装，先把 PDF 和图片预览跑通，再逐步加转换器。这个渐进式做法适合绝大多数从“下载文件”升级到“在线预览”的后台系统，因为业务方最急的是先解决“能不能看”，而不是“格式多全”。
这里有个容易被误解的点：标题写的是 HTML+JS，但不是说所有转换都在浏览器里完成。Office 文件的版式、字体、分页，只能靠本地渲染引擎。前端做不了，也不该做。正确分工是：JS 负责把“能直接渲染的”直接渲染，把“不能直接渲染的”交给一个总是返回 PDF 的接口。这个接口和后端存储之间可以有缓存层，但对前端是透明的。
接口约定上，我一般会让后端提供两个接口：POST /api/upload返回{ url, name }；POST /api/convert接收文件，返回{ previewUrl }。前端拿到previewUrl后，如果返回的是 PDF，就调用渲染 PDF 的代码；如果返回的是 HTML，就 iframe 套起来。这样 HTML+JS 这一层逻辑保持稳定，后端无论用 LibreOffice、OnlyOffice 还是商业组件，都不影响页面代码。
3. 用 HTML+JS 跑通预览器：核心代码与参数说明
3.1 搭建页面：一个 input、一个预览容器
先搭一个最小页面，本地打开就能测图片和 PDF。代码里包含<!DOCTYPE html>、字符集和基础样式。
<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>HTML+JS 在线预览 Demo</title> <style> #drop-zone { border: 2px dashed #aaa; padding: 20px; text-align: center; margin-bottom: 16px; } #preview-panel { width: 100%; height: 85vh; border: 1px solid #ddd; background: #f5f5f5; display: flex; align-items: center; justify-content: center; overflow: auto; } </style> </head> <body> <div id="drop-zone"> <input type="file" id="file-input" accept=".pdf,.xls,.xlsx,.ppt,.pptx,.doc,.docx,.jpg,.jpeg,.png"> <label for="file-input">选择文件</label> </div> <div id="preview-panel"></div> <script src="preview.js"></script> </body> </html>代码不复杂，重点在#preview-panel。它就是预览容器，图片、PDF 的 iframe、Office 转换后的内容都会往里面塞。accept属性只是给操作系统文件选择器提供过滤，不是安全边界，真正判断还是要看 JS 逻辑。#drop-zone可以再扩展成拖拽区域，在 JS 里监听dragover和drop就行，为了保底，拖拽进来后仍然取event.dataTransfer.files[0]。
3.2 JS 判断文件类型：不要只信扩展名
接下来是预览器能不能做好的关键一步：识别类型。很多代码只根据文件扩展名去判断，遇到“把 ppt 改成 pdf 后缀”的文件，预览就会翻车。可靠的做法是用文件头的 magic bytes 配合扩展名兜底。
function sniffFileType(file) { return new Promise((resolve) => { const reader = new FileReader(); reader.onerror = () => resolve('unknown'); reader.onload = (e) => { const arr = new Uint8Array(e.target.result); const head = Array.from(arr.slice(0, 8)) .map((b) => b.toString(16).padStart(2, '0')) .join(' '); if (head.startsWith('25 50 44 46')) { // %PDF resolve('pdf'); } else if (head.startsWith('ff d8 ff') || head.startsWith('89 50 4e 47')) { // JPEG 或 PNG resolve('image'); } else if (head.startsWith('d0 cf 11 e0 a1 b1 1a e1') || head.startsWith('50 4b 03 04')) { // OLE2 或 ZIP，前者是 .doc/.xls/.ppt，后者是 .docx/.xlsx/.pptx resolve('office'); } else { resolve('unknown'); } }; reader.readAsArrayBuffer(file.slice(0, 8)); }); }说明一下这几个签名：%PDF对应十六进制25 50 44 46；JPEG 的前三个字节是FF D8 FF，PNG 是整个 8 字节签名89 50 4E 47 0D 0A 1A 0A；OLE2 复合文档（老式 Office 文件）以D0 CF 11 E0 A1 B1 1A E1开头；而 docx、xlsx、pptx 本质是 ZIP 包，以PK\x03\x04开头，也就是50 4B 03 04。这个识别方法不依赖file.type，因为浏览器给的 MIME 有时是空的，有时会被 Windows 注册表干扰。我的经验是：先按 magic bytes 分大类，再按扩展名细分为 excel、ppt、doc，但预览链路其实不用分太细，统一丢给 Office 处理即可。
3.3 PDF 和图片预览：用 Object URL 最直接
图片和 PDF 是原生渲染，这是最小闭环的起点。把File转成 object URL，再分别交给img和iframe。
const previewPanel = document.querySelector('#preview-panel'); let currentObjectUrl = null; function renderPdf(pdfUrl) { previewPanel.innerHTML = ''; const iframe = document.createElement('iframe'); iframe.src = pdfUrl; iframe.style.width = '100%'; iframe.style.height = '85vh'; iframe.setAttribute('type', 'application/pdf'); previewPanel.appendChild(iframe); } function renderImage(imageUrl, fileName) { previewPanel.innerHTML = ''; const img = document.createElement('img'); img.src = imageUrl; img.style.maxWidth = '100%'; img.style.maxHeight = '90vh'; img.alt = fileName; previewPanel.appendChild(img); } async function handleFile(file) { const kind = await sniffFileType(file); if (currentObjectUrl) URL.revokeObjectURL(currentObjectUrl); currentObjectUrl = URL.createObjectURL(file); if (kind === 'pdf') { renderPdf(currentObjectUrl); } else if (kind === 'image') { renderImage(currentObjectUrl, file.name); } else if (kind === 'office') { previewOffice(file); } else { previewPanel.innerHTML = '<p>不支持预览，请下载后打开</p>' + downloadButton(file); } }参数说明：URL.createObjectURL(file)生成的地址形如blob:http://localhost:8080/xxx，浏览器内部映射到内存中的文件内容。用 iframe 加载 PDF 时，type="application/pdf"只是给浏览器一个提示，最终是否渲染仍由浏览器内置插件决定；maxHeight: 90vh是给大图做约束，防止超大像素图片把容器顶出去。URL.revokeObjectURL必须放在创建下一条 URL 之前，否则多切几次文件，内存占用只增不减，这在后台系统里就是“用着用着变卡”的经典原因。
注意：PDF 并不总是能按预期渲染。如果浏览器策略禁止 iframe 加载 PDF，可以换<embed>试试，它比 iframe 对插件更友好；再不行就新窗口打开。生产环境我更倾向用 pdf.js 渲染到 canvas，但那是另一个话题，这里不展开。
3.4 Excel/PPT/Doc 预览：在线预览服务与后端转换两条腿走路
到了 Office 文件这一层，纯前端只能做分拣。我给两套写法，第一套适合快速验证，第二套适合生产。
方案 A：第三方在线预览服务。
async function previewOffice(file, remoteUrl) { const officeService = 'https://view.officeapps.live.com/op/view.aspx?src='; const iframe = document.createElement('iframe'); iframe.src = officeService + encodeURIComponent(remoteUrl); iframe.style.width = '100%'; iframe.style.height = '85vh'; previewPanel.innerHTML = ''; previewPanel.appendChild(iframe); }其中remoteUrl来自你后台上传接口的返回字段，必须是公网可访问的完整地址。src参数必须encodeURIComponent整个文件地址，因为远程 URL 嵌套在 query 里面，里面的&、?、中文都要做转义。本地生成的 blob URL 不能给这个服务用，它必须能通过公网访问真实地址。快速验证时，如果文件就在公网服务器，可以先手工拼一个 URL 丢给 iframe 测试，通了再写自动化。
方案 B：后端转换，返回 PDF。
async function previewOffice(file) { const fd = new FormData(); fd.append('file', file); const res = await fetch('/api/convert', { method: 'POST', body: fd }); const data = await res.json(); if (data.previewUrl) { renderPdf(data.previewUrl); } else { previewPanel.innerHTML = '<p>转换失败：' + (data.error || '未知错误') + '</p>' + downloadButton(file); } }previewUrl可以是后端返回的相对地址，如果同源就不需要额外编码。后端转出来是 PDF，前端直接走renderPdf，比单独给 Office 写一套播放器简单得多。方案 B 还有一个好处：用户接下来看到的 PDF 预览行为和普通 PDF 完全一致，避免同一个文件在不同 Office 版本间出现样式漂移。
3.5 预览失败降级：始终给用户一条下载的路
在线预览最大的问题是“不可知”：iframe 是跨域的，JS 没法捕获内部的 HTTP 404 或加载超时。所以我的做法是：预览容器在渲染前就放一个“下载原文件”按钮；如果 15 秒还没有出现可用的渲染内容，再把按钮样式变成一个明显的提示条。下面是兜底逻辑。
function downloadButton(file) { // 实际项目中这个地址应该指向后端的下载接口，而不是直接用文件名 return '<a class="btn" href="/api/download?name=' + encodeURIComponent(file.name) + '">下载原文件</a>'; } function renderWithFallback(renderFn, file) { previewPanel.innerHTML = '<p>如果预览一直没有加载出来，请直接下载原文件</p>' + downloadButton(file); setTimeout(() => { if (!previewPanel.querySelector('img,iframe,embed,canvas')) { previewPanel.innerHTML = '<p>预览加载超时，请直接下载原文件</p>' + downloadButton(file); } }, 15000); renderFn(file); }需要说明的是，这个超时判断并不绝对可靠：iframe 加载一个失败页面也算有元素存在。所以它只能兜底“渲染函数没有成功插入元素”的情况，真正确认跨域 iframe 是否加载成功，前端做不到。更好的方式是在后端加一个探活接口，预览前先 HEAD 一下文件 URL，看响应码和 Content-Type。生产里多一步探活，可以过滤掉很多“白屏”投诉。
4. 在线预览避坑清单：文件名、MIME 与大文件
下面这些坑是我在交付类似需求时反复踩过的，每条都按“现象 → 原因 → 解决”的顺序写。排查时建议先打开开发者工具 Network 面板，看文件请求的状态码和响应头；如果状态码正常，再关注Content-Disposition、X-Frame-Options。很多白屏问题在请求层面就能定位，不需要猜。
4.1 本地 Blob URL 不能直接塞给第三方预览服务
现象：本地选了一个 docx，用URL.createObjectURL(file)生成 URL 后拼到 Office 在线预览地址，iframe 里报错或者一直空白。
原因：blob:URL 只在当前浏览器上下文有效，第三方预览服务器根本访问不到你的文件。它要求在src参数里放一个公网可访问的 HTTP(S) 地址。所以本地调试时，http://127.0.0.1:8080/xxx.docx也不行，因为公网服务访问不到 localhost。
解决：先把文件通过POST /api/upload上传到自己的服务器或对象存储，用返回的公网 URL 去拼装。测试阶段可以用部署在公网上的临时环境。如果对象存储开启了访问签名，注意签名 URL 的有效期和防盗链设置，带时效签名的 URL 在第三方预览服务多次回源时可能会失效，所以最好先转存到一个普通目录，或者拿到真实下载地址。还有一个大前提：如果公司没有公网出口，这条路直接放弃，老实做后端转换。
4.2 中文文件名导致 400，或者预览时文件名乱码
现象：文件名是“2025年1月报表.docx”，后端返回的下载链接一切正常，但拼到预览服务后请求报 400；自己在浏览器里预览 PDF 时，标签页标题显示一串乱码。
原因：URL 拼接时没有做完整的encodeURIComponent，或者服务端保存文件时保留了中文名，而代理层、预览服务对非 ASCII URL 的解析不一致。iframe的src属性虽然会自动编码一部分，但嵌套在 query 里的完整 URL 还是要手动编码。
解决：前端拼 URL 时对文件地址做整体编码，不要用字符串直接拼；后端保存上传文件时最好重命名为随机 ID 加后缀，例如20250101_ab12.docx，原始文件名存数据库。这样所有 URL 都是纯 ASCII，预览服务和缓存层都不会踩中文编解码的坑。这个习惯在对接第三方预览服务时尤其重要，因为它们对 URL 的容错很低。
4.3 PDF iframe 被 X-Frame-Options 或 CSP 拦住
现象：本地打开 HTML 文件预览 PDF 正常，部署到公司服务器后，iframe 里一片空白。打开浏览器控制台能看到类似Refused to frame ... because it set 'X-Frame-Options: SAMEORIGIN'的报错。
原因：存放 PDF 的服务器（Nginx、Tomcat 或云对象存储）在响应头里设置了X-Frame-Options: SAMEORIGIN或CSP: frame-ancestors，浏览器拒绝将页面嵌入到其他来源的 iframe 中。常见的后端框架如 Spring Security 默认也会加这个响应头，很多人不知道。
解决：如果是 Nginx 代理文件，去掉该路径的X-Frame-Options限制；如果是后端框架加的，对预览接口单独覆盖响应头。文件接口还要注意Content-Disposition，返回inline而不是attachment。改完用curl -I看一眼响应头，确认content-disposition: inline且没有被 CSP 禁止再继续。如果文件放在第三方对象存储且不允许改响应头，可以加一层后端代理，把文件流读回来再返回给前端，同源后自然不受跨域限制。
4.4 大文件预览导致的页面崩溃和超时
现象：用户上传 80MB 的 PPT，预览页转圈 2 分钟后浏览器标签页崩溃；或者第三方预览服务直接返回“文件过大”。
原因：PDF 渲染需要浏览器把整个文件载入内存，Office 转 PDF 的过程也要解压 ZIP 包，内存占用成倍增长。在线预览服务一般有文件大小上限，常见是 10MB 附近；同步调 Library 的转换大文件又容易超时，最终 HTTP 连接挂住，用户端表现为一直加载。
解决：前端在上传时做大小预检，超过 20MB 直接提示“大于预览上限，请下载”；后端转换务必做成异步任务，接口先返回taskId，前端轮询任务状态，不要用同步请求把连接挂 5 分钟。压测时也要注意 LibreOffice 并发：同时转多个文件会互相锁，需要给每个转换任务配置独立的UserInstallation参数。如果文件实在太大，宁可让业务人员下载原文件也不要硬做预览，不值得为极端场景透支服务器性能。
4.5 旧版 .doc/.xls/.ppt 的兼容性比想象中差
现象：用户拿.doc预览成功，但.xls预览出来后表格样式完全错乱，甚至提示文件损坏；.ppt预览只有文字，没有排版和动画。
原因：.doc、.xls、.ppt是 OLE2 复合文档格式，和新的 Office Open XML（.docx、.xlsx、.pptx）不是一回事。LibreOffice、在线预览服务虽然能打开，但转换出的样式还原度远不如新格式；旧格式本身也没有严格的页面布局描述。前端纯 JS 库更不用说，几乎没有能解析这些旧格式的。
解决：在预览页明确提示用户优先上传新格式；后端转换前用系统file命令探测真实类型，如果是 OLE2，给soffice指定对应的过滤器参数再转。实测中发现.xls转 PDF 经常把列宽挤在一起，.ppt转 PDF 的文字位置会偏移，这是组件能力限制，不是代码 bug。处理办法是：降低对旧格式的还原预期，功能上只保证“能看个大概”，同时放大“下载原文件”的入口。这个结论不是我硬想出来的，而是开源组件本身对旧格式支持就这么有限。
5. 再进一步：把 Office 转成 PDF 做离线预览，以及一些验证技巧
5.1 用 LibreOffice 转 PDF 的命令与参数
如果你决定走服务端转换，最省事的工具是 LibreOffice 的命令行。一行命令就能把 docx、xlsx、pptx 转成 PDF：
soffice --headless --convert-to pdf --outdir /data/preview /data/upload/20250101_ab12.docx参数说明：--headless是无界面模式，适合在服务器上跑；--convert-to pdf会根据输入文件扩展名自动选择过滤器；--outdir指定输出目录，缺省会输出到当前目录。对.xlsx和.pptx同样适用，转换完成后生成的文件名是20250101_ab12.pdf。
常见坑是 root 用户直接跑soffice可能报初始化错误，因为 LibreOffice 需要 HOME 目录，指定一个可写目录即可：
HOME=/tmp soffice --headless --convert-to pdf --outdir /data/preview /data/upload/xxx.pptx另一个坑是并发。LibreOffice 默认共用一个UserInstallation，同时转换多个文件会互相等锁。给每个转换任务加一个独立 profile 参数：
soffice -env:UserInstallation=file:///tmp/lo_profile_12345 --headless --convert-to pdf --outdir /data/preview /data/upload/xxx.pptx12345可以用任务 ID 替代，保证并发进程之间不冲突。转换超时可以用timeout 60 soffice ...控制，超时就放弃并返回错误。
5.2 转换后的缓存与清理
在线预览没必要每次请求都重新转换。转换完成后的 PDF 可以缓存 30 分钟，映射关系放在内存或 Redis 里。
| 键 | 值 | 过期 |
|---|---|---|
| 原文件 MD5 | 转换后 PDF 路径 | 30 分钟 |
| 任务 ID | 转换状态 | 2 小时 |
如果转换结果存在临时目录，写一个 crontab 清理 2 小时前的文件，比如find /data/preview -type f -mmin +120 -delete。这样响应变快，磁盘也不会被打爆。
5.3 验证预览是否可用的三组自测用例
交付前建一个小文件库，至少准备三个样本：一个带中文文件名、包含中文和表格的 docx；一个多 sheet、带合并单元格和公式的 xlsx；一个包含嵌入图片和 SmartArt 的 pptx。每个样本都跑一遍“上传 → 预览 → 切换 → 下载”的流程，对比原文件和转出 PDF 的排版差异。如果 docx 转出的 PDF 中文变成方框，多半是服务器缺中文字体，安装对应字体后重新转换即可。把这三组样本作为回归用例，后面每次改代码都跑一遍，比临时拍脑袋测试高效得多。
我自己的习惯是把所有格式先统一转成 PDF，再让前端专心处理“PDF 和图片”，因为这样逻辑最简单，线上出问题也好排查。做这个方向几年下来，发现 90% 的在线预览需求，一台能跑 LibreOffice 的 Linux 服务器加一个 HTML+JS 页面就能解决，不需要上昂贵组件。希望帮到你。
本文还有配套的精品资源，点击获取