uniapp保存图片三端实战：H5下载、Android权限与iOS相册授权

图片要保存到本地这个需求看起来一句话就能说完真动手做的时候往往要在 H5、Android、iOS 三个运行环境里各写一套逻辑还要处理权限、路径、跨域、相册刷新这些零零碎碎的细节。uniapp 把这三种运行环境收在同一个工程里好处是业务代码可以复用麻烦的地方就在于同一个保存图片的动作在浏览器里是触发下载在 Android 上是写文件到相册在 iOS 上又是请求照片库授权后写相册三者底层完全不是一回事。这篇内容我想把这三端的实现链路拆开讲清楚H5 端怎么绕过跨域把图片变成可下载的 blobAndroid 端怎么处理不同系统版本的存储权限和相册刷新iOS 端怎么在沙盒和照片库之间正确落盘最后再给一套可以直接抄走的跨端封装。适合已经上手 uniapp、正在做海报保存、二维码保存、凭证图片下载这类功能的前端同学也适合刚接触多端适配、想搞明白为什么同一段代码三端表现不一样的开发。1. 先搞清楚三端保存图片到底差在哪1.1 三个运行环境三套文件系统逻辑很多人第一次写这个功能会下意识去找一个万能 API结果翻文档翻到uni.saveImageToPhotosAlbum以为这一条就能通吃写完一跑H5 端直接报当前平台不支持。问题不在于 API 设计得不好而在于三个运行环境对保存到本地这件事的定义根本不同。H5 运行在浏览器沙箱里页面没有任何直接写磁盘的能力你能做的只有发起一次下载请求让浏览器自己决定文件落在哪里用户点确认还是取消你都无法干预。Android 端的 App 是一个真正的原生进程它有私有目录、有公共存储区、有系统相册媒体库写入的位置不同权限要求就完全不同。iOS 更严格应用被关在沙盒里想往用户照片库写东西必须走系统提供的授权通道用户点了拒绝你就彻底没戏。所以正确的思路不是找万能 API而是先想清楚保存到哪里这件事在三端各自对应什么。多数业务场景想要的其实是用户在系统相册或下载目录里能看到这张图那么 H5 对应浏览器下载目录Android 对应相册媒体库iOS 对应照片 App。这条主线定下来后面的技术选型才有依据。1.2 需求拆解保存到哪里算保存成功我在项目里会把需求拆成三个问题来问产品一图片最终要在哪里被用户看到是相册、文件管理器还是应用内部二是否需要不经过用户操作就能保存三保存失败时要不要给用户可操作的补救路径这三个问题的答案直接决定方案。如果是保存到相册走系统相册接口如果是存到应用内部供后续上传那走私有目录就够了还省掉权限申请如果必须静默保存不给任何提示那 H5 端基本不可能实现只能退化成展示图片引导用户长按。我见过一些项目把保存成功的提示做成uni.showToast结果 Android 上图片其实写进了应用私有目录用户在相册里翻半天找不到回来投诉功能有问题。这种坑的根源就是一开始没把保存到哪里定义清楚代码写完才发现语义对不上。1.3 一个容易被忽略的前置条件图片从哪来图片的来源同样影响链路长度。远端 URL、本地临时文件、base64 字符串这三种来源在三端的处理路径完全不同。远端 URL 在 H5 端会撞上跨域在 Android 和 iOS 端要先下载成本地临时文件base64 在 H5 端可以直接塞进a标签的href在 App 端必须先写成本地文件才能交给相册接口本地临时文件相对最简单但它的有效期很短App 重启后可能就失效了。我一般会在业务层统一约定不管图片从哪来先归一化成一个可访问的本地路径或者一个可下载的远端 URL再交给保存函数。这样上层的保存逻辑只需要处理两种输入代码复杂度立刻降一个量级。2. 方案选型别一上来就写代码2.1 官方 API 的能力边界对照uniapp 官方在图片保存这块提供了几个不同层次的 API能力边界差异很大先把这张表记在心里能省掉大量试错时间。APIH5AndroidiOS说明uni.saveImageToPhotosAlbum不支持支持支持保存到系统相册App 端最常用uni.downloadFile支持受跨域限制支持支持下载远端资源到临时目录uni.saveFile不支持支持支持把临时文件转成持久化文件uni.getFileSystemManager不支持支持支持文件读写HBuilderX 3.5.3 起可用plus.gallery.save不支持支持支持5 原生相册接口粒度更细a[download]或 Blob 下载支持不适用不适用H5 端标准做法看到这张表基本就能明白H5 是一条完全独立的技术路线Android 和 iOS 可以共用大部分逻辑但权限和路径上还要分开处理。所以工程结构上我会把它拆成两个函数saveImageH5和saveImageApp用条件编译在入口处分流App 内部再按osName做二次细分。2.2 条件编译是整个方案的地基uniapp 的条件编译在这里不是可选技巧而是必需的工程手段。uni.getFileSystemManager这类 API 在 H5 端根本不存在如果你把它写在公共模块里H5 打包时不会报错但运行时一调用就是undefined is not a function。所以我会把平台相关的代码全部包在条件编译注释里。// #ifdef H5 export function saveImage(options) { return saveImageH5(options); } // #endif // #ifdef APP-PLUS export function saveImage(options) { return saveImageApp(options); } // #endif这种写法有个细节要注意条件编译是在编译期生效的所以同一份源码在不同平台打包后产物里只会保留对应的那一个函数。这比运行时判断process.env.UNI_PLATFORM更干净也不会把无用代码带进包里。我在早期的项目里图省事用了运行时判断结果 H5 包里混进了一堆plus.*的调用虽然没执行但代码体积和可读性都被拖累了。2.3 封装层的输入输出约定统一封装的函数签名我固定成这样的形态/** * param {Object} options * param {string} options.url 远端图片地址与 path 二选一 * param {string} options.path 本地临时路径或 base64与 url 二选一 * param {string} [options.filename] 下载文件名仅 H5 生效 * returns {Promise{path: string}} */返回值统一给一个pathH5 端返回空字符串App 端返回实际落盘路径。这样调用方只需要关心成功还是失败不需要关心内部走了哪条链路。失败时统一抛出一个带code和message的 Error业务层据此决定是提示权限被拒绝还是网络异常。3. H5 端实操浏览器里保存图片就是触发下载3.1 URL 直链下载的最短路径如果图片本身是一个同源的 URL或者服务器已经在响应头里带了Content-Disposition: attachment那最省事的做法就是创建一个隐藏的a标签设置download属性后模拟点击。function downloadByAnchor(url, filename) { const a document.createElement(a); a.href url; a.download filename || image; a.style.display none; document.body.appendChild(a); a.click(); document.body.removeChild(a); }这段代码在桌面浏览器上稳如老狗但在移动端的表现就参差不齐了。iOS Safari 从 13 才开始比较完整地支持download属性13 以前的版本会直接把图片在新标签页打开用户得自己长按保存。国内不少安卓浏览器用的是定制内核download属性可能被忽略表现同样是打开图片预览页。所以我会在调用前先做一次能力探测而不是盲目执行function canUseDownloadAttr() { const a document.createElement(a); return typeof a.download ! undefined; }探测不通过就走后面的兜底方案。3.2 跨域图片的 Canvas 中转方案真实业务里的图片大多挂在 CDN 上域名跟页面不同这时候a[download]会失效——浏览器出于安全考虑不允许把跨域资源直接下载到本地。解决办法是把图片先画到 canvas 上再通过toBlob导出成同源的 Blob 对象。function downloadByCanvas(url, filename) { return new Promise((resolve, reject) { const img new Image(); img.crossOrigin anonymous; img.onload () { const canvas document.createElement(canvas); canvas.width img.naturalWidth; canvas.height img.naturalHeight; const ctx canvas.getContext(2d); ctx.drawImage(img, 0, 0); canvas.toBlob((blob) { if (!blob) { reject(new Error(canvas 导出失败)); return; } const objectUrl URL.createObjectURL(blob); const a document.createElement(a); a.href objectUrl; a.download filename || image.png; document.body.appendChild(a); a.click(); document.body.removeChild(a); setTimeout(() URL.revokeObjectURL(objectUrl), 1000); resolve(); }, image/png); }; img.onerror () reject(new Error(图片加载失败请检查跨域配置)); img.src url; }); }这里的img.crossOrigin anonymous是关键它让浏览器以匿名模式请求图片不带 cookie同时要求服务器响应Access-Control-Allow-Origin。如果服务器没配这个头图片依然能加载出来但 canvas 会被标记成被污染调用toBlob时抛SecurityError。这个错误在控制台里往往只显示一行Tainted canvases may not be exported新手很容易一头雾水。URL.revokeObjectURL那行放在setTimeout里不是随手写的。部分浏览器在a.click()之后立刻回收 Blob URL 会导致下载中断加一个短延时能规避这个问题。这个延时我没有精确测量过具体需要多少经验值 1000 毫秒足够保险。3.3 base64 图片在 H5 的特殊处理base64 图片在 H5 端反而是最好处理的因为它天生就是同源的。直接把data:image/png;base64,...塞给a.hrefdownload属性同样生效。function downloadByBase64(base64, filename) { const a document.createElement(a); a.href base64; a.download filename || image_${Date.now()}.png; document.body.appendChild(a); a.click(); document.body.removeChild(a); }不过有个隐蔽的坑微信内置浏览器会拦截 base64 的下载行为点击后没有任何反应也不会报错。这种情况下只能退化成把图片渲染到页面上提示用户长按保存。3.4 微信内置浏览器的兜底策略微信 WebView 对下载的支持一直很保守a[download]和 Blob 下载都可能被静默拦截。我的做法是先判断 UAfunction isWechat() { return /micromessenger/i.test(navigator.userAgent); }如果是微信环境直接跳过下载尝试把图片用img标签放大展示配一句长按图片保存到手机。用户体验上其实并不差微信用户对长按保存这个动作已经形成肌肉记忆了。如果是微信里通过公众号 JSSDK 接入的场景还可以调用wx.previewImage预览图片用户在预览页右上角同样有保存选项。不过这条路径需要公众号配置和鉴权门槛比纯 H5 高我会在文档里当备选方案列出来不强推。还有一个小众但值得提的场景部分安卓定制浏览器在下载时会弹出一个是否保存的原生对话框用户点了取消代码里是感知不到的。所以 H5 端的保存成功提示我一般写成已触发下载请在通知栏或下载列表查看而不是保存成功避免误导。4. Android 端实操权限、分区存储与相册刷新4.1 网络图片先落地downloadFile 的正确用法uni.saveImageToPhotosAlbum只接受本地文件路径传 http URL 会直接失败。所以远端图片必须先下载到临时目录。uni.downloadFile就是干这个的成功回调里拿到的tempFilePath在 Android 上是/storage/emulated/0/Android/data/包名/cache/...这样的绝对路径可以直接交给后续的保存接口。function downloadToTemp(url) { return new Promise((resolve, reject) { uni.downloadFile({ url, success: (res) { if (res.statusCode 200) { resolve(res.tempFilePath); } else { reject(new Error(下载失败状态码 ${res.statusCode})); } }, fail: (err) reject(new Error(err.errMsg || 网络异常)) }); }); }这里有个容易被忽略的点statusCode的判断不能省。服务端返回 404 时downloadFile的成功回调依然会触发tempFilePath指向的可能是一个包含错误页面的文件后续保存到相册会得到一张裂图或者 HTML 文件。我踩过一次排查了半天才发现是 CDN 上的图片被删了。另外要注意downloadFile下载的临时文件在应用重启后可能被系统清理所以如果业务需要保存后长期可访问要么走uni.saveFile转成持久化文件要么直接保存进相册。相册里的文件归系统媒体库管理不受应用缓存清理影响。4.2 权限申请的分版本策略Android 的存储权限从 6.0 开始是运行时权限从 10 开始引入了分区存储两个变化叠加起来让这块代码必须分支处理。Android 6.0 到 9.0写外部存储需要WRITE_EXTERNAL_STORAGE权限而且必须在运行时动态申请。这段我用plus.android调原生接口function requestAndroidStoragePermission() { return new Promise((resolve) { const Build plus.android.importClass(android.os.Build); // Android 10 及以上走分区存储保存自己的图片不需要额外权限 if (Build.VERSION.SDK_INT 29) { resolve(true); return; } plus.android.requestPermissions( [android.permission.WRITE_EXTERNAL_STORAGE, android.permission.READ_EXTERNAL_STORAGE], (result) { const denied result.deniedPresent.length result.deniedAlways.length; resolve(denied 0); }, () resolve(false) ); }); }deniedAlways和deniedPresent要分开看。前者表示用户勾选了不再询问后者表示这次拒绝了但下次还会弹。针对deniedAlways正确做法是引导用户去设置页手动开启而不是反复弹窗调系统接口——系统根本不会再弹。function openAppSetting() { const main plus.android.runtimeMainActivity(); const Intent plus.android.importClass(android.content.Intent); const Uri plus.android.importClass(android.net.Uri); const intent new Intent(); intent.setAction(android.settings.APPLICATION_DETAILS_SETTINGS); intent.setData(Uri.fromParts(package, main.getPackageName(), null)); main.startActivity(intent); }Android 10 及以上的分区存储是个好消息应用通过 MediaStore 写入自己的图片不需要任何存储权限这也是我把版本判断放在最前面的原因——能少一次弹窗就少一次用户体验上差别很大。4.3 保存到相册的完整链路链路串起来大概是这个样子async function saveImageToAlbumAndroid(url) { const granted await requestAndroidStoragePermission(); if (!granted) { throw new Error(STORAGE_PERMISSION_DENIED); } const tempPath await downloadToTemp(url); return new Promise((resolve, reject) { uni.saveImageToPhotosAlbum({ filePath: tempPath, success: () resolve({ path: tempPath }), fail: (err) reject(new Error(err.errMsg || 保存相册失败)) }); }); }uni.saveImageToPhotosAlbum在 Android 上内部调用的是系统的媒体扫描插入逻辑成功之后图片会出现在相册App 的最近项目里不需要你手动发广播刷新媒体库。这一点跟直接用FileOutputStream写到公共目录不同后者如果不发MediaScannerConnection.scanFile的广播文件管理器里能看到但相册里不显示。官方 API 帮你处理了这一步代价是灵活性差一些比如没法自定义相册子目录的名字。如果业务确实需要把图片归到一个固定命名的相册里那就得用plus.gallery.savefunction saveToNamedAlbum(filePath, albumName) { return new Promise((resolve, reject) { plus.gallery.save(filePath, () resolve(), (err) reject(err), albumName); }); }这个接口的最后一个参数就是相册名实测在大部分国产 ROM 上都能正确建目录但在某些深度定制的系统上可能被忽略图片还是落到默认相册。这种差异没法从文档里查到只能真机测试。4.4 存到应用私有目录的适用场景有些业务根本不需要用户去相册里找图比如生成一张图片后要立刻上传到服务器或者存下来做本地缓存。这时候完全可以绕开权限直接写应用私有目录。uni.getFileSystemManager在 App 端的可用路径有几个固定前缀_doc对应应用的文档目录_downloads对应下载目录。写文件大概这样function writeToDocDir(base64Data, filename) { return new Promise((resolve, reject) { const fs uni.getFileSystemManager(); const filePath ${uni.env.USER_DATA_PATH}/${filename}; fs.writeFile({ filePath, data: base64Data, encoding: base64, success: () resolve(filePath), fail: (err) reject(new Error(err.errMsg || 写入失败)) }); }); }uni.env.USER_DATA_PATH在 App 端会解析成实际的应用私有路径Android 上大概是/storage/emulated/0/Android/data/包名/files/iOS 上在沙盒的 Documents 里。这条路子不需要任何权限写进去的文件也不会被系统清理但用户通过文件管理器很难找到它仅适合应用内部使用。5. iOS 端实操沙盒路径与相册授权5.1 沙盒路径的三条路iOS 应用运行在沙盒里能写的目录就那么几个。uniapp 里常用的有三个_doc对应 Documents 目录_documents是同一位置的另一种写法_downloads对应 Library/Downloads。写临时文件的时候我常用_doc因为它在文件共享开启的情况下用户可以通过 iTunes 或者访达访问到调试的时候方便。function saveToSandbox(base64Data, ext) { const filename img_${Date.now()}.${ext || png}; const filePath _doc/${filename}; return new Promise((resolve, reject) { plus.io.resolveLocalFileSystemURL(filePath, (entry) { entry.createWriter((writer) { writer.onwrite () resolve(entry.toLocalURL()); writer.onerror (e) reject(new Error(e.message || 写入失败)); // 去掉 base64 的 data URI 前缀 const raw base64Data.replace(/^data:image\/\w;base64,/, ); writer.writeAsBinary(raw); }, (err) reject(new Error(err.message))); }, (err) reject(new Error(err.message))); }); }这段用的是 5 的plus.ioAPI兼容性最好。如果要统一用uni.getFileSystemManager代码会更简洁一些但前提是 HBuilderX 版本够新。注意writer.writeAsBinary接收的是纯二进制字符串不能带data:image/png;base64,这个前缀否则写出来的文件是损坏的。这个坑非常常见图片保存成功但打开是坏的八成就是前缀没剥干净。5.2 相册授权的两种级别iOS 的相册权限分得比 Android 细NSPhotoLibraryUsageDescription是读写权限NSPhotoLibraryAddUsageDescription是仅添加权限。用uni.saveImageToPhotosAlbum只需要添加权限就够了但这两种描述必须提前在manifest.json的 iOS 配置里填好否则打包时不会自动生成运行时一调用相册接口就直接闪退或者被拒。{ app-plus: { distribute: { ios: { privacyDescription: { NSPhotoLibraryAddUsageDescription: 需要访问相册以保存图片, NSPhotoLibraryUsageDescription: 需要访问相册以保存图片 } } } } }这两个键名写错是另一个高频事故。我见过把NSPhotoLibraryAddUsageDescription拼成NSPhotoLibraryAddUsageDescriptions的编译器不报错上架审核的时候被系统直接拒掉返回的原因列表里会带上具体的键名。iOS 14 之后新增了有限访问的概念用户可以选择只授权应用访问部分照片。对于保存场景来说仅添加权限不受这个限制影响用户授权后应用依然能写入新图片只是读不到已有的照片。所以如果业务只是保存不读取尽量只申请 Add 权限被用户拒绝的概率会低不少。用户拒绝授权之后再调用相册接口会立即失败不会二次弹窗。这时候要给用户一条明确的路径function gotoSystemSettingIos() { const UIApplication plus.ios.importClass(UIApplication); const app UIApplication.sharedApplication(); const url plus.ios.invoke(app, openURL:, plus.ios.invoke(NSURL, URLWithString:, app-settings:)); }这段代码在 iOS 8 之后都能用打开的是当前应用的设置页用户可以在那里重新开关权限。5.3 base64 转临时文件的统一处理iOS 端有一个细节跟 Android 不太一样uni.saveImageToPhotosAlbum的filePath参数在某些版本上要求必须是file://协议开头的路径而在另一些版本上接受相对路径。为了保险我会在调用前统一做一次路径规范化function normalizePath(path) { if (!path) return path; if (path.startsWith(file://)) return path; if (path.startsWith(_doc) || path.startsWith(_downloads)) { return plus.io.convertLocalFileSystemURL(path); } return path; }plus.io.convertLocalFileSystemURL会把_doc/xxx.png这种相对路径转成file:///var/mobile/Containers/.../Documents/xxx.png这样的绝对路径。实测两个形式在多数机型上都能用但转换一下更稳尤其是在 iOS 上。完整的 iOS 保存链路async function saveImageIos(source) { let filePath; if (/^https?:\/\//.test(source)) { filePath await downloadToTemp(source); } else if (source.startsWith(data:image)) { filePath await saveToSandbox(source); } else { filePath source; } const normalized normalizePath(filePath); return new Promise((resolve, reject) { uni.saveImageToPhotosAlbum({ filePath: normalized, success: () resolve({ path: normalized }), fail: (err) { const msg err.errMsg || ; if (/denied|authorize/i.test(msg)) { reject(new Error(PHOTO_PERMISSION_DENIED)); } else { reject(new Error(msg || 保存失败)); } } }); }); }errMsg的匹配我用了正则而不是精确相等因为不同版本的 iOS 和不同版本的 HBuilderX 返回的文案不完全一样用包含匹配更皮实。6. 跨端统一封装与常见问题速查6.1 一个 saveImage 函数收口三端把前面几块拼起来主入口大概长这样export async function saveImage(options) { const { url, path, filename } options; // #ifdef H5 if (url) { if (isWechat()) { throw new Error(WECHAT_NO_DOWNLOAD); } try { await downloadByCanvas(url, filename); } catch (e) { // 跨域失败时退化成直接开新窗口 window.open(url, _blank); } return { path: }; } if (path path.startsWith(data:image)) { downloadByBase64(path, filename); return { path: }; } throw new Error(INVALID_SOURCE); // #endif // #ifdef APP-PLUS const osName uni.getSystemInfoSync().osName; if (osName android) { return saveImageToAlbumAndroid(url || path); } if (osName ios) { return saveImageIos(url || path); } throw new Error(UNSUPPORTED_PLATFORM); // #endif }入口层只做三件事判断平台、归一化图片源、分发到具体实现。这样业务代码里只需要saveImage({ url: https://cdn.xxx.com/a.png })一行不需要关心底下发生了什么。错误码我也做了一层统一STORAGE_PERMISSION_DENIED、PHOTO_PERMISSION_DENIED、WECHAT_NO_DOWNLOAD这几个在业务层可以分别映射成不同的提示文案和引导按钮。比起直接抛原始错误信息这种方式让 UI 层的处理逻辑清晰很多。6.2 常见问题速查表实打实踩过的坑我都整理在这张表里了遇到问题先在表里对一遍能省不少时间。现象可能原因处理方式H5 点击无反应微信内核拦截下载展示图片引导长按保存H5 控制台报 Tainted canvases图片跨域且未配 CORS服务端加Access-Control-Allow-OriginH5 下载的是 HTML 文件图片地址 404 返回了错误页下载前先校验statusCodeAndroid 相册里找不到图片图片写进了私有目录改用saveImageToPhotosAlbumAndroid 权限弹窗不出现用户勾了不再询问引导跳转到应用设置页Android 10 以上申请权限失败分区存储下不需要该权限版本判断前置跳过申请iOS 图片保存成功但打不开base64 前缀未剥离writeAsBinary前先剔除 data URIiOS 调用相册接口闪退权限描述键名缺失或拼错检查 Info.plist 配置相册保存成功但提示失败errMsg匹配过于严格用包含匹配而非精确相等6.3 几个我踩过的坑与实操心得第一个坑跟uni.downloadFile的临时路径有关。早期我直接把下载回来的tempFilePath存进 Vuex想着后面还能复用结果用户切到后台再回来安卓上这个路径下的文件已经被系统清理掉了保存相册时拿到的是一张 0 字节的空文件。后来的做法是临时路径用完即弃需要持久保留就走uni.saveFile转存或者干脆不保留每次要保存都重新下载。第二个心得是关于权限申请的时机。我一开始把权限申请放在页面onLoad里用户还没点保存按钮就先弹窗转化率极低——很多人一进页面看到要权限就退出去了。后来改成点击保存时再申请用户有明确意图的时候同意率高很多。这个改动对整体成功率的影响比任何代码优化都大值得专门拿出来说。第三个坑是 iOS 上uni.saveImageToPhotosAlbum的filePath传相对路径时部分机型上会失败但不报错success回调正常触发相册里却没有图。我排查了很久才定位到是路径格式问题后来统一走convertLocalFileSystemURL转换就再没出过。这类静默失败最难查因为代码逻辑看起来完全正确只能靠真机对比才能发现。还有一个经验是关于图片格式的。uni.saveImageToPhotosAlbum保存 webp 格式的图片时在部分安卓机上会失败或者保存成无法打开的损坏文件因为底层媒体扫描对 webp 的支持不完整。稳妥的做法是在业务层约束只保存 jpg 和 png如果上游给的是 webp先用 canvas 转一次再保存。这个转换在 H5 端顺手就能做在 App 端要用uni.compressImage或者canvasToTempFilePath处理。最后分享一个调试技巧。三端表现不一致的时候我习惯先在电脑浏览器里验证 H5 逻辑再用 Android 模拟器验证权限分支最后上真机跑 iOS。模拟器上 iOS 的相册权限行为跟真机不完全一样特别是有限访问这一档模拟器上根本模拟不出来必须真机测。项目里如果有多台不同系统版本的安卓测试机尽量覆盖 Android 9、10、12 这三个大版本基本能覆盖权限模型的所有分支。