别让用户先下载再打开：vibe 项目的文件预览实战

先说判断：预览不是“顺手加个功能”，而是决定用户留不留下的第一道门

你的产品里一定有文件：用户上传的 PDF 合同、图片、视频、表格、代码、设计稿。用户点开一个文件时，发生什么？很多 vibe 项目的答案是：浏览器开始下载。用户等下载完成，再找到文件，再用别的软件打开，再回到你的产品。这个过程里，每多一步就流失一批人，尤其是在手机上。

我的判断先摆出来：文件预览不是锦上添花，而是文件类产品的第一道门。用户点开文件的那一刻，心里只有一个问题：“这是我要找的东西吗？”预览的作用就是用最快的速度回答这个问题：三秒内看到内容，确认无误，再决定要不要下载、编辑、分享。回答得越快，用户留下的概率越高；回答得越慢，用户越觉得你的产品“不好用”，哪怕你的其他功能都很好。

这篇文章讲的就是怎么把文件预览做对：按文件类型选渲染方式、PDF 和 Office 各自的取舍、图片和视频的坑、安全边界、移动端、性能，最后是一份落地清单。不讲大而全的理论，只讲一个一人团队今天就能动手的做法。

以下例子里出现的产品“方格文库”与人物、数字均为虚构，仅用于说明写法；方法本身是通用的。

先定原则：预览的第一使命是“确认”，不是“编辑”

动手之前，先把预览的定位定下来：预览是用来“确认内容”的，不是用来“处理内容”的。用户点开预览，想确认的是：这是不是我要的那份文件、内容对不对、版本新不新。编辑、批注、转换格式，那是下一步的事。定位定错了，预览就会越做越重：又想在线编辑，又想加批注，又想转格式，最后哪样都没做好。

基于这个定位，预览设计有三条铁律。第一，首屏三秒内必须看到内容。超过三秒还没渲染出来，用户就会认为“打不开”，转而去下载。三秒是上限，不是目标；能一秒看到，就别拖到三秒。第二，永远保留“下载原文件”的出口。预览是快捷方式，不是唯一通道；再好的预览也不能替代原文件，下载按钮要一直可见。第三，预览失败时要体面地降级：渲染不出来，就显示文件信息（名称、大小、类型、上传时间）加一个明确的下载按钮，而不是一片空白或者一个看不懂的错误码。

按类型选渲染方式：一张对照表就够了

不同类型的文件，预览方式完全不同。先给一张对照表，再逐个讲取舍。

图片是最简单的：浏览器原生就能显示 JPEG、PNG、WebP、GIF、AVIF，基本不用额外工作。但有两个坑。第一是 HEIC：苹果设备拍出来的照片默认是 HEIC 格式，浏览器打不开，必须在服务端转码成 JPEG 或者在前端用解码库处理，否则 iPhone 用户上传的照片自己都看不到。第二是 EXIF 方向：手机拍的照片带方向信息，不处理的话会出现“横过来的照片”，处理方法是读取 EXIF 按方向旋转，或者在生成缩略图时就把方向修正掉。

PDF 是第二常见的类型，有三条路线。第一条是浏览器原生：现代浏览器内置 PDF 阅读器，用一个 iframe 或者 embed 标签就能看，零成本，缺点是样式和功能受浏览器控制，想加水印、禁下载、自定义工具栏都做不到。第二条是 pdf.js：Mozilla 的开源库，把 PDF 渲染成 Canvas，可以完全控制界面、做分页加载、加自定义水印，缺点是需要自己维护，大文件首次加载慢。第三条是服务端转图片：把 PDF 每一页转成图片再下发，优点是显示效果完全可控、天然防复制，缺点是存储和转换成本高。我的建议是：先用浏览器原生方案上线，跑起来之后再按需升级到 pdf.js；服务端转图片只用在“必须防下载”的场景，别一上来就选最重的方案。

视频和音频的关键是“流式”而不是“整包下载”。视频要用支持分段请求（Range 请求）的托管方式，让用户点开就能看开头，不用等整个文件下完；同时准备一张封面图（poster），点开之前先看到画面，而不是一片黑。音频同理，先给波形图或者时长信息，再流式播放。转码是另一个现实问题：用户上传的视频格式五花八门，统一转成 H.264 + AAC 的 MP4 是最稳妥的做法，移动端兼容性最好。

Office 文档（Word、Excel、PPT）是最麻烦的一类，因为浏览器打不开。常见的有三条路线：第一，接微软或者谷歌的在线查看器，把文件 URL 交给它们渲染，优点是零开发、效果好，缺点是文件要经过第三方服务器，涉及隐私和合规问题，内部文件、合同、财务数据不能这么干；第二，服务端用 LibreOffice 转成 PDF 再预览，优点是文件不出自己的服务器，缺点是转换要花时间、复杂排版可能走样；第三，只做“元信息预览”：显示文档标题、页数、表格行数、上传者，再加下载按钮，承认“这个类型在线看不了”，但把信息给全。我的建议是：公开资料可以用在线查看器，内部文件走 LibreOffice 转 PDF，实在转不了的就老老实实显示元信息加下载，别硬撑。

代码和纯文本是最容易被忽视的一类，也是最好做的一类：按语言做语法高亮、显示行号、支持按行定位，再加一个“复制”按钮。对开发者用户来说，一个带行号和高亮的代码预览，比下载下来用编辑器打开快得多。压缩包（zip、tar）则不要尝试在线解压预览全文：显示压缩包里的文件清单、每个文件的大小，再让用户单独下载其中某一个，这就够了。

安全边界：预览是离用户上传内容最近的地方

预览功能离用户上传的内容最近，安全边界必须先想清楚。第一条是内容类型校验：只看文件头（magic number）判断类型，不看扩展名。一个把扩展名改成 .jpg 的可执行文件，文件头会出卖它；只信扩展名的系统，会把它当成图片原样输出。第二条是沙箱隔离：预览内容要放在独立的 iframe 沙箱里跑，禁止脚本执行，禁止访问父页面；PDF 和 HTML 类型的文件尤其要小心——一个精心构造的 HTML 文件可以在预览里执行脚本，盗走用户的登录态。

第三条是访问控制：预览链接不能是“知道地址就能看”的公开地址。要用带签名的短期链接，过期作废；权限校验要在服务端做，预览接口和下载接口用同一套权限逻辑，别出现“下载要登录、预览不用登录”的裂缝。第四条是病毒扫描：用户上传的文件在进入预览之前，最好先过一遍扫描；扫描可以是异步的，但没扫完的文件不要进预览队列，至少要在预览页上标注“未完成安全检查”。

还有一条容易被忽视的：预览产生的派生文件（缩略图、转码后的视频、转出来的 PDF 图片）同样要走权限控制和过期清理。很多人只给原文件加了权限，缩略图却放在公开路径下，等于给原文件留了一扇没锁的后门。

性能：预览慢，用户会认为是“打不开”

预览的性能目标只有一个：点开之后尽快看到内容。实现上有四招。第一招是缩略图先行：列表页只加载缩略图，点开详情才加载原文件或者高清预览；缩略图在上传时生成，而不是在预览时现算。第二招是懒加载和分页：PDF 只渲染当前页和前后一页，视频只加载当前播放位置附近的分段，长图片先给低分辨率版本、再逐步清晰。第三招是缓存：同一个文件的预览结果要缓存起来，第二个用户点开时直接命中，不用重新转码、重新渲染。

第四招是分级降级：网络慢的时候，先给低分辨率图片、文字版摘要或者文件元信息，让用户先确认“这是我要的文件”，高清内容随后补上。降级不是偷工减料，而是把“确认”这个核心使命放在最高优先级。衡量预览性能的指标也很直接：从点击到首屏内容出现的时间。把这个时间记下来，每周看一次趋势，比任何主观感受都可靠。

这里要和文件存储与 CDN 的话题划清界：那篇指南讲的是文件存在哪里、怎么传、怎么分发；这篇讲的是文件到了用户眼前之后怎么“被看到”。存储解决的是“有”，预览解决的是“看得见”。两者都做好了，文件功能才算完整。

移动端：预览体验的差距主要在手机上拉开

桌面端预览做得再好，移动端跟不上，差距立刻就出来了。移动端有三件事要单独处理。第一，触摸手势：PDF 要支持滑动翻页和双指缩放，图片要支持双指缩放和滑动切换，视频要支持全屏和进度拖动。这些手势在桌面端是鼠标滚轮和点击，在移动端缺一个都会被用户立刻感知到。

第二，流量和电量：移动端不要一上来就加载高清原图，先给压缩过的版本，用户主动要求再加载高清；视频默认不要自动播放，点一下再播。第三，系统级分享和打开方式：移动端用户经常想把文件“用别的 App 打开”或者“分享给同事”，预览页上要留好“用其他应用打开”和“分享”两个出口，别把用户锁在自己的预览器里。

还有一个细节：手机浏览器对很多文件类型的支持比桌面差，HEIC 照片、某些 Office 格式、特殊编码的文本文件，在手机上更容易打不开。移动端预览失败时的降级文案要格外清楚：告诉用户“这个文件在当前设备上无法直接预览”，再给下载按钮，而不是让用户对着空白页发呆。

无障碍和细节：预览做得好不好，看边缘情况

预览的无障碍常常被遗忘，但它决定了产品能不能被所有人用。图片预览要有替代文本，至少是文件名和基本描述；PDF 预览要保留文本层，让屏幕阅读器能读到内容，而不是只看到一张图片；所有操作按钮（放大、缩小、翻页、下载）都要能用键盘操作，焦点顺序要合理。

还有一些细节，平时注意不到，出问题时很要命。文件名太长要截断显示，但悬停要能看到全名；文件大小要换算成人类可读的单位，别显示一串字节数；上传时间要显示相对时间（“3 天前”）加绝对时间；多页 PDF 要显示“第 3 / 12 页”，让用户知道自己在哪。版本管理也值得做：如果一个文件被覆盖上传，预览页要能看到历史版本，至少要标注“这是最新版本”或者“你正在看的是旧版本”。

最后是“空结果”的处理：如果一个文件损坏了、转码失败了、或者类型实在不支持预览，页面要说清楚三件事：发生了什么、为什么、用户现在能做什么（下载原文件、联系上传者、重新上传）。错误信息写得越具体，用户越不会觉得是你的产品坏了。

从 0 到 1：先上哪三种类型

如果你的产品今天还没有文件预览，别想着一次把所有类型都做完。按这个顺序上，每一步都能立刻看到效果。第一步先做图片：浏览器原生支持，工作量最小，覆盖的用户场景却最广。上传时生成缩略图，列表页只加载缩略图，点开看原图，这一步做完，大部分用户的“确认”需求就已经满足了。

第二步做 PDF：先用浏览器原生阅读器，不用自己维护渲染库。PDF 是合同、简历、报告、发票最常见的格式，覆盖了文件类产品的第二大场景。这一步的关键不是渲染得多精美，而是“点开就能看”，再加上页码显示和下载按钮，就已经比“先下载再打开”好一个数量级。

第三步做视频封面加流式播放：先给视频生成一张封面图，再用支持分段请求的方式托管。封面图的作用被很多人低估：用户在列表里看到封面，就能判断这是不是要找的视频，根本不用点开。流式播放则是为了让用户点开之后不用等整个文件下完。这三步做完，文件预览的核心体验就已经立住了。

Office 转换、HEIC 转码、代码高亮、压缩包清单，这些都可以往后放。它们重要，但不是第一批。判断“先上什么”的标准只有一个：哪种类型的文件在你的产品里被打开得最频繁，就先做哪种。打开频率的数据可以从现有的下载日志里直接统计，不用猜。按频率排序做预览，投入产出比最高，也最不容易返工。等到前三步都稳定运行了，再回过头来补 Office 转换和 HEIC 转码，那时你已经有了真实的使用数据，知道该把力气花在哪里。

落地清单：按这个顺序做

第一，先把“下载原文件”这个出口做扎实，再谈预览。预览是加分项，下载是底线。第二，按文件类型一张表定好渲染方式：图片原生显示、PDF 先走浏览器原生、视频音频走流式、Office 先做元信息加下载，再按需升级。第三，安全先行：文件头校验、沙箱 iframe、签名短期链接、派生文件同样设权限，这四件事在预览上线之前就要有。

第四，缩略图在上传时生成，列表页只加载缩略图。第五，移动端单独验收一遍：手势、流量、分享出口、降级文案，缺一不可。第六，记下“点击到首屏内容出现”的时间，每周看一次。第七，准备好失败时的体面降级：文件信息加下载按钮，永远比空白页强。

最后回到开头那句话：预览的第一使命是让用户三秒内确认“这是我要的文件”。所有选型、所有优化，都服务于这一个目标。目标定了，取舍就清楚了：能让用户更快确认的，就做；让用户更慢确认的，再高级也不做。