免下载在线预览完整方案：图片、视频、音频、PDF

1. 为什么非要做“免下载”预览

1.1 常见的业务场景

如果你的项目里也有个在线媒体预览工具的需求，这篇文章应该能帮你少走不少弯路。我说的这个工具，指的是不用把文件下载到本地、直接在浏览器里看图片、视频、音频、PDF的一种服务。

网盘、企业OA、素材库、后台管理系统，几乎每个文件密集型的业务都会撞上这种场景：文件明明就在服务器上，用户却必须下载完才能确认内容。我自己接手过的项目里，有一个是公司内部的合同归档系统，几百M的PDF合同，业务同事每天要反复打开核对条款，每次都下载到本地，不仅占电脑空间，而且版本管理一乱，很容易看错文件。还有一个是电商素材库，运营要挑视频素材做投放，一天要预览上百个片子，下载再删除再下载，那个效率低到让人怀疑人生。

免下载预览解决的就是这个割裂感：图片在网页里直接看，视频点开就能播，音频即点即听，PDF像阅读器一样翻页。更重要的是，它可以加上权限控制、临时链接、访问记录和水印，文件不用落地到用户设备上，对敏感内容的安全管控也更友好。

这篇文章适合谁看？如果你是Web全栈开发者、前端工程师，或者正在规划文件类产品功能的产品和技术负责人，下面这套从后端接口到前端组件的完整方案，基本可以拿着直接用。

1.2 核心思路与方案选型

做在线预览，思路其实就三层：

• 前端负责“怎么看”，按文件类型选择对应的预览方式，图片用img，视频用video，音频用audio，PDF用pdf.js渲染。
• 后端负责“怎么给”，提供一个支持HTTP Range分片的流式预览接口，把文件内容按需吐给前端。
• 安全层负责“怎么防”，通过签名URL、有效期、权限校验、防盗链这些手段，确保只有有权限的人才能在限定时间内预览。

为什么强调这三个层面而不是塞一个现成的播放器插件？因为在线预览最大的一个坑，就是很多人以为前端加个video标签、iframe就能搞定所有事。真实项目里，文件在OSS或者内网存储上，你随便给个直链让前端去拉，会遇到跨域、防盗链、路径暴露、链接过期无法控制等一系列问题。所以我的建议是：统一走后端代理，由后端统一做鉴权、转发、缓存和日志，前端只拿到一个短时有效的预览地址。

另外，视频和音频的预览，本质上是一个流式传输问题，不是简单地抛给浏览器一个完整文件。用户点开视频后拖进度条，浏览器会发起Range请求，服务端必须支持206 Partial Content，否则视频播着播着就会卡在缓冲，甚至根本没法拖动。PDF预览也不是浏览器自带的插件都能搞定，浏览器内置阅读器自带下载按钮，很多场景下并不合适。这些都是实际开发中被反复踩到的点。

2. 图片、视频、音频、PDF的预览方案拆解

2.1 图片：原生标签也能踩坑

图片是所有类型里最“友好”的，因为 <img> 标签天生支持直接显示远端文件，不需要任何额外解析。但真正放到在线预览工具里，还是藏着不少问题。

第一是权限。如果文件是私有存储，前端拿到的是临时签名URL，那还好。但如果直接暴露OSS地址，别人拿到URL就能永久访问，这就等于把文件脱光了扔到公网上。所以我一般建议所有图片都走预览代理接口，由后端统一控制访问权限和过期时间。

第二是大图性能。一个几M甚至几十M的高清大图，直接往img标签一扔，图片确实能显示，但加载极慢，而且浏览器解码大图时会占掉大量内存。移动端更明显，用户打开页面直接卡死的情况我都碰到过。稳妥做法是生成缩略图或者动态裁剪图，预览时优先显示低配版本，用户要看原图再点开原图接口。

第三是EXIF方向问题。手机拍的竖版照片，很多都带EXIF旋转信息，如果服务器或者前端不解析，图片显示出来就是横的。用Canvas处理或者接入exif相关库可以解决，但注意别在缩略图上改原图方向，否则会影响原图展示。

第四是内存释放。如果用 URL.createObjectURL(blob) 生成的临时地址来预览，用完一定要调用 URL.revokeObjectURL 释放，否则标签页长时间运行会越来越卡，后台挂着几十个预览就会明显掉帧。

2.2 视频：Range请求才是关键

视频预览比图片麻烦一个数量级，核心就是流式播放。

浏览器里的 <video> 标签，本身会向服务端发起两次请求：第一次是探测请求，只看文件头信息，用来识别编码格式和时长；第二次才是真正拉数据。如果服务端在第一次请求时返回了整个文件，或者压根没处理Range头，视频就加载不了元数据，播放器会一直转圈或者黑屏。

我做一个内部培训视频库时踩过这个坑。最初后端直接把视频文件读进内存再整体返回，本地测试没毛病，一放到内网，几个同事同时打开就卡成幻灯片。后来查了Network面板，发现浏览器发的是 Range: bytes=0-，但服务端无视它返回了完整200响应，而且没有 Accept-Ranges，等于告诉浏览器“我没法分段给”。修复方式也直接：后端必须解析 Range 头，返回 206 Partial Content 和 Content-Range，视频才能拖进度条，才能实现按需加载。

编码兼容性也值得多说一句。市场占有率最高的依然是H.264编码的MP4文件，几乎全平台通吃。WebM格式也不错，但有些老一点的设备和软件兼容性欠佳。HEVC（H.265）压缩率高、画质好，但浏览器端的支持不够统一，有些系统需要额外装解码扩展，普通用户根本不知道去哪里弄。所以对上传的视频，我强烈建议做成自动转码，统一转成H.264 + AAC的MP4，不要和浏览器兼容性较劲。

如果视频很长，比如超过30分钟，还要考虑HLS（m3u8）方案，把视频切成小分片，按需加载。这种方案对直播和超长视频最友好，但实现成本高，前期MVP阶段可以先不做。

2.3 音频：流式加载与自动播放限制

音频和视频共用一套HTTP流式传输机制，<audio> 标签同样依赖Range请求。后端返回206，用户拖动播放进度条才顺畅，所以视频接口设计好之后，音频基本是复用同样一套逻辑。

音频预览有几个独立的点需要注意。

自动播放限制是绕不开的。浏览器为了用户体验，通常会阻止带声音的媒体自动播放。用户点开预览页，音乐没有立刻响起，往往是浏览器策略在拦截，不是代码写错了。如果确实要做自动播放入场音，可以先把音量设为0，再在用户点击页面后恢复音量，或者明确提示用户点击播放按钮。强制调用 play() 可能会返回一个被拒绝的Promise，记得用 catch 捕获，别让控制台飘红。

preload 属性根据场景设置。预览工具里，我一般建议 preload="metadata"，只加载音频头部信息，显示时长和格式，等用户点播放再真正拉数据。一口气把整段音频拉下来，对网盘预览这种高并发场景是灾难。

音频还有一个扩展功能：波形预览。用Web Audio API解码音频数据后，可以画出波形图，方便用户快速定位到人声或鼓点。但注意解码大音频文件非常吃内存，几十M的WAV文件解码时会有明显卡顿，建议只解码一小段采样来做展示，或者后端提前生成波形数据再给前端。

2.4 PDF：别迷信浏览器内置预览

PDF比较复杂，因为它是“文档”而不是“媒体”，浏览器处理它的方式还在不断变化。

最简单的实现是用iframe或者新标签页直接打开PDF地址，让浏览器内置阅读器去展示。Chrome、Edge、Firefox都内置了PDF查看器，而且体验其实还不错。但这种方案有三个致命问题：

• 内置阅读器自带下载、打印按钮，用户一键就把文件存到本地了，这叫哪门子免下载。
• 如果预览地址跨域，部分浏览器内置阅读器不会正常加载。
• 无法统计用户的阅读行为，比如看了第几页、看了多久，这对很多后台系统来说是个重要数据。

我实际项目里最终选了pdf.js。Mozilla出品的这个开源库，可以在网页里把PDF渲染成Canvas，页面怎么展示完全由前端控制。我们可以去掉下载按钮、加上页码、做按页懒加载、加水印、统计阅读时长，甚至可以给某些页面打上“内部文件禁止外发”的透明水印。

pdf.js集成时最需要注意的是worker配置。不配置worker的时候，JS会在主线程里做解析，稍微大一点的PDF会直接把界面卡死。正确做法是把 pdf.worker.min.js 单独引进，并显式指定workerSrc路径。如果PDF地址是跨域的，worker加载和fetch文件也会遇到跨域问题，后续章节我会细说。

2.5 方案选型对比

这个表可以当作技术选型时的快速对照。大部分业务场景，图片和PDF应该优先做，视频和音频次之，因为前两者开发成本低、使用频率高。

3. 实操实现：从后端接口到前端组件

3.1 后端：设计一个支持Range的预览代理接口

这里我拿Python FastAPI举例，其他语言思路完全一致。

先定义接口：GET /api/v1/preview?file_id=xxx&expire=xxx&sign=xxx。file_id是文件唯一标识，expire是链接过期时间戳，sign是签名，防止接口被随便调用。文件名和路径不应该出现在URL里，全部藏在后台文件表中。

核心逻辑分四步：

1. 校验签名和过期时间。
2. 根据file_id查出文件的存储路径、文件名、MIME类型。
3. 解析 Range 请求头，决定返回200还是206。
4. 用文件分片读取的方式响应，而不是一次性读入内存。

关键代码大致长这样：

python复制from fastapi import FastAPI, Request, Response
from fastapi.responses import StreamingResponse
import os, hashlib, hmac

app = FastAPI()

# 简化示例，真实场景请从数据库读取文件元信息
FILE_META = {
    "10001": {"path": "/data/files/10001.mp4", "mime": "video/mp4"}
}

def check_sign(file_id: str, expire: str, sign: str) -> bool:
    secret = b"your-secret-key"
    msg = f"{file_id}:{expire}".encode()
    expect = hmac.new(secret, msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expect, sign)

@app.get("/api/v1/preview")
async def preview(file_id: str, expire: str, sign: str, request: Request):
    if int(expire) < int(time.time()):
        return Response(status_code=403, content="link expired")
    if not check_sign(file_id, expire, sign):
        return Response(status_code=403, content="invalid sign")

    meta = FILE_META.get(file_id)
    if not meta:
        return Response(status_code=404, content="file not found")

    file_path = meta["path"]
    file_size = os.path.getsize(file_path)
    mime = meta["mime"]

    # 读取 Range 头
    range_header = request.headers.get("range")
    headers = {
        "Content-Type": mime,
        "Accept-Ranges": "bytes",
        "Content-Disposition": "inline",
        "X-Content-Type-Options": "nosniff",
    }

    # 没有Range头，从0开始返回
    if not range_header:
        headers["Content-Length"] = str(file_size)
        return StreamingResponse(open(file_path, "rb"), status_code=200, headers=headers)

    # 解析 Range: bytes=start-end
    # 简单实现只处理单段Range，多段Range在预览场景可以忽略
    try:
        range_str = range_header.replace("bytes=", "")
        start_str, end_str = range_str.split("-", 1)
        start = int(start_str)
        end = int(end_str) if end_str else file_size - 1
    except Exception:
        return Response(status_code=416, content="invalid range")

    if start >= file_size or end >= file_size or start > end:
        return Response(status_code=416, content="invalid range")

    length = end - start + 1
    headers["Content-Range"] = f"bytes {start}-{end}/{file_size}"
    headers["Content-Length"] = str(length)

    def file_chunk():
        with open(file_path, "rb") as f:
            f.seek(start)
            remaining = length
            while remaining > 0:
                chunk = f.read(min(1024 * 1024, remaining))
                if not chunk:
                    break
                remaining -= len(chunk)
                yield chunk

    return StreamingResponse(file_chunk(), status_code=206, headers=headers)

这段代码的核心价值在于：让前端播放器可以自由拖进度条、按需加载，同时不会因为用户取消加载而让后端白白读取完整文件。StreamingResponse 配合生成器逐块读取，内存占用很低，几十个用户同时预览也不会把服务器打爆。

Content-Disposition: inline 也很重要，它告诉浏览器这个响应是“内嵌展示”而不是“附件下载”。如果设置成attachment，浏览器会直接弹下载框，免下载预览就失败了。

X-Content-Type-Options: nosniff 是安全头，防止浏览器对返回内容做MIME猜测，避免存储型XSS风险。特别是当文件名是HTML或者SVG时，没有这个头，浏览器可能会把文件当页面渲染，这是非常危险的事情。

3.2 后端：用Nginx内部重定向减少服务器压力

如果文件量很大，预览接口经由应用服务器读取磁盘再转发给前端，应用服务器CPU和内存都会吃紧。一个更优的做法是：应用服务器只负责鉴权和文件定位，真正的文件读取交给Nginx去做。

Nginx有一个 X-Accel-Redirect 机制，应用服务器返回一个内部重定向地址，Nginx会接管后续的文件发送。整个过程外部用户无感知，文件读取不占用应用服务器的进程资源。

Nginx配置段示例：

nginx复制location /internal_file/ {
    internal;
    alias /data/files/;
}

后端接口的鉴权逻辑不变，只是最后不再用 StreamingResponse 返回文件，而是设置响应头，由Nginx接管：

python复制@app.get("/api/v1/preview")
async def preview(file_id: str, expire: str, sign: str, request: Request):
    # ... 鉴权逻辑同上 ...
    meta = FILE_META.get(file_id)
    headers = {
        "X-Accel-Redirect": f"/internal_file/{meta['filename']}",
        "Content-Type": meta["mime"],
        "Content-Disposition": "inline",
    }
    return Response(status_code=200, headers=headers)

注意 internal 目录不能让外部直接访问，只能由Nginx内部重定向。否则绕过鉴权直接访问文件地址，一切防护都白搭。

如果你的文件放在对象存储里，那更简单，后端鉴权通过后，生成一个短期有效的对象存储预签名URL，让前端保存到那个跳转地址，不需要Nginx也完全没问题。但要注意加上有效期，以及设置对象存储的 Content-Disposition: inline。

3.3 前端：按类型分发预览组件

后端接口就绪后，前端要做的事就三件：判断文件类型、调预览接口、渲染到对应容器里。

判断类型时不要只看扩展名，要用后端返回的MIME类型为主，扩展名兜底。因为有些文件明明是个图片，扩展名写错了，或者后台存的时候没写对。下面是一个精简的示例：

javascript复制function getPreviewType(mime, filename) {
  if (mime.startsWith("image/")) return "image";
  if (mime.startsWith("video/")) return "video";
  if (mime.startsWith("audio/")) return "audio";
  if (mime === "application/pdf") return "pdf";
  const ext = filename.split(".").pop().toLowerCase();
  if (["jpg", "jpeg", "png", "gif", "webp"].includes(ext)) return "image";
  if (["mp4", "webm", "mov"].includes(ext)) return "video";
  if (["mp3", "wav", "ogg", "m4a"].includes(ext)) return "audio";
  if (ext === "pdf") return "pdf";
  return "unsupported";
}

拿到类型后，渲染端就很直接：

javascript复制function renderPreview(container, type, url, fileName) {
  container.innerHTML = "";
  switch (type) {
    case "image": {
      const img = document.createElement("img");
      img.src = url;
      img.alt = fileName;
      container.appendChild(img);
      break;
    }
    case "video": {
      const video = document.createElement("video");
      video.src = url;
      video.controls = true;
      video.style.width = "100%";
      container.appendChild(video);
      break;
    }
    case "audio": {
      const audio = document.createElement("audio");
      audio.src = url;
      audio.controls = true;
      audio.preload = "metadata";
      container.appendChild(audio);
      break;
    }
    case "pdf": {
      // 交给 pdf.js 渲染函数
      renderPdfWithPdfjs(container, url);
      break;
    }
    default: {
      container.textContent = "该文件类型暂不支持在线预览";
    }
  }
}

这里有一个细节：视频和音频元素，src 最好保持后端返回的代理接口URL，而不要去下载Blob再播放。原因很简单，直接用URL播放时，浏览器会按需请求文件的分片，服务端Range机制才能发挥作用。如果先用 fetch 把整个文件拉到Blob再播放，虽然名义上也是“流”，但实际上文件已经完整下载到用户内存或缓存里了，和下载文件没什么本质区别。

3.4 前端：PDF.js集成流程

PDF.js集成是预览工具里最值得写一段的模块。先说版本，建议直接用最新稳定版，CDN或者npm安装都可以。核心步骤是：

1. 引入PDF.js主体库和worker。
2. 设置workerSrc。
3. 加载PDF文档，获取总页数。
4. 按需渲染每一页为Canvas。

一个最小可用的渲染函数：

javascript复制let pdfDoc = null;
let currentPage = 1;

async function renderPdfWithPdfjs(container, url) {
  const script = document.createElement("script");
  script.src = "/vendor/pdf.min.js";
  await new Promise((resolve) => (script.onload = resolve));
  document.head.appendChild(script);

  pdfjsLib.GlobalWorkerOptions.workerSrc = "/vendor/pdf.worker.min.js";

  const loadingTask = pdfjsLib.getDocument(url);
  pdfDoc = await loadingTask.promise;

  const pageInfo = document.createElement("div");
  pageInfo.textContent = `共 ${pdfDoc.numPages} 页`;
  container.appendChild(pageInfo);

  const canvasWrap = document.createElement("div");
  canvasWrap.id = "pdf-canvas-wrap";
  container.appendChild(canvasWrap);

  await renderPage(currentPage);
}

async function renderPage(pageNum) {
  const page = await pdfDoc.getPage(pageNum);
  const viewport = page.getViewport({ scale: 1.5 });
  const canvas = document.createElement("canvas");
  canvas.width = viewport.width;
  canvas.height = viewport.height;
  const ctx = canvas.getContext("2d");

  const renderContext = {
    canvasContext: ctx,
    viewport: viewport,
  };
  await page.render(renderContext).promise;

  const wrap = document.getElementById("pdf-canvas-wrap");
  wrap.innerHTML = "";
  wrap.appendChild(canvas);
}

这个代码能跑，但生产环境还要补三块：

• 上一页/下一页按钮，以及页码跳转。
• 按页懒加载，不要一次渲染所有页。
• 异常处理，尤其是PDF损坏、密码保护的情况，要给出明确的错误提示。

还要注意嵌入文本层。如果只是展示图片化的PDF，用户没法选中文字做复制和搜索，很多场景下体验不够。pdf.js提供了 textLayer 模式，可以在Canvas上方覆盖一层透明文字层，让搜索、复制对用户可见。但注意，如果文件是机密的，不想让用户复制内容，那就别开文本层，只渲染Canvas，这样内容就像一张图。

3.5 权限控制与防盗链：阻止“另存为”的前后端配合

先泼一盆冷水：前端再怎么做，都不可能100%阻止用户保存文件。只要用户的浏览器能看到这个内容，用户就一定可以通过开发者工具、抓包等办法拿到原始文件。在线预览的所谓“免下载”，真正的意义是：不让正常用户因为图方便而下载到本地，同时让文件的访问权限、有效期、访问记录都在你的掌控之中。

前端能做的体验防护：

• controlsList="nodownload" 可以隐藏视频播放器的下载按钮。
• 监听浏览器上下文菜单事件，禁用右键“图片另存为”。
• PDF预览用pdf.js渲染，彻底去掉内置阅读器的下载按钮。
• 图片预览加水印，看到内容的同时带走身份标识。

但这些都只是UI层面的限制，不是安全措施。真正的安全控制必须在后端做：

• 签名URL有效期。给预览链接加过期时间，比如默认10分钟，超时自动失效。不要让链接长期有效，否则用户转发出去就是永久漏洞。
• 权限校验。预览接口要和业务权限体系打通，用户没有文件所属模块的权限，接口直接403。
• 限流。短时间内同一IP、同一用户访问预览接口次数过多，触发报警或临时封禁，防止别人用脚本批量拉取文件。
• 水印。敏感场景下，在图片或PDF上动态叠加当前用户ID或昵称，出了问题可以追溯是谁泄露的。

签名算法我用的是HMAC-SHA256，前端的预览地址长这样：

code复制/api/v1/preview?file_id=10001&expire=1730000000&sign=xxxxx

前端拿到这个地址后直接给img、video、audio或pdf.js用，不需要知道文件真实路径，更拿不到永久链接。

4. 性能优化与安全防护实录

4.1 大文件与弱网环境的加载策略

在线预览工具上线后，用户第一个骂的就是慢。尤其是视频、大图、厚PDF，网络稍差就转圈。

先说视频。预览场景下，用户往往只会看前几十秒，不需要把整部片子都加载完。Range机制本身已经解决了按需加载的问题，但如果你发现用户拖进度条还是很卡，第一件事是看服务端响应是否有 206 Partial Content。如果服务端返回的是200，那就是Range没生效，用户每次拖动都要从0开始重新下载，卡是必然的。

其次是码率。同一个视频，给办公室固定网络预览可以用1080p，给移动端弱网用户，720p甚至480p更流畅。生产环境可以在上传时用ffmpeg转出多份不同码率的副本，然后根据用户当前网络状况动态切换。这个工程量大一些，MVP阶段可以不搞，但至少要知道这个方向。

音频比较简单，preload="metadata" 可以减少首屏流量。用户不点击播放，浏览器只下载少量的文件头信息，而不是整首音频。

图片方面，缩略图是立竿见影的优化。后端生成一套小尺寸版，比如宽度不超过1200px，用WebP格式输出，画质几乎无损但体积小一半以上。预览页先展示小图，用户点击“查看原图”再走原图接口。这样列表页和详情页的加载速度都能提升一个档次。

PDF方面，pdf.js支持按页渲染，但我建议再加一层后端优化：对PDF生成预览用的图片缓存。也就是第一次打开时，把某一页渲染成图片放到缓存里，下次用户访问直接读图片，不用重新解析PDF。对几十页的大合同，这个优化能显著降低服务端CPU压力。

4.2 前端渲染与内存管理

浏览器虽然不像原生App那么容易被内存管理坑到，但预览大文件时问题依然不少。

URL.createObjectURL 生成的Blob地址，占用的内存只有当页面关闭或者手动调用 revokeObjectURL 时才释放。如果用户在工具里连续预览了20个大视频，每次都把整个文件拉成Blob再播放，浏览器的内存曲线会直线上升，最后页面崩溃也不是不可能。

所以我的建议是：能直连预览地址就不要转Blob，只有需要做本地编辑、裁剪、加水印这类操作时，才用Blob方式加载文件，而且操作完成后必须及时 revokeObjectURL。

Canvas也有内存天花板。pdf.js渲染大尺寸页面时，Canvas的像素宽度可能超出设备限制，有些设备在超过4096像素时会出现空白甚至报错。解决方案是限制渲染的 viewport.scale，不要盲目追求高清，预览场景1.5倍到2倍就够用。图片预览同理，大原图在Canvas里重新绘制前，先检查目标尺寸，不要直接拿原始尺寸做离屏缓冲。

前端还有一个隐形开销：未使用的监听器。预览组件在切换文件或者销毁时，要移除事件监听器、暂停视频播放、释放Canvas上下文，否则后台标签页会一直占用资源。

4.3 安全加固：防绕过下载与防带宽盗刷

这个环节容易被忽略，但预览工具一旦上线，就会成为某些人眼中的免费CDN。

典型的攻击方式有两种。一种是把预览链接直接发到公网论坛，引来大量访问，源站带宽被打满，运营成本飙升。另一种是写脚本遍历file_id，批量下载所有文件，直接把你的存储库搬空。

对应策略：

• 预览链接必须短有效。短到多少？我自己的习惯是图片和PDF用15分钟，视频和音频用1小时，因为大文件预览过程中可能要反复拉分片，过期太短反而会导致播放中断。核心文件要更短。
• 同文件重复访问时，签名要在后端校验，同时配合缓存策略。如果是允许缓存的公共文件，可以设置较长的 Cache-Control，让CDN或浏览器缓存减轻源站压力。
• 对file_id生成方式做好随机化，不要用自增数字，否则别人能枚举遍历。使用UUID或者基于业务键哈希后的ID。
• 接口做限流。同一用户或同一IP每分钟超过一定次数，就拒绝服务，并记录审计日志。这个限流要覆盖到“即使签名正确”的请求，因为攻击者可能盗用了一个合法签名链接。
• 存储桶或文件目录的私有权限不能降级。代理接口是唯一出口，底层存储始终设为私有。

再提醒一次：不要试图用“禁止右键”之类的前端手段来防下载，那只会气到正常用户，防不住任何有技术能力的人。安全的重心永远在后端。

5. 常见问题与排查技巧

5.1 问题速查表

5.2 我实际踩过的几个坑

第一个印象深刻的坑，是只做了前端权限控制，没做后端校验。当时项目赶上线，前端通过隐藏下载按钮、禁用右键来“保护”视频，结果上线第二天就被运营同事用开发者工具把地址扒了出来，直接传到公司群里，还被问“为什么这个链接能直接下载”。从那以后，我的原则就一句话：前端做的所有限制都是体验设计，后端权限才是安全底线。

第二个坑是Range透传。之前用Java写过一个版本，文件直接用 FileInputStream 读出来返回，所有文件都是200，本地测试一切正常，放到测试环境别人拖动视频进度条时，进度条会跳回开头。查了一整个下午，最后抓包看到 Accept-Ranges 没返回，才意识到问题。后来我养成了习惯：预览接口做完了，先打开Network面板，点一下视频时间轴看看有没有 206，再谈其他。

第三个坑是pdf.js的workerSrc。有段时间把pdf.js库放到了CDN，但页面和CDN域名不一致，worker加载被跨域策略拦了，PDF解析一直失败。那时候我才理解为什么pdf.js文档特别强调worker的跨域配置，后来统一用同域部署，或者给静态资源加上正确的跨域响应头，问题才解决。

第四个坑让我印象最深，是签名URL的缓存策略。我给图片生成了带过期时间的签名地址，结果有些用户反馈“预览黑屏”，排查后发现代理服务器把签名URL当成普通静态资源缓存了，过期之后的请求从未过期的缓存里取数据，导致签名校验通过但文件不对。最后在动态响应里显式加上 Cache-Control: no-store，并对静态文件域名和动态预览域名做了分离，才算彻底解决。

其实看下来，在线预览的坑大多是同一个根源：把动态内容当成静态文件处理了。预览接口是带鉴权、带时效、带日志的动态请求，不能简单套用静态资源的缓存策略，也不能把原文件地址直接暴露给前端。

6. 给同样想做的朋友几句掏心窝的话

这个工具我前前后后做了三四个版本，从最早的简单iframe方案，到后来完整的后端代理+pdf.js+转码方案，最大的体会是：在线预览工具的根本不是播放器选得有多花哨，而是后端接口写得够不够扎实。Range支持、签名校验、过期时间、权限控制、缓存策略，这些基础能力做扎实了，前端换什么播放器都顺手。

如果你现在正准备在项目里做在线预览，而不是已经有了一套复杂系统，我的建议是不要一上来就追求全格式通用。先把图片和PDF做扎实，这两个类型开发成本低、使用频率高，能解决大部分业务问题。视频预览第二轮再做，音频可以复用视频的接口方案。先让业务跑起来，再逐步补齐转码、多码率、水印这些进阶功能。

对于大文件、高清视频这类场景，尽早考虑转码和对象存储预签名URL方案。自己从零写一个能扛住高并发的流媒体服务，不是不能做，但成本远超想象。能用现成的技术组合解决，就尽量别重复造轮子。

最后再分享一个小技巧：预览服务上线前，一定要找几个人在真实的弱网环境里测试。办公室Wi-Fi下一切正常不算数，4G信号弱、电梯里加载、用户开了一堆后台应用时，还能不能流畅预览，才是这个工具真正见真章的地方。我的经验是，图片先加载缩略图、视频用Range分片、PDF按页懒加载，这三板斧下去，弱网表现立刻改善大半。