Vue 3 文件预览生产排障：Worker/WASM 404、鉴权 Blob 与子路径

Vue 3 文件预览最常见的生产故障是：开发环境可以打开 DOCX、XLSX、PPTX 或 PDF，部署后却白屏，控制台只留下一条 Worker 加载失败，或者 Network 中出现 WASM、字体、vendor 资源 404。

这类问题不要从"重装组件"开始。按照下面的顺序排查，通常能更快找到真正断点：

确认失败的是文件请求还是解析器运行时；
核对 Vite base 与生产访问路径；
确认 Worker/WASM 和主包来自同一版本；
根据鉴权方式选择 URL 或 File；
单独检查大 PDF 的 Range 与内存；
用真实生产基址完成四类文件回归。

1. 先在 Network 中把请求分成两类

打开浏览器 DevTools，过滤失败请求，先判断 404 属于哪一类。

第一类是业务文件本身，例如：

text 复制代码

/api/attachments/42
/files/contract.docx
/object-storage/signed-url

这类请求失败，优先检查登录态、签名时效、CORS、反向代理和文件权限。

第二类是解析器运行时，例如：

text 复制代码

/oa/file-viewer/pdf.worker.min.mjs
/oa/file-viewer/pptx.worker.js
/oa/file-viewer/*.wasm
/oa/file-viewer/fonts/*

这类请求失败，说明 Vue 组件已经运行，但按需资源没有正确发布。业务文件换多少次都不会解决。

2. Vite 子路径要同时影响入口和运行时

假设应用最终地址是：

text 复制代码

/oa/

Vite 配置应该使用同一个基址，并在构建时复制运行时资产：

ts 复制代码

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileViewerRenderers } from '@file-viewer/vite-plugin'

export default defineConfig({
  base: '/oa/',
  plugins: [
    vue(),
    fileViewerRenderers({ copyAssets: true }),
  ],
})

生产环境正确请求应以 /oa/file-viewer/ 开头。如果实际请求是 /file-viewer/，说明资源地址退回了域名根目录；如果请求路径正确但文件不存在，则检查构建产物与部署脚本。

可以先在产物目录中确认资源是否真的存在：

bash 复制代码

find dist -maxdepth 3 -type f | grep file-viewer

如果项目不使用 Vite，可以在构建阶段显式复制：

bash 复制代码

npx --no-install file-viewer-copy-assets ./public/file-viewer

静态资源统一部署到其他目录时，设置完整基址：

ts 复制代码

import { setDefaultFullAssetBaseUrl } from '@file-viewer/vue3-full'

setDefaultFullAssetBaseUrl('/static/file-viewer/')

3. 不要让主包和 Worker/WASM 跨版本拼装

文件预览运行时不是一组永久不变的静态文件。主包、Worker、WASM 和 vendor 之间可能共享消息结构、导出名称和资源约定。

一个常见故障过程是：

前端依赖从旧版本升级；
CI 重新构建了 JavaScript；
静态服务器沿用之前手工上传的 file-viewer/；
页面加载成功，命中特定格式后才失败。

修复方式不是继续补单个文件，而是让构建过程每次从当前依赖生成整套运行时，再与前端产物一起发布。

4. 鉴权接口不要盲目传 URL

公开 URL、同源 Cookie 接口、短期签名地址，可以直接交给预览组件。这样 PDF 等格式仍有机会使用缓存和 Range。

需要自定义 Header、解密或统一处理 401 时，让业务层先下载：

vue 复制代码

<script setup lang="ts">
import { ref } from 'vue'
import { FileViewer } from '@file-viewer/vue3-full'

const previewFile = ref<File>()
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 @click="openAttachment('42', '合同.docx')">
    预览合同
  </button>
  <p v-if="errorMessage">{{ errorMessage }}</p>
  <FileViewer v-if="previewFile" :file="previewFile" />
</template>

构造 File 时要保留真实扩展名。某些下载接口返回统一 MIME，只有 合同.docx 这个名称能稳定告诉路由层应该进入哪条解析链路。

5. 大 PDF 要单独检查 Range

fetch + Blob 通常需要完整下载，并在浏览器中保留完整二进制。对于大 PDF，这可能带来明显等待和内存峰值。

如果业务允许同源 URL，可以在 Network 中检查是否出现：

http 复制代码

Request Headers
Range: bytes=0-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 和 Range；
File 路径覆盖 401、下载中断、取消和快速切换；
断开公网，确认没有隐藏 CDN 依赖。

内容与性能

四类文件各准备一个真实脱敏样本；
验证内容，不只验证首屏；
记录浏览器版本、设备内存、文件大小、页数和峰值内存。

总结

"本地能开、上线白屏"通常不是 Vue 组件突然失效，而是输入、路径或运行时交付只完成了一半。

排查时按这个顺序最省时间：先区分文件请求与运行时请求，再核对 base，然后检查版本一致性，最后根据鉴权和文件大小选择 URL 或 File。

本次示例按 File Viewer v2.2.5 验证。把 Worker、WASM、字体和真实生产回归纳入交付后，文件预览才不再是只能在开发机上成立的一段代码。