App端离线缓存应优先使用uni.getFileSystemManager()，它跨平台兼容性好、支持完整文件操作，且在iOS/Android/H5三端行为一致；需配合版本控制、路径规范（如iOS要求__APP__/前缀）及网络状态兜底策略。
uni-app App端离线缓存该用哪个 API？
App端（iOS/Android）不能靠 localStorage 或 cacheStorage 做可靠离线资源缓存，必须走原生层能力。uni-app 提供的 uni.getNetworkType 和 uni.onNetworkStatusChange 只能监听网络状态，不解决资源缓存问题。真正起作用的是 uni.downloadFile + uni.saveFile 配合本地文件路径管理，再结合 plus.runtime.install（仅 H5+ 环境）或自定义原生插件——但绝大多数项目应优先使用 uni.getFileSystemManager() 管理离线资源。
实操建议：
-
uni.getFileSystemManager()是 App 端最稳定、跨平台兼容性最好的离线文件操作入口，支持writeFile、readFile、getFileInfo等，且在微信小程序、App、H5 三端行为一致（App端写入路径为_doc或_www目录） - 避免用
uni.setStorage存大量 HTML/JSON 数据——容量小（通常 10MB 限制）、无版本控制、无法直接作为src加载图片或 HTML - 首次启动时主动触发资源预下载，不要等用户点开才下载；下载失败需降级 fallback 到内置默认资源（如本地打包的
static/offline.html）
断网时怎么让页面正常显示？
单纯检测 networkType === 'none' 不够，因为页面可能已加载完成但后续 AJAX 失败，或图片资源未缓存导致空白。关键在于「资源加载链路」全部可控：HTML、JS、CSS、图片、接口数据都要有兜底。
常见错误现象：img 标签 src 404、axios.get 报 Network Error、Vue 组件 mounted 后白屏
实操建议：
- 所有远程图片统一走封装函数
loadCachedImage(src)，先查uni.getFileSystemManager().getFileInfo是否存在本地副本，存在则返回file://路径；不存在则 fallback 到占位图/static/img/placeholder.png - 接口请求必须带
cache: true参数（需后端配合返回Cache-Control），并在拦截器里捕获err.message === 'Network Error'时，自动读取上一次成功缓存的 JSON 文件（路径如uni.getFileSystemManager().readFile({filePath: '/wxfile/cache/user.json'})） - 整个页面 HTML 不要依赖服务端渲染；App 端首页建议用纯静态
index.html+ Vue 挂载，断网时直接展示缓存过的 DOM 结构，而非跳转到一个“网络错误页”
如何给离线资源加版本控制？
没版本号的缓存等于没缓存——用户更新 App 后，旧缓存文件还在，新逻辑读不到新数据，或更糟：读到旧版 HTML 导致 JS 报错。
实操建议：
- 每次资源变更（如
news-list.json更新），生成唯一 hash 值，存为cache-manifest.json，内容类似：{"version":"a1b2c3","files":["news-list.json","banner.jpg"]} - 启动时先读
cache-manifest.json，对比当前版本号与本地存储的lastVersion；不一致就清空旧缓存目录（uni.getFileSystemManager().readdir+removeFiles），再重新下载 - 不要用时间戳当 version（如
Date.now()），会导致每次启动都重下；也不要用 Git commit id（CI 构建时不可控），推荐构建时由脚本注入 SHA256 或 MD5
App 端离线缓存最容易被忽略的坑
很多团队卡在“看起来能缓存，但上线后失效”，根本原因不是代码写错，而是路径和权限没对齐。
关键细节：
- iOS 上
file://路径必须以__APP__/开头才能被 WebView 正确加载，否则图片/HTML 显示空白；正确路径示例：file:///var/mobile/Containers/Data/Application/xxx/Documents/__APP__/cache/banner.jpg - Android 10+（API 29+）默认禁用外部存储，
uni.getFileSystemManager()的temp目录不可写，必须用plus.io.resolveLocalFileSystemURL('_doc')获取可信路径（仅 H5+ 支持），或改用plus.cache（DCloud 官方缓存模块） - 调试时真机连电脑，USB 调试会干扰
file://协议加载，务必断开 USB、用二维码安装包测试，否则永远复现不了线上问题
离线能力不是“加个缓存开关”就能生效，它要求你把每个资源加载路径、每个网络请求分支、每个文件写入时机都变成显式可控的状态。最麻烦的从来不是代码量，而是边界条件——比如用户在下载中途切后台，或磁盘满时 writeFile 静默失败。
