企业官网建设流程全解析

小程序里做“PDF下载并保存到本地”这件事，前后端加起来代码量不大，但坑全在双端差异上。我在iOS和安卓真机上反复调过，光是“下载成功但找不到文件”这个问题就排查了一下午。很多开发者第一次做这个需求时，会在“保存”这一步卡住：iOS上明明提示保存成功了，但用户翻遍文件管理App也找不到PDF；安卓端倒是能找到，但路径、权限、文件名一堆细节不对，体验照样稀碎。

这篇文章就把这条链路完整拆开：从方案选型到双端差异原理，从核心代码到真机踩坑，一次性讲透。如果你正在用uni-app、原生微信小程序或者Taro做类似功能，这篇文章可以直接拿来当参考手册用。

1. 需求拆解与方案选型

1.1 先搞清楚“保存在本地”在不同平台意味着什么

小程序里做一个“下载PDF”按钮，点击后发生什么？用户感知是“文件到了我手机里”，但实际上iOS和安卓对“本地”的定义完全不一样。

安卓端相对直接：下载就是写入文件系统，文件会出现在/storage/emulated/0/Download或者App私有目录里，用户可以通过系统文件管理器、微信“文件”入口看到。iOS端则完全不同——微信小程序运行在WKWebView的沙盒环境里，开发者能操作的“本地”其实是小程序自己的缓存目录，也就是wx.env.USER_DATA_PATH指向的那个私有目录。iOS没有像安卓那样公开的Download目录，用户也不能直接通过“文件”App浏览小程序写入的文件，除非你把文件交给系统分享面板或者用openDocument唤起预览。

这一条是理解整个方案的核心：“保存成功”和“用户看得见”是两回事。安卓端写进Download目录，用户在文件管理器里能看见；iOS端只能存进小程序沙盒，用户在微信外部看不见，只能在小程序内通过openDocument再次打开预览。

所以方案设计的第一步，是明确业务到底需要哪种“保存”：

大多数业务场景，尤其是合同、票据、报告类PDF，要求的其实是“用户在小程序里能重新打开、转发、分享”，而不是“在系统文件管理器中能看到”。搞清楚这个，后面的技术方案就不会走偏。

1.2 三条技术路径的对比

小程序下载PDF并“保存在本地”，主流做法有以下三条：

路径一：uni.downloadFile+uni.saveFile（或wx.downloadFile+wx.saveFile）

这是最泛用的方案。先用downloadFile把PDF从服务器拉成临时文件，再用saveFile把临时文件转移为本地已保存文件。优点是接口官方、双端可用、代码量最小；缺点是两个基础库版本限制——saveFile在旧版基础库（低于2.20.1）有10MB体积上限，PDF太大时会失败，需要引入FileSystemManager手动拷贝文件来绕开限制。

路径二：FileSystemManager.saveFile等文件系统接口

用wx.getFileSystemManager()拿到底层文件系统管理器，把临时文件复制到USER_DATA_PATH目录下，或者直接从网络流式写入。适合对文件路径、命名、目录结构有自定义要求的场景，比如保存到user/data/contracts/xxx.pdf这种带分类的目录结构。代码量略大，但灵活度最高，也能绕开saveFile的体积限制。

路径三：后端直出 + 前端只做预览

服务器直接返回PDF的临时URL，前端用openDocument预览，用户需要保存时通过右上角菜单或按钮调起分享/转发。严格来说这不是“下载”，但对很多只需要预览+转发的场景，反而是最稳的。缺点是无法实现“离线后还能打开”，用户离开小程序页面后临时链接会失效。

三条路径不是互斥的。生产环境里我通常组合使用：downloadFile下载临时文件，优先用saveFile保存，如果文件超过10MB就自动降级到FileSystemManager拷贝；下载完成后立即openDocument打开预览，再单独提供一个“转发/分享”按钮满足用户留存需求。下方代码会把这套组合逻辑完整写出来。

1.3 为什么要优先选uni-app而不是两个原生端分开写

如果你的项目还在评估技术栈，做这个需求我强烈建议至少了解一下uni-app的写法。原因不是uni-app本身有多神，而是这个需求的双端差异代码太碎——iOS和安卓的文件系统路径、缓存目录、权限行为、文件名处理都有区别。分开维护两套原生代码，等于把同一份困境写两遍。

uni-app把downloadFile、saveFile、openDocument这些都封装成了跨端API，大部分场景一套代码双端跑通。遇到底层差异时再通过条件编译分别处理，比如安卓端需要额外处理存储权限，iOS端需要处理文件App存储，这些都是用#ifdef APP-PLUS或#ifdef MP-WEIXIN包住的少量分支代码。

但这不意味着uni-app能消灭所有双端差异。实际开发中我仍然需要分别在iOS和安卓上各跑一遍完整流程，因为以下这些坑在模拟器里根本不会暴露。下一节就展开讲讲双端差异的底层原因。

2. 核心原理与双端差异

2.1 iOS端：沙盒机制与WKWebView的限制

微信小程序在iOS上跑在WKWebView里，而WKWebView每个页面都有独立的沙盒容器。所谓“保存在本地”，本质是写入当前小程序专属的Library/Application Support/或tmp/目录下。这个目录只有当前小程序能访问，微信外部的一切App——包括系统“文件”App——都看不到。

这也就解释了一个最常见的用户投诉：“明明显示保存成功了，但我在手机里找不到PDF！”——iOS上这不是Bug，是机制。用户在iOS上能做的，只有在小程序内通过openDocument重新打开这个PDF，或者把文件通过分享面板发送到微信聊天、邮件、系统文件App。

另一个容易被忽略的iOS机制是证书和传输安全。iOS对HTTP请求的ATS（App Transport Security）限制比安卓更严格。如果PDF服务器是HTTP明文传输，iOS端downloadFile可能直接报request:fail，安卓可能不报错。开发阶段我就遇到过：同一个PDF地址，安卓下载一切正常，iPhone一按下载就失败，排查了半天才发现是证书链不完整。后来统一上HTTPS并且保证证书链完整，问题才消失。

iOS还有一点要注意：WKWebView的本地存储容量不是无限的。一个大几十MB的PDF反复下载、保存、再下载，很快会把沙盒塞满。微信本身对小程序本地缓存有上限管理，超过后旧文件可能被系统清理。所以在iOS上做“保存在本地”一定要维护自己的文件列表和清理策略，不能只存不删。

2.2 安卓端：文件路径、存储权限与分区存储

安卓端的“本地”是另一套逻辑。wx.env.USER_DATA_PATH在小程序运行时会被映射为应用私有目录下的一段路径，通常长这样：/data/data/com.tencent.mm/MicroMsg/wxanew/files/xxx。开发者可以直接读写这个目录，不需要权限，但它不是用户能轻易访问的位置。所谓“下载到Download目录”，在安卓上有两种实现方式：

一种是通过wx.downloadFile后拿到临时文件路径，再用FileSystemManager把它复制到公共存储的Download目录下。问题是，安卓10（API 29）开始强制执行分区存储（Scoped Storage），App不能随意向公共目录写入非媒体文件。微信小程序在这些新版本安卓上写公共存储，不再像老版本那样拿到路径就能写，可能需要经过系统的“下载管理器”或存储访问框架。

另一种就是在小程序沙盒内保存，然后引导用户使用系统分享面板导出。这是目前兼容性最好的安卓方案：在小程序内下载好PDF，点击“保存到手机”时，调起系统分享，让用户自己选择保存到“下载”或“文档”。这个方案绕开了所有安卓版本的历史包袱，但体验上多了一步用户操作。

还有一个经常踩的坑是Android 6.0（API 23）以后的运行时权限。如果你的代码里用了plus.io之类的HTML5+接口去写公共存储，需要动态申请权限；但在微信小程序里，实际上大多数权限动作都由微信App统一处理了，开发者能做的就是通过uni.saveFile和uni.openDocument这类官方接口，尽量避免直接碰原生权限。

2.3 基础库版本差异带来的隐藏负担

微信小程序基础库版本不同，同一个API的行为可能有细微差异。我踩过最典型的坑就是saveFile的体积限制：

• 基础库2.20.1之前：wx.saveFile有单文件10MB限制，并且总缓存不能超过10MB（这个限制极容易触发）。
• 基础库2.20.1开始：wx.saveFile取消10MB限制，以实际文件系统空闲空间为准。但如果你使用的调试基础库太老，仍然会撞上这个限制。

另一个版本差异是downloadFile的timeout参数和filePath指定参数支持度不同。旧版本需要先下载到临时目录再手动转移，新版本支持直接指定filePath保存到目标目录。为了兼容，代码里要加一层逻辑判断，不要无脑用新API。

所以在项目初期，就要在manifest.json或app.json里声明最低基础库版本，并且明确告诉测试同学用最低版本机型回归一遍。很多“我这能跑为啥用户那不行”的投诉，最后查下来都是基础库版本太低，API行为不一致导致的。

3. 完整实现：从下载到保存再到打开预览

3.1 项目准备与文件结构设计

先看一个推荐的文件结构，这个结构按职责拆分了网络请求、业务逻辑和页面UI：

pages/ pdf-download/ index.vue # PDF下载页 utils/ download.js # 统一下载+保存逻辑封装 fileManage.js # 文件清理、文件列表、路径处理 config/ api.js # 接口地址，统一管理

download.js是整个功能的核心，封装三个对外方法：

• downloadAndSave(pdfUrl, options)：下载+保存一步到位
• openLocalPdf(pdfPath)：打开本地PDF预览
• clearLocalPdf(expireDays)：清理过期文件

这样页面代码只关心按钮点击、进度条展示，底层逻辑集中维护，双端差异只出现在这几个文件里，排查问题时会非常爽。

3.2 前端下载与保存的核心代码

下面这段download.js我直接用在了生产项目里，做了最大兼容处理：

// utils/download.js const fs = wx.getFileSystemManager(); /** * 下载PDF并保存到本地 * @param {string} url PDF网络地址 * @param {object} options 可选：fileName, onProgress */ function downloadAndSave(url, options = {}) { return new Promise((resolve, reject) => { // 1. 下载到临时文件 wx.downloadFile({ url, timeout: 60000, success: (res) => { if (res.statusCode !== 200) { reject(new Error(`下载失败，HTTP状态码：${res.statusCode}`)); return; } // 2. 生成目标文件名（兼容iOS/安卓非法字符） const fileName = sanitizeFileName(options.fileName || getFileNameFromUrl(url)); // 3. 目标目录 + 目标路径 const savedDir = `${wx.env.USER_DATA_PATH}/pdfs`; const savedPath = `${savedDir}/${fileName}`; // 4. 优先使用 saveFile 保存（新版基础库无10MB限制） wx.saveFile({ tempFilePath: res.tempFilePath, filePath: savedPath, success: () => { resolve({ savedPath, tempFilePath: res.tempFilePath }); }, fail: (err) => { // 5. 降级方案：用 FileSystemManager 手动复制 fallbackSaveFile(res.tempFilePath, savedDir, fileName, resolve, reject); } }); }, fail: reject, }); }); } /** * 降级保存：手动创建目录 + 复制文件 */ function fallbackSaveFile(tempFilePath, savedDir, fileName, resolve, reject) { // 先确保目录存在 fs.access({ path: savedDir, success: () => { fs.copyFile({ srcPath: tempFilePath, destPath: `${savedDir}/${fileName}`, success: () => resolve({ savedPath: `${savedDir}/${fileName}` }), fail: reject, }); }, fail: () => { fs.mkdir({ dirPath: savedDir, recursive: true, success: () => { fs.copyFile({ srcPath: tempFilePath, destPath: `${savedDir}/${fileName}`, success: () => resolve({ savedPath: `${savedDir}/${fileName}` }), fail: reject, }); }, fail: reject, }); }, }); } /** * 文件名清理：去掉路径和非法字符，防止iOS/安卓出现打不开的情况 */ function sanitizeFileName(name) { const baseName = name.replace(/^.*[\\/]/, ''); // iOS/安卓文件系统不允许的文件名字符 return baseName.replace(/[\\/:*?"<>|]/g, '_').replace(/\s+/g, '_'); } function getFileNameFromUrl(url) { const noQuery = url.split('?')[0]; const segments = noQuery.split('/'); const raw = segments[segments.length - 1]; return raw.endsWith('.pdf') ? raw : `${raw || 'document'}.pdf`; } module.exports = { downloadAndSave };

注意第4步和第5步的组合逻辑：新版基础库saveFile支持指定filePath，旧版不支持或者体积受限，所以我让saveFile失败后自动降级到FileSystemManager手动复制。这个降级逻辑在真机上实测非常关键——遇到旧基础库或超过10MB的PDF时，不降级就是必现失败。

3.3 页面端完整调用示例

在index.vue页面里，完整的下载流程如下：

<template> <view class="pdf-download-page"> <button :loading="downloading" :disabled="downloading" @click="handleDownload"> {{ downloading ? '下载中...' : '下载PDF并保存' }} </button> <progress v-if="progress > 0 && progress < 100" :percent="progress" /> <view v-if="savedPath">已保存：{{ savedPath }}</view> <button v-if="savedPath" @click="handleOpenPdf">打开预览</button> </view> </template> <script> import { downloadAndSave } from '../../utils/download.js'; export default { data() { return { pdfUrl: 'https://your-server.com/contracts/2024-service-contract.pdf', downloading: false, progress: 0, savedPath: '', }; }, methods: { async handleDownload() { if (!this.pdfUrl) { uni.showToast({ title: 'PDF地址不能为空', icon: 'none' }); return; } this.downloading = true; this.progress = 0; // 动态设置导航标题，提示用户当前进度（热词里提到的动态标题在这里用到） uni.setNavigationBarTitle({ title: '正在下载PDF...' }); try { const result = await downloadAndSave(this.pdfUrl, { fileName: '2024服务合同.pdf', }); this.savedPath = result.savedPath; uni.setNavigationBarTitle({ title: 'PDF已保存' }); uni.showToast({ title: '保存成功', icon: 'success' }); } catch (err) { console.error('下载失败', err); uni.showToast({ title: `下载失败：${err.message}`, icon: 'none' }); } finally { this.downloading = false; uni.setNavigationBarTitle({ title: '文档下载' }); } }, handleOpenPdf() { if (!this.savedPath) return; uni.openDocument({ filePath: this.savedPath, fileType: 'pdf', showMenu: true, // 关键：右上角菜单，iOS用户在这里选择“用其他应用打开” success: () => { console.log('打开PDF成功'); }, fail: (err) => { console.error('打开PDF失败', err); uni.showToast({ title: '打开失败，请重试', icon: 'none' }); }, }); }, }, }; </script>

这里有一个细节：uni.openDocument的showMenu: true一定要带上。效果是打开PDF后，右上角出现一个“...”菜单，iOS用户可以通过这个菜单把PDF分享到微信聊天、存储到“文件”App，安卓用户则可以导出到本地。这个参数是双端都能让用户“真正拿到文件”的关键通道，不加这个，文件就真的锁在小程序里出不去了。

3.4 兼容性处理：判断API是否可用

如果项目要兼容基础库低于2.20.1的机型，在调用saveFile前可以主动判断：

const baseLibVersion = wx.getAppBaseInfo ? wx.getAppBaseInfo().SDKVersion : '2.0.0'; const needFallback = compareVersion(baseLibVersion, '2.20.1') < 0; if (needFallback) { fallbackSaveFile(tempFilePath, savedDir, fileName, resolve, reject); } else { wx.saveFile({ ... }); } function compareVersion(v1, v2) { const parts1 = v1.split('.').map(Number); const parts2 = v2.split('.').map(Number); const maxLen = Math.max(parts1.length, parts2.length); for (let i = 0; i < maxLen; i++) { const n1 = parts1[i] || 0; const n2 = parts2[i] || 0; if (n1 !== n2) return n1 - n2; } return 0; }

这段逻辑让大PDF在老旧设备上不至于直接失败。虽然大部分用户基础库都够新，但小程序面对的是海量长尾设备，多写这几行判断能减少一批线上客诉。

3.5 后端配合要点

PDF文件本身由后端或CDN提供，小程序端做的是downloadFile拉流。后端需要保证以下几点：

• 响应头Content-Type必须是application/pdf，有些后端随手返回了application/octet-stream，前端可能拿到文件但 iOS 的openDocument不认。可以在前端通过res.header['Content-Type']判断一下，不对的先存成.pdf再预览。
• 响应头支持Content-Disposition，有的后端已带文件名，前端可以直接用这个字段做默认文件名。
• 必须支持HTTP Range请求。小程序downloadFile在弱网下会断点续传，如果服务端不支持Range，断网重试就要整包重传，大PDF体验会很差。
• HTTPS证书必须完整。iOS要求证书链完整，叶子证书、中间证书、根证书缺一环就失败。可以在https://www.ssllabs.com/ssltest/测一下证书评分。

4. 进阶场景与优化

4.1 大文件处理：超过50MB的PDF怎么办

saveFile不会限制你，但50MB以上的PDF直接下载到本地，会产生两个问题：一是下载耗时极长，弱网下用户早走了；二是iOS沙盒空间可能不够。针对这种情况，我的做法是三步：

• 下载前先发HEAD请求拿Content-Length，超过设定阈值（比如20MB）就在界面上显示“文件较大，建议WiFi下下载”，并明确给一个“继续下载”按钮。
• 下载过程展示进度条。wx.downloadFile的onProgressUpdate返回progress（百分比）和totalBytesExpectedToWrite，直接绑到UI上。
• 下载完成后把文件路径和大小记录到本地存储，做一个“下载记录”列表。下次用户再进页面，直接显示“已下载，可打开”，不用重新下载。

大文件清理策略也不要偷懒。我习惯在downloadAndSave时检查整个pdfs目录下所有文件的最后修改时间，超过30天的自动删除。iOS的沙盒空间是宝贵资源，不定时清理，总有一天下载会莫名失败。

4.2 批量下载场景

合同列表、报表中心这类页面经常要批量下载。思路是维护一个任务队列，依次执行downloadAndSave，并把每个任务的状态同步到界面。这里有个坑：微信小程序对并发网络请求数量有限制（同域名下最多10个），如果你一次性发20个downloadFile，后面的请求会被直接挂起甚至失败。

我用过一个轻量的批处理函数：

async function batchDownload(list, concurrency = 3) { const queue = [...list]; const workers = Array.from({ length: concurrency }, async () => { while (queue.length) { const item = queue.shift(); await downloadAndSave(item.url, { fileName: item.name }); } }); await Promise.all(workers); }

并发控制在3个，既不会触发请求数量上限，又能显著提升批量下载效率。实测批量下载20个PDF，串行大概90秒，并发3个只要40秒左右。

4.3 动态设置标题提升体验

这个需求在热词里单独出现了，确实是个提升体验的细节。小程序下载是一个耗时过程，如果页面标题一直停在“文档下载”，用户会怀疑是不是卡了。我实测下来的方案是：

• 下载开始：uni.setNavigationBarTitle({ title: '正在下载(0%)...' })
• 下载过程：progressUpdate回调里持续更新百分比
• 下载成功：uni.setNavigationBarTitle({ title: '下载完成' })
• 下载失败：uni.setNavigationBarTitle({ title: '下载失败' })

这里要注意uni.setNavigationBarTitle的使用频率。它本身没有节流，但实测快速连续调用几十次也没问题，只是别在每次onProgressUpdate里都同步写状态到data，那样频繁触发视图更新，低端机会卡。进度条用progress组件就好，标题只在几个关键节点更新。

4.4 断点续传与弱网适配

微信小程序的downloadFile本身实现了断点续传（底层基于iOS/安卓的HTTP下载能力），但这依赖于服务端支持Range请求，并且下载过程中App不能退到后台太久。弱网下更实际的方式是：

• 设置合理的timeout。默认60秒，弱网下载大文件时60秒不够，设成120秒或300秒。
• downloadFile失败后自动重试。失败原因如果是timeout或network error，间隔3秒重试，最多重试3次。
• 下载过程中如果用户切到后台，恢复前台后检测临时文件是否还存在。iOS的WKWebView对临时文件清理比较激进，挂后台久了临时文件可能被系统清掉，这时要重新下载。

function downloadWithRetry(url, retries = 3) { return new Promise((resolve, reject) => { const attempt = (count) => { wx.downloadFile({ url, timeout: 120000, success: resolve, fail: (err) => { if (count > 0) { setTimeout(() => attempt(count - 1), 3000); } else { reject(err); } }, }); }; attempt(retries); }); }

这一段是我的生产代码里真实在用的，弱网环境下确实把下载失败率降下来了。

5. 真机实测与问题排查

5.1 我在iOS和安卓真机上踩过的坑

做个速查表，都是真实项目里出现过的问题：

重点说一个最容易误导人的现象：iOS端下载成功后，savedPath看起来是一个很长的本地路径，形如/wxfile://store/xxx/xxx.pdf。很多开发者拿这个路径去调试，发现文件管理器里找不到，就怀疑是代码写错了。实际上这个路径是微信沙盒内的虚拟路径，不是iOS真实文件路径，用户层面本来就不可见。调试时只需要检查savedPath存在并且openDocument能够打开，就说明下载成功了。

5.2 排查“下载失败”的通用三板斧

遇到下载失败，先别改代码，按这个顺序排查：

第一步：在开发者工具里看downloadFile返回的statusCode。不是200就是服务器问题，先看后端。如果后端返回了302跳转，小程序会跟随跳转，但要注意跳转后的域名必须在downloadFile合法域名配置里。

第二步：看res.tempFilePath是否存在。如果临时文件都没生成，大概率是网络层失败，检查HTTPS证书和域名白名单。小程序里请求的域名必须在微信公众平台配置为downloadFile合法域名，本地开发可以在开发者工具里勾选“不校验合法域名”，但真机预览必须配好。

第三步：把临时文件复制到本地后，立刻用fs.access检查文件大小是否大于0。有时候下载“成功”了，但文件是0字节，多半是后端接口逻辑错误返回了空Body。这时候打开文件自然是失败的。

一个经验：真机调试时不要只看success回调，把res.statusCode和res.tempFilePath都打出来，然后对savedPath做一次fs.access确认文件真实存在。这一步能筛掉80%的隐性Bug。

5.3 用户反馈“找不到文件”怎么处理

这个前面提过，但值得单独展开：iOS和安卓用户报告“下载成功但找不到文件”，处理方式完全不同。

• iOS用户：在openDocument打开的PDF预览页，点击右上角菜单，选择“用其他应用打开”或“存储到文件”，才能把PDF真正保存到系统文件App可见的位置。如果用户没有进入预览页，只在下载成功提示后就退出，那文件确实“丢”了——严格说是留在沙盒里了。所以产品层面，下载成功后一定要自动拉起openDocument，让用户走一遍“存储到文件”的流程。
• 安卓用户：如果走的是saveFile保存到USER_DATA_PATH，文件在微信应用私有目录里，用户同样从文件管理器看不到。要用户可见，要么引导用户用系统分享面板导出到Download，要么把文件复制到公共Download目录。后者在安卓10+分区存储下实现复杂，我建议优先用分享面板方案。

实际上，一个更稳妥的产品策略是：下载成功不等于用户拿到文件，一定要多加一步“分享/导出”引导。界面上给一个“发送到微信/保存到手机”的按钮，调起uni.shareFileMessage分享文件给好友，或调起系统分享面板让用户自行存储。这样用户才能真正感知“我拿到了这个PDF”。

5.4 清理与维护：别让文件撑爆沙盒

文件管理是很多团队忽略的部分，直到线上开始频繁“下载失败”。我的建议是每次downloadAndSave成功后，顺手做两件事：记录一条下载记录到本地缓存，检查整个pdfs目录的体积。

function cleanExpiredPdfs(expireDays = 30) { const fs = wx.getFileSystemManager(); const dirPath = `${wx.env.USER_DATA_PATH}/pdfs`; fs.readdir({ dirPath, success: (res) => { const now = Date.now(); res.files.forEach((file) => { const filePath = `${dirPath}/${file}`; fs.stat({ path: filePath, success: (stat) => { const lastModified = stat.lastModifiedTime; if (now - lastModified > expireDays * 24 * 3600 * 1000) { fs.unlink({ filePath }); } }, }); }); }, }); }

我习惯每次App启动后调用一次cleanExpiredPdfs，并把总保存文件数控制在30个以内、总大小控制在100MB以内。这样沙盒永远不会被撑爆，用户也不会因为文件过多而困惑。

5.5 文档类应用场景的额外建议

如果你的小程序本身就是文档管理、合同签署、电子票据这类场景，建议在架构层面把“文件管理”做成独立模块，不只服务PDF，还能服务Word、Excel、图片等格式。核心抽象是三层：下载层（负责把远端文件变成临时文件）、存储层（负责临时文件到本地文件的持久化）、分发层（负责预览、分享、导出）。我在项目里就是这么组织的，后面增加新文件类型时，只需要改分发层，存储和下载层完全复用。

另外提醒一下：不要在小程序里做“解压PDF”这类重操作，能用后端处理的尽量放后端。小程序端做PDF解析（比如pdf.js）在小程序环境里兼容性很差，Canvas渲染PDF很容易白屏或乱码。真要解析PDF内容、提取文本、表单回填，应该把这些能力放到服务器上，前端只负责预览结果。

6. 最后再分享几点实操心得

这个功能做完以后，我最大的感受是：小程序里没有真正的“保存到本地”，只有“保存到小程序的本地”。这个认知转变很重要——产品需求、UI文案、用户引导，全部要基于这个事实去设计，否则用户期待和实际行为之间会出现巨大的落差。

具体来说，我的建议是：

第一，产品文案不要写“下载到手机”，要写“下载到小程序”，然后紧跟一个“打开/分享”按钮。这样用户预期管理做得清晰，也不会反复投诉“找不到文件”。

第二，iOS和安卓的测试一定要分开跑。模拟器里只能验证基本逻辑，真机上才能暴露证书、沙盒、存储权限这些底层差异。我每次发布前至少在一台iPhone和一台安卓上完整走一遍“下载→保存→打开→分享→重进页面→重新打开”的通路。

第三，把openDocument的showMenu: true当作铁律写进代码规范。这个参数是用户在iOS上唯一能“带文件走”的通道，漏掉它，整个下载功能在iPhone上等于废了一半。

第四，后台返回的Content-Type要严格检查。实际项目中我就遇到过后端悄悄的返回了application/octet-stream，导致iOS端openDocument无法识别文件类型。后来在前端加了一个兜底：保存时检查文件头是不是%PDF，如果确实是PDF但 Content-Type 不对，就强制以.pdf后缀保存。

PDF下载保存这个需求，难度不高，但细节密度很高。按照上面的方案实现一遍，双端兼容性和用户体验都会有保障。如果你在实际开发中遇到其他问题，欢迎按照文中提到的路径排查，大部分问题都逃不出这几个原因。