uni-app如何通过URL下载网络图片

在前端开发内容学习中，uni-app如何通过URL下载网络图片是常见主题。很多人在阅读时会遇到概念分散、步骤不清和注意点难以归纳的问题。本文按照基础概念、操作流程和关键细节，对相关内容进行整理。

uni.downloadFile返回的tempFilePath是仅当前会话有效的临时文件路径（如uni-file://xxx.jpg），非永久路径，不可直接用于src或a.href，离开success回调即失效。

uni.downloadFile 是唯一能直接通过 URL 下载网络图片的最新 API，但它不等于“保存到相册”或“触发浏览器下载”——它只负责把图片拉到本地临时路径，后续动作必须手动衔接。

uni.downloadFile 调用后，tempFilePath 是什么？

它是一个仅在当前会话有效的临时文件路径（如 uni-file://xxx.jpg），不是永久路径，也不能直接用于 src 或 a.href。不同平台表现差异大：

• 微信小程序：可直接传给 uni.saveImageToPhotosAlbum 保存到相册
• App 端（iOS/Android）：同样支持 uni.saveImageToPhotosAlbum，但 Android 需提前申请 WRITE_EXTERNAL_STORAGE 权限，iOS 需检查相册授权状态
• H5 端：tempFilePath 无效，无法使用，必须换方案（见下一条）

H5 端不能用 uni.downloadFile 下载图片？

• 跨域图片：加 crossOrigin="anonymous" 后 draw 到 canvas，再用 canvas.toDataURL() 转 base64，最后用 <a download> 触发下载
• 同源图片：可直接用 fetch + blob + URL.createObjectURL() 生成可下载链接
• 注意：微信内置浏览器（H5）不支持自动下载，只能提示用户「长按图片保存」

为什么下载后图片打不开或报错「文件不存在」？

常见原因不是代码写错，而是路径或时机问题：

• res.tempFilePath 只在 success 回调里有效，离开回调就失效 —— 别把它存到 data 里异步用
• 部分安卓机型对文件名含特殊字符（如中文、空格、#）敏感，建议用 encodeURIComponent 处理原始 URL 后截取后缀，或统一用 .png
• 微信小程序中，如果图片是 HTTPS 但证书不合规，statusCode 可能为 0，res.tempFilePath 为空，需在 success 里加 if (!res.tempFilePath) 判断
• App 端 debug 模式下临时路径可查，但真机打包后路径不可见，别依赖日志打印路径去调试

真正麻烦的从来不是“怎么下”，而是“下完之后在哪、怎么用、用户能不能看到、权限有没有被拒”。跨端图片下载本质是三套逻辑：小程序走 saveImageToPhotosAlbum，App 端补权限校验，H5 端彻底弃用 uni.downloadFile 改用 canvas/fetch。漏掉任一环节，用户点下去就静默失败。