企业官网建设流程全解析

做 uni-app 项目时，几乎每个涉及“资料下载”“合同查看”“报表查阅”的模块，都会遇到同一个需求：用户点一下文件名，直接把内容打开看，不要跳出应用，也不要让用户先下一份文件到本地再自己找。需求听起来简单，实现起来却没有一套通用做法——H5 端能做的事，App 端不一定能，App 端能用的 API，在小程序端又会被文件体积、域名白名单、临时文件生命周期卡住。我前后在两个项目里做过文件在线预览，第一版写了两天，上线后接连遇到“iOS 打开白屏”“中文名直接报错”“小程序提示文件类型不支持”一类的问题，第二次重构才把逻辑理顺。这篇就把我在 uni-app 文件在线预览上的完整思路、分端实现、踩过的问题和最终封装方式都写出来，适合正在做跨端项目、刚接触 uni-app、或者已经写完但被兼容性折磨的同行参考。核心关键词是跨平台文件在线预览、uni.openDocument、临时文件路径、分端降级。

1. 三端能力矩阵：先看清 uni-app 文件预览的真实边界

1.1 H5、小程序、App 三端的原生能力差异

很多人做这个需求时的第一反应是：uni-app 不是有uni.openDocument吗？调一下不就完事了。这套想法在 App 端基本成立，在另外两端就会立刻失效。我建议在动手之前，先把三端各自真正能给到的能力列清楚，这决定了后面所有架构设计。

App 端能拿到最完整的能力，因为它本身跑在系统之上，可以直接调用系统的文件预览组件。uni.openDocument在 App 端支持的文件类型最全，doc、docx、xls、xlsx、ppt、pptx、pdf 都在覆盖范围内，甚至部分版本还支持 txt。它本质上会把文件交给系统注册的阅读器打开，用户看到的是系统级的预览界面。

小程序端有一半能力，uni.openDocument同样可用，但前置条件是你必须先用uni.downloadFile把文件下载到本地临时路径。而且小程序对文件体积有硬性限制，这个上限在不同平台、不同基础库版本上还会变化，我遇到过大版本升级后限制放开的，也遇到过老版本卡在十几兆的。所以小程序端的设计必须以“假设文件可能很大”为前提来做降级。

H5 端最容易被误判。uni.openDocument在 H5 端是空实现，调了不报错但也没反应——这个情况我在第一次接入时就让测试同事给坑了一回。浏览器里能做文件预览的只有 iframe 嵌入、浏览器原生渲染能力（PDF、图片、视频），以及你自己引入的渲染库。

提示：三端能力差异会随 uni-app 版本、各平台基础库版本滚动变化，动手前务必以官方文档当前版本为准，不要照抄两年前博客里的参数表。

1.2 一张表看清每条路径的代价

我习惯在动手前画一张决策表，把每种文件类型在三端分别该走哪条路径写死。这张表后面会直接变成代码里的判断逻辑：

这张表里最值得注意的是 H5 端的 Office 文档。浏览器本身不具备解析 Office 格式的能力，也没有官方提供的渲染接口。所以 H5 端要预览 Word、Excel、PPT，只有两条路：一是让后端转成 PDF 再给前端，二是接入第三方的文档转换服务，把文件转成可嵌入的页面地址。前者可控性最高，后者上线快但对网络和第三方可用性有依赖。我在做的时候选了前者，因为文档里有部分内部数据，不希望文件流出到外部服务。

2. 地址这一层没理顺，后面全是白忙

2.1 直链、签名地址、本地临时路径的三种性质

预览失败的案例里，我统计了一下，大概八成问题出在“文件地址”这一层，而不是打开动作本身。地址有三种形态，性质完全不同，混用就会出事。

后端直链是最简单的一种，形如https://域名/files/xxx.pdf。它的优点是能直接用，缺点是权限控制弱，任何人拿到链接都能访问。如果文件涉及隐私，直链方案基本要否决。

临时签名地址是主流做法，后端生成一个带过期时间和签名的 URL，通常几分钟到几小时有效。这类地址要注意两点：一是有效期要大于用户从点击到下载完成的整个链路耗时，二是签名参数里如果有特殊字符（比如+、/、=这种 base64 编码产生的字符），没做 URL 编码就会在传输中被截断或篡改，然后后端返回 403。我遇到过签名里的加号变成空格的经典问题，排查了半小时。

本地临时路径是下载之后的产物。App 端拿到的是应用沙箱内的文件路径，小程序端拿到的是形如wxfile://tmp_xxx的临时协议路径，H5 端拿到的是blob:开头的对象 URL。这三者只在各自平台内有效，跨过去就毫无意义。很多人在调试时把小程序端拿到的路径复制到 App 端去测，然后困惑为什么打不开——这是平台隔离决定的，不是 bug。

2.2 downloadFile 的几个隐藏参数

uni.downloadFile看起来就三个参数，实际上有几个直接影响成功率的细节。

第一个是filePath。这是个可选参数，允许你指定下载后的保存路径，但它在不同端支持度不一样。指定它的最大好处是能自己控制文件后缀名——这一点后面会详细说，这是解决“文件类型不支持”报错的关键手段之一。

第二个是响应状态码。downloadFile的success回调里会带statusCode，但如果你只判断success而没有检查statusCode === 200，那么后端返回 403 或者 404 时，你照样会拿到一个临时文件，然后打开时报错，错误信息还跟真实原因毫无关系。我现在的写法是一律先校验状态码，非 200 直接抛错并带上状态码文本，方便定位。

第三个是超时。默认超时时间对于大文件来说往往不够，尤其是移动网络下预览一个几十兆的 PDF。我一般会把超时放到 60 秒以上，并且配一个进度监听，让用户知道文件正在下载而不是界面卡死。

function downloadFile(url, filePath, onProgress) { return new Promise((resolve, reject) => { const task = uni.downloadFile({ url, filePath, timeout: 60000, success: (res) => { if (res.statusCode !== 200) { reject(new Error(`文件下载失败，状态码 ${res.statusCode}`)); return; } resolve(res.tempFilePath || filePath); }, fail: (err) => reject(new Error(err.errMsg || '文件下载失败')) }); if (typeof onProgress === 'function' && task && task.onProgressUpdate) { task.onProgressUpdate((p) => onProgress(p.progress)); } }); }

2.3 后缀名丢了，一切白搭

这一点值得单独拎出来说。uni.openDocument判断文件类型的方式，主要依赖文件路径上的扩展名，而不是文件内容本身。所以当你下载下来的路径是一个随机串，比如_doc/uniapp_temp/1234567890，没有.pdf后缀，打开时就会直接报“不支持的文件类型”。这个报错看起来像是文件本身有问题，实际上是后缀丢失。

有两种解法。第一种是在下载时通过filePath参数显式指定带后缀的保存路径，但要注意这个参数在小程序端要求路径位于用户目录下，不能随便给。第二种是在拿到路径后重命名，App 端可以用文件系统 API 做重命名操作，小程序端则可以用文件系统管理器的 rename 方法。我现在的默认做法是：先从原始文件名或者 URL 里解析出扩展名，扩展名解析不到就报错中断，而不是硬着头皮往下走——早报错比后面出现更奇怪的错误要好。

function resolveExt(url, fileName) { const candidates = [fileName, url.split('?')[0].split('#')[0]]; for (const c of candidates) { if (!c) continue; const match = /\.([a-zA-Z0-9]{2,5})$/.exec(c); if (match) return match[1].toLowerCase(); } return ''; }

这段函数看着简单，但split('?')[0]这一步很关键。签名地址往往带一长串查询参数，不切掉的话正则匹配到的会是参数结尾的东西，直接导致扩展名错乱。

3. App 端：openDocument 的甜区与盲区

3.1 什么时候它非常好用

App 端的文件预览是整条链路里最省心的。只要文件已经落在本地，uni.openDocument一行调用就能把系统阅读器拉起来，用户看到的是他熟悉的界面，手势、缩放、夜间模式都跟着系统走，不用你做任何适配。

// App 端预览 uni.openDocument({ filePath: localPath, fileType: 'pdf', showMenu: true, success: () => { /* 已调起系统阅读器 */ }, fail: (err) => { /* 走兜底提示 */ } });

showMenu: true这个参数我基本都会打开，它会让系统预览界面带上分享、用其他应用打开等菜单，用户想保存到本地或者转发给同事时很方便。有些人担心“文件被随便转走”，如果你的业务场景有这个顾虑，就把它关掉，但要知道这只影响系统菜单，用户截图照样能拿走内容，别把它当成防泄漏手段。

3.2 没有对应阅读器时会怎样

Android 端有一个很容易被忽略的情况：系统里可能根本没有注册能打开某种格式的应用。比如某些精简过的定制系统，打开一个 pptx 文件时，openDocument会直接失败，fail回调里给出的信息通常是找不到可处理该文件的应用。

这个失败在测试机上往往复现不出来——测试机一般装了一堆办公软件。真正出问题的是用户手里的设备。我的处理方式是在fail回调里做二次兜底：先尝试用系统级的方式再次打开，还失败就给出一个明确提示，并且提供“复制文件下载链接”的选项，让用户自己去浏览器里处理。

function openInApp(filePath, fileType) { return new Promise((resolve, reject) => { uni.openDocument({ filePath, fileType, showMenu: true, success: resolve, fail: () => { // #ifdef APP-PLUS plus.runtime.openFile( filePath, {}, () => reject(new Error('当前设备没有可打开该文件的应用')) ); // #endif // #ifndef APP-PLUS reject(new Error('文件打开失败')); // #endif } }); }); }

这里用了条件编译，因为plus对象在非 App 环境下不存在，不做隔离会在编译期或者运行期直接报错。条件编译是 uni-app 项目里的基本功，文件预览这种强平台相关的模块几乎每一段都要用到。

3.3 大文件与返回后的页面状态

App 端预览大文件时，系统阅读器加载需要时间，如果文件是几百兆的扫描版 PDF，用户点开后会看到一个白屏几秒。这不是你的代码问题，但用户会认为是。我一般会在调起前先给一个轻提示或者 loading，等success回调触发后再关掉。

另一个隐蔽的问题是，从系统阅读器返回你的应用页面时，部分 Android 机型上页面会重新走一次onShow，如果这个生命周期里有数据刷新逻辑，用户看到的就是列表数据突然重新加载了一遍。我遇到过一次，用户从预览返回后发现列表滚动位置回到了顶部，体验很差。解决办法是在onShow里判断是不是从预览返回的场景，用一个标志位跳过刷新。

4. 小程序端：在体积红线内把预览做出来

4.1 临时文件的生存周期

小程序端的预览链路是固定的两步：先downloadFile拿到临时路径，再openDocument打开。麻烦的地方在于，这个临时路径是本次小程序运行期间有效的，用户杀掉小程序再进来，路径就失效了。如果页面里有缓存下来的路径，二次进入时直接拿去打开，就会报文件不存在的错。

所以我的规则是：临时路径不落地到本地存储层，只在当前页面的内存里存，页面卸载就丢弃。如果确实需要复用，就用文件系统管理器的保存接口把它转成持久文件，但要清楚持久文件也有总量配额，存多了会写失败。多数预览场景根本不需要持久化，重下就重下，反而更干净。

4.2 域名白名单与开发环境的假象

这是小程序端最经典的“开发环境好、真机全挂”问题。downloadFile请求的域名必须在平台的合法域名列表里配置过，开发者工具里可以选择不校验域名，但真机没有这个开关。

我第一次上线时就是栽在这里：本地和工具里一切正常，提审后真机测试，所有预览都失败。排查思路其实很简单，先看fail回调里的errMsg，如果里面出现“不在以下 request 合法域名列表中”这样的字样，就是白名单问题。把地址对应的域名加到后台配置里，重新编译就好了。

注意：白名单配置的是域名，不是完整 URL，也不是 IP。如果你的文件地址用的是临时 IP 或者测试域名，真机上一定会失败，这是设计阶段就要避开的方向。

4.3 不支持的类型怎么转

小程序端的openDocument支持 doc、docx、xls、xlsx、ppt、pptx、pdf 这几类，但如果你要预览的是 txt、md、csv、ofd 这类，它就不认了。txt 和 md 其实好办，直接下载后用文件系统读成字符串，自己在页面里渲染，还能顺便做搜索和复制。csv 稍微麻烦点，需要自己解析成表格。

真正无解的是 ofd 这类国内文档格式，小程序端没有任何原生支持。这种只能靠后端转成 PDF 或者图片，前端再按 PDF 或图片去预览。我在做这类需求时的判断标准是：如果一种格式在三端里有两端都不支持，那它就不该在前端处理，应该在后端统一转换，前端只接收 PDF 或图片这一种标准产物。

// 小程序端读取文本文件 function readTextFile(filePath) { return new Promise((resolve, reject) => { const fs = uni.getFileSystemManager(); fs.readFile({ filePath, encoding: 'utf8', success: (res) => resolve(res.data), fail: (err) => reject(new Error(err.errMsg || '读取失败')) }); }); }

4.4 一次白屏但无报错的排查

有次线上反馈说点击某个 Word 文件后，页面白了一下就回到列表，没有任何提示。日志里也看不到错误。这种“无声失败”最难查。

我的排查顺序是：第一步，确认文件是否真的下载成功，在downloadFile的成功回调里打点，看statusCode；第二步，确认临时路径的后缀是不是对的；第三步，在openDocument的fail回调里把完整的errMsg打出来。

结果问题是第二步：后端返回的文件名里带中文，downloadFile拿到的临时路径本身是不带扩展名的，而代码里又没做后缀补全，openDocument解析不到类型，走了静默失败。修复方式就是在下载前用filePath指定一个带后缀的路径，路径放在用户目录下，用时间戳加扩展名拼接，问题立刻消失。这个坑之后，我后来所有项目的临时文件路径都强制带后缀，不再依赖任何默认行为。

5. H5 端：iframe 与 pdf.js 的分工线

5.1 iframe 直嵌什么时候够用

H5 端最省事的方案就是 iframe 直接嵌地址。浏览器对 PDF、图片、视频都有原生渲染能力，一个 iframe 或者直接<embed>就能出来。

<iframe :src="previewUrl" style="width: 100%; height: 100%; border: 0;" frameborder="0" />

但这里有两个前提必须满足。第一，文件地址必须是浏览器可以直接访问的，如果后端返回的响应头里带了Content-Disposition: attachment，浏览器会直接触发下载而不是在 iframe 里渲染，用户看到的就是一个下载提示。这个行为由响应头决定，前端改不了，必须让后端在预览场景下返回inline。

第二，跨域问题。如果文件放在独立的静态资源域名下，某些浏览器会对外域资源的嵌入做限制。我在项目里统一的做法是让预览接口和文件服务走同一个域名，或者至少让文件服务带上允许嵌入的响应头，避免上线后在部分浏览器里出现空白框。

5.2 pdf.js 的接入代价与收益

需要精确控制渲染的时候（比如要加水印、要禁止下载按钮、要自定义工具栏），iframe 就不够用了。这时候就要引入 PDF 渲染库。业内用得最多的那套方案原理是把 PDF 的每一页解析成 canvas，然后自己画界面。

代价是体积。这类库压缩后仍然不小，直接打进主包会让首屏变大。我的处理是把它放到分包里，或者在需要预览时才动态加载。

async function loadPdfViewer(container, fileUrl) { const pdfjsLib = await import(/* webpackChunkName: "pdf-viewer" */ 'pdfjs-dist'); const loadingTask = pdfjsLib.getDocument({ url: fileUrl, cMapUrl: '/cmaps/', cMapPacked: true }); const pdf = await loadingTask.promise; for (let i = 1; i <= pdf.numPages; i++) { const page = await pdf.getPage(i); const viewport = page.getViewport({ scale: 1.5 }); const canvas = document.createElement('canvas'); canvas.width = viewport.width; canvas.height = viewport.height; container.appendChild(canvas); await page.render({ canvasContext: canvas.getContext('2d'), viewport }).promise; } }

cMapUrl这个参数很容易漏。如果 PDF 里含有中文等 CJK 字体，不配置字符映射文件路径，渲染出来的文字会变成空白或者乱码，但页面结构还在，看起来像是“字体丢了”。我第一次遇到时以为是文件损坏，换了几个文件都是同样的现象，最后才发现是缺映射表。这个文件需要从库的发行包里拷贝到静态目录，打包配置里也要保证它能被访问到。

5.3 Office 文档在浏览器里没有银弹

再强调一次：H5 端预览 Word、Excel、PPT，前端自身是做不到的。任何声称“前端直接解析 Office”的方案，实际都是在你浏览器里跑一个体积巨大的转换器，性能和维护成本都不划算。

实际可选的路径就两条。一是后端转换，上传时或首次预览时把 Office 转成 PDF，前端按 PDF 的方式处理，这条路的优点是产物统一、体验一致，缺点是转换有延迟，需要做异步任务和状态轮询。二是接入第三方的文档在线预览服务，把文件地址传给对方，拿回一个可嵌入的页面地址，优点是接入快、格式覆盖全，缺点是对外部服务的依赖，以及文件内容的合规性需要评估。

我自己的项目选的是后端转换，理由很实际：文档里有客户信息，不适合交给外部服务；而且转换后的 PDF 还能顺手加上水印，安全性更好控制。

6. 三端收口：一个 preview 模块的完整封装

6.1 接口约定与能力探测

三端逻辑差异这么大，如果每处调用都写一堆条件编译，代码会烂掉。我的做法是提供一个统一入口，把所有分支收在一个文件里。

接口设计上我定了几条规则：入参统一用对象，包含url（必填，文件地址）、name（可选，原始文件名，用于解析扩展名和展示）、fileType（可选，显式指定类型，优先级最高）、onProgress（可选，下载进度回调）。返回值统一是一个 Promise，失败时抛出的错误对象里必须带上可读的中文提示，方便页面直接展示。

能力探测这块，我不用运行时判断 UA 那套，直接用 uni-app 的条件编译，编译期就确定好当前平台走哪条分支，运行期零开销。

// utils/preview.js const OFFICE_EXT = ['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx']; const SUPPORTED_EXT = [...OFFICE_EXT, 'pdf']; function resolveExt(url, fileName) { const candidates = [fileName, (url || '').split('?')[0].split('#')[0]]; for (const c of candidates) { if (!c) continue; const m = /\.([a-zA-Z0-9]{2,5})$/.exec(c); if (m) return m[1].toLowerCase(); } return ''; } function downloadFile(url, filePath, onProgress) { return new Promise((resolve, reject) => { const task = uni.downloadFile({ url, filePath, timeout: 60000, success: (res) => { if (res.statusCode !== 200) { return reject(new Error(`文件下载失败（${res.statusCode}）`)); } resolve(res.tempFilePath || filePath); }, fail: (err) => reject(new Error(err.errMsg || '文件下载失败，请稍后重试')) }); if (task && task.onProgressUpdate && typeof onProgress === 'function') { task.onProgressUpdate((p) => onProgress(p.progress)); } }); }

6.2 分端实现的具体代码

下面是统一入口的核心逻辑，我用条件编译把三端分开，主流程保持清晰：

export async function previewFile(options = {}) { const { url, name = '', fileType = '', onProgress } = options; if (!url) throw new Error('文件地址为空'); const ext = (fileType || resolveExt(url, name) || '').toLowerCase(); if (!ext) throw new Error('无法识别文件类型'); // #ifdef H5 return previewInH5(url, ext, name); // #endif // #ifdef MP if (!SUPPORTED_EXT.includes(ext)) { throw new Error(`暂不支持在线预览 ${ext} 格式`); } const fileName = `${Date.now()}.${ext}`; const filePath = `${uni.env.USER_DATA_PATH}/${fileName}`; const localPath = await downloadFile(url, filePath, onProgress); return openDocument(localPath, ext); // #endif // #ifdef APP-PLUS const tmpPath = await downloadFile(url, undefined, onProgress); const finalPath = await ensureExt(tmpPath, ext); return openInApp(finalPath, ext); // #endif }

App 端的ensureExt负责后缀补全，思路是判断路径结尾是不是目标扩展名，不是就用文件系统 API 重命名：

function ensureExt(filePath, ext) { if (filePath.toLowerCase().endsWith('.' + ext)) { return Promise.resolve(filePath); } return new Promise((resolve, reject) => { plus.io.resolveLocalFileSystemURL( filePath, (entry) => { const newPath = filePath + '.' + ext; entry.getParent((parent) => { entry.moveTo( parent, entry.name + '.' + ext, (newEntry) => resolve(newEntry.fullPath), () => reject(new Error('文件重命名失败')) ); }, () => reject(new Error('文件目录读取失败'))); }, () => reject(new Error('文件不存在')) ); }); }

H5 端的实现要区分 PDF 和其他类型，PDF 优先用 iframe 直嵌，其他类型直接给出提示引导下载：

function previewInH5(url, ext, name) { return new Promise((resolve) => { if (ext === 'pdf' || ['png', 'jpg', 'jpeg', 'gif', 'webp'].includes(ext)) { window.open(url, '_blank'); return resolve({ mode: 'window' }); } if (OFFICE_EXT.includes(ext)) { // 交给页面层处理：提示“浏览器暂不支持直接预览，是否下载” return resolve({ mode: 'fallback', url, name }); } window.open(url, '_blank'); resolve({ mode: 'window' }); }); }

这套封装我在两个项目里用过，改动主要集中在previewInH5上面——因为 H5 端的产品要求每次都不一样，有的要 iframe 内嵌，有的要新开窗口，有的要弹提示。把变化点收在一个函数里，比散落在各个页面里强太多。

6.3 降级提示怎么写才不会被投诉

错误提示的措辞这件事看着小，其实直接影响投诉率。我一度用过“预览失败”四个字，结果客服那边接到一堆“点了没反应”的反馈。后来改成三段式：发生了什么 + 可能的原因 + 用户可以做什么。

比如文件下载失败，提示写成“文件下载超时，可能是网络不稳定，请稍后重试或先下载到本地查看”。格式不支持时写“当前环境暂不支持预览此格式，你可以下载后使用本地应用打开”，并配一个下载按钮。这样用户至少知道下一步该干什么，而不是卡在一个死界面上。

7. 上线之后才会暴露的六个细节

7.1 中文名、空格与井号

文件地址里带中文和特殊字符，是最容易被测试漏掉的场景。中文在 URL 里必须做百分号编码，空格会变成%20也还好，但#是致命字符——浏览器会把它当成锚点分隔符，后面全部被切掉。如果文件名里恰好有#，用户看到的就是下载了一个空文件或者 404。

解决办法是构造地址时统一走一遍编码。注意要整段编码再拼参数，不要只编码文件名部分，否则路径里的斜杠会被一起编码掉，导致地址失效。

const safeUrl = encodeURI(url).replace(/#/g, '%23');

7.2 重复下载与缓存清理

用户在同一页面反复点同一个文件，如果不做控制，就会反复下载，移动网络下流量消耗很可观，小程序端还会因为临时文件堆积导致后续下载变慢。我的做法是在模块内维护一个简易的路径缓存，key 用文件地址的哈希，value 是本地路径加时间戳，超过一定时长（比如五分钟）就失效重下。

缓存要注意不能无限增长。小程序端的临时文件会在小程序销毁时清理，但 App 端的下载文件是真实落盘的，需要定期清理临时目录。我一般在应用启动时做一次清理，把临时目录里超过一定时间的文件删掉。

7.3 iOS 返回后白屏

App 端在 iOS 上有一个现象：从系统预览返回后，页面偶尔会白屏几秒才恢复。原因是系统预览会抢占渲染资源，返回时页面需要重新走一次渲染。这个在低端机上更明显。

缓解方式是：调起预览前先暂停页面上所有正在播放的动画和轮询请求，返回后延迟一小段时间再恢复。这不是根本解决方案，但用户感知会好很多。我试过把onShow里的所有网络请求都延后 300 毫秒执行，白屏时间明显缩短。

7.4 进度条不能只画不动

下载进度如果只是从 0 跳到 100，用户会觉得卡住了。哪怕真实进度没法细粒度拿到，也要让界面有变化——比如显示已经下载的字节数，或者用不确定态的动画。我的经验是，只要界面上有任何变化，用户等待的耐心就会长很多。

7.5 并发下载的控制

一个列表页里如果有多个文件的下载按钮，用户可能连点好几个。移动端同时发起三四个下载请求，很容易出现互相拖慢甚至全部超时的情况。我在封装里加了一个简单的队列，同一时间最多跑两个下载任务，其余排队。实现不复杂，一个数组加一个计数器就够了。

7.6 权限与合规

最后一条不算技术问题但必须提。预览本身就是一种“把文件内容展示给用户”的行为，如果文件涉及敏感信息，需要考虑是否加水印、是否记录访问日志、是否限制单次预览时长。我在做内部资料模块时就被要求加动态水印，用 canvas 叠一层半透明的用户标识，虽然不能彻底防截图，但能起到威慑作用。这部分需求往往在项目后期才提出来，提前预留一个可插拔的水印层，比后期硬改要轻松得多。

我在实际项目里的体会是，文件在线预览这个需求，最难的部分从来不是“把文件打开”，而是把三端那些不一致的边界条件一个个摸清楚。前期的能力矩阵和数据流设计花的时间，会在上线之后成倍地还回来。真正写代码的时间可能只占三成，剩下七成都在处理路径、编码、体积、权限这些看起来琐碎但绕不过去的细节。