更新记录

1.0.0（2026-09-07）下载此版本

初始化

平台兼容性

uni-app(3.8.3)

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
-	√	-	-	√	√	√	√	√

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
-	-	-	-	-	-	-	-	-	-	-	-

lv-image-cache 图片本地缓存

App（Android / iOS）/ 鸿蒙端网络图片本地缓存插件。零配置：插件放进 uni_modules 后，把 image 标签换成 cache-image 即可，不需要改 main.js 或 pages.json。

用法

<!-- 改造前 -->
<image class="icon" mode="aspectFit" :src="qny_url + 'index/more.png'"></image>

<!-- 改造后：只改标签名，其余属性原样保留 -->
<cache-image class="icon" mode="aspectFit" :src="qny_url + 'index/more.png'"></cache-image>

批量替换（HBuilderX 全局搜索替换，勾选正则）：

<image → <cache-image
</image> → </cache-image>

工作原理

组件优先用 plus.downloader 把图片下载到应用私有目录 _doc/image-cache/；无 plus 环境（如鸿蒙）自动降级为 uni.downloadFile + uni.saveFile。
索引（url -> 本地路径 / 大小 / 时间）持久化在 Storage，App 重启后仍命中。
命中缓存时直接渲染本地文件，不发起网络请求；未命中时先等待下载，超过 fallbackDelay 自动先显示网络图，避免长时间空白。
本地文件失效（被系统清理）时自动删除缓存记录并回退网络地址，只重试一次，不会死循环。
下载 / 保存 / 取大小任一环节失败都回退为网络地址，绝不影响图片展示。

组件属性

属性	类型	默认值	说明
src	String	''	图片地址，网络地址参与缓存，本地路径 / base64 原样展示
mode	String	scaleToFill	同 image 组件
cache	Boolean	true	是否启用本地缓存，频繁变动的图片建议设为 false
placeholder	String	''	加载中占位图
error-src	String	''	加载失败占位图，缺省回退 placeholder
lazy-load	Boolean	false	同 image 组件
webp	Boolean	false	同 image 组件
show-menu-by-longpress	Boolean	false	同 image 组件
fade	Boolean	false	加载完成后淡入（默认关闭，优先保证图片一定可见）
duration	Number	300	淡入时长（毫秒）
fallback-delay	Number	2000	等待下载的最长时间，0 表示立即显示网络图

事件：@load / @error / @click（含 .stop 等修饰符），用法与 image 组件一致。

其他未声明的属性（如 class、style、data-*）会原样透传给内部 image，可直接使用。

升级后会自动清空缓存

覆盖安装（Android 整包安装、iOS App Store 更新）时，应用私有目录和 Storage 都会保留，缓存不会自动消失。若新版本更换了图片但文件名不变，用户会继续看到旧图，最长 7 天。

因此插件默认开启版本隔离：启动时比对 App 版本号，发生变化则清空全部缓存（索引 + 文件），确保升级后展示的是新资源。取不到版本号时保守跳过，不会误删。

场景	结果
同版本重启 / 热更新（版本号未变）	缓存保留
整包升级 / App Store 更新（版本号变化）	缓存清空，重新下载
卸载重装	缓存本就随应用删除
取不到版本号	保守跳过，不清空

可选：调整缓存策略

默认 7 天有效期、100MB 总容量、800 个文件、5 个并发，一般无需修改。如需调整，在任意位置调用一次即可（例如在 App.vue 的 onLaunch）：

import { configureImageCache } from '@/uni_modules/lv-image-cache/utils/image-cache.js'

configureImageCache({
  maxAge: 7 * 24 * 60 * 60 * 1000, // 有效期，0 表示永不过期
  maxSize: 100 * 1024 * 1024, // 总容量，0 表示不限制
  maxCount: 800, // 文件数量上限，0 表示不限制
  concurrency: 5, // 并发下载数
  autoClearOnUpgrade: true // 升级后自动清空缓存，设为 false 可关闭
})

若 uni.getSystemInfoSync() 取不到版本号（少数机型），而你通过 plus.runtime.getProperty 拿到了准确版本，可这样补上：

import { setAppVersion } from '@/uni_modules/lv-image-cache/utils/image-cache.js'

plus.runtime.getProperty(plus.runtime.appid, (info) => {
  setAppVersion(info.version) // 版本变化时会清空缓存
})

可选：JS API

import {
  getCachedImage, // url -> Promise<本地路径>，失败返回原 url
  getCachedPath, // url -> 本地路径（同步命中，未命中返回 ''）
  preloadImages, // 预加载一批图片
  invalidateCache, // 使单张图片缓存失效
  removeExpiredCache, // 清理过期缓存，返回清理数量
  clearImageCache, // 清空全部图片缓存
  getImageCacheInfo // { size, count }
} from '@/uni_modules/lv-image-cache/utils/image-cache.js'

注意事项

缓存文件写在应用私有目录，卸载 App 会随之删除，用户不可见。
频繁变化、或 URL 不变但内容会变的图片请加 :cache="false"（如用户头像、验证码、临时上传文件）。本项目已在 pages/mine/mine.vue、pages/mine/user/personal-Information.vue 的头像上做了处理。
首次接入后，建议在真机（Android / iOS / 鸿蒙）各运行一次，确认本地路径渲染正常。