Vue 3 文件预览最常见的生产故障是开发环境可以打开 DOCX、XLSX、PPTX 或 PDF部署后却白屏控制台只留下一条 Worker 加载失败或者 Network 中出现 WASM、字体、vendor 资源 404。这类问题不要从“重装组件”开始。按照下面的顺序排查通常能更快找到真正断点确认失败的是文件请求还是解析器运行时核对 Vitebase与生产访问路径确认 Worker/WASM 和主包来自同一版本根据鉴权方式选择 URL 或 File单独检查大 PDF 的 Range 与内存用真实生产基址完成四类文件回归。1. 先在 Network 中把请求分成两类打开浏览器 DevTools过滤失败请求先判断 404 属于哪一类。第一类是业务文件本身例如/api/attachments/42 /files/contract.docx /object-storage/signed-url这类请求失败优先检查登录态、签名时效、CORS、反向代理和文件权限。第二类是解析器运行时例如/oa/file-viewer/pdf.worker.min.mjs /oa/file-viewer/pptx.worker.js /oa/file-viewer/*.wasm /oa/file-viewer/fonts/*这类请求失败说明 Vue 组件已经运行但按需资源没有正确发布。业务文件换多少次都不会解决。2. Vite 子路径要同时影响入口和运行时假设应用最终地址是/oa/Vite 配置应该使用同一个基址并在构建时复制运行时资产// vite.config.tsimport{defineConfig}fromviteimportvuefromvitejs/plugin-vueimport{fileViewerRenderers}fromfile-viewer/vite-pluginexportdefaultdefineConfig({base:/oa/,plugins:[vue(),fileViewerRenderers({copyAssets:true}),],})生产环境正确请求应以/oa/file-viewer/开头。如果实际请求是/file-viewer/说明资源地址退回了域名根目录如果请求路径正确但文件不存在则检查构建产物与部署脚本。可以先在产物目录中确认资源是否真的存在finddist-maxdepth3-typef|grepfile-viewer如果项目不使用 Vite可以在构建阶段显式复制npx --no-install file-viewer-copy-assets ./public/file-viewer静态资源统一部署到其他目录时设置完整基址import{setDefaultFullAssetBaseUrl}fromfile-viewer/vue3-fullsetDefaultFullAssetBaseUrl(/static/file-viewer/)3. 不要让主包和 Worker/WASM 跨版本拼装文件预览运行时不是一组永久不变的静态文件。主包、Worker、WASM 和 vendor 之间可能共享消息结构、导出名称和资源约定。一个常见故障过程是前端依赖从旧版本升级CI 重新构建了 JavaScript静态服务器沿用之前手工上传的file-viewer/页面加载成功命中特定格式后才失败。修复方式不是继续补单个文件而是让构建过程每次从当前依赖生成整套运行时再与前端产物一起发布。4. 鉴权接口不要盲目传 URL公开 URL、同源 Cookie 接口、短期签名地址可以直接交给预览组件。这样 PDF 等格式仍有机会使用缓存和 Range。需要自定义 Header、解密或统一处理 401 时让业务层先下载script setup langts import { ref } from vue import { FileViewer } from file-viewer/vue3-full const previewFile refFile() const errorMessage ref() async function openAttachment(id: string, filename: string) { errorMessage.value const response await fetch(/api/attachments/${id}, { credentials: include, headers: { X-Preview-Request: 1 }, }) if (!response.ok) { errorMessage.value 附件读取失败${response.status} return } const blob await response.blob() previewFile.value new File([blob], filename, { type: blob.type, lastModified: Date.now(), }) } /script template button clickopenAttachment(42, 合同.docx) 预览合同 /button p v-iferrorMessage{{ errorMessage }}/p FileViewer v-ifpreviewFile :filepreviewFile / /template构造File时要保留真实扩展名。某些下载接口返回统一 MIME只有合同.docx这个名称能稳定告诉路由层应该进入哪条解析链路。5. 大 PDF 要单独检查 Rangefetch Blob通常需要完整下载并在浏览器中保留完整二进制。对于大 PDF这可能带来明显等待和内存峰值。如果业务允许同源 URL可以在 Network 中检查是否出现Request Headers Range: bytes0-65535 Response HTTP/1.1 206 Partial Content Content-Range: bytes 0-65535/734003200服务端返回200 OK并完整传输文件时即使响应里写了Accept-Ranges也不能说明渐进读取已经成功。需要自定义鉴权 Header 且文件很大时不要只在开发机验证。应明确文件上限、设备内存、取消下载行为和失败提示必要时为这类文件提供服务端转换或专用流式接口。6. 四类文件分别验证内容统一组件只统一了入口不能把验收也缩成一个布尔值。DOCX页眉页脚、表格、图片、字体XLSX合并单元格、样式、大表滚动、中文编码PPTX页序、主题、图片和 Worker 请求PDF目录、中文字体、旋转页、打印和 Range。当前验证基线中208 个已注册扩展名映射到 25 条预览链路。它是扩展名到能力路由的数量不是 208 套独立渲染器。本文的 PowerPoint 范围也只包括.pptx不把内部结构不同的.ppt混在一起。7. 可直接执行的生产检查清单构建与路径使用生产base执行 build 和 preview确认dist中存在完整file-viewer/确认生产请求路径包含/oa/确认主包、Worker、WASM 来自同一版本。权限与网络URL 路径覆盖 Cookie、签名过期、CORS 和 RangeFile 路径覆盖 401、下载中断、取消和快速切换断开公网确认没有隐藏 CDN 依赖。内容与性能四类文件各准备一个真实脱敏样本验证内容不只验证首屏记录浏览器版本、设备内存、文件大小、页数和峰值内存。总结“本地能开、上线白屏”通常不是 Vue 组件突然失效而是输入、路径或运行时交付只完成了一半。排查时按这个顺序最省时间先区分文件请求与运行时请求再核对base然后检查版本一致性最后根据鉴权和文件大小选择 URL 或 File。本次示例按 File Viewer v2.2.5 验证。把 Worker、WASM、字体和真实生产回归纳入交付后文件预览才不再是只能在开发机上成立的一段代码。