离线HTML必须声明自身为缓存目标，否则将白屏；需删除manifest属性和applicationCache代码；清单文件须更新字节内容并返回正确MIME类型；WebView加载应绕过file://协议。
离线HTML中不能依赖 window.applicationCache
这个 API 在 Chrome 94+、Firefox 85+ 已被彻底移除，调用 applicationCache.update() 会直接报 TypeError: Cannot read property 'update' of undefined，且整个离线逻辑静默失效。很多老项目还留着 manifest="cache.manifest" 属性，浏览器会尝试加载但失败，控制台出现无意义告警。
实操建议：
- 立即删除所有 HTML 中的
manifest属性（包括） - 删掉所有
window.applicationCache相关代码，不要试图 polyfill —— 它不是兼容性问题，而是标准废弃 - 检查构建产物（如 dist 目录），确认没有残留的
.appcache文件或引用
离线HTML必须声明自身为缓存目标
即使你把 JS/CSS/图片都列进缓存清单，如果 index.html 没出现在 CACHE: 段里，它就不会被缓存，导致“离线能打开，但打开就是白屏”——因为浏览器仍试图联网加载 HTML。
常见错误现象：
立即学习“前端免费学习笔记（深入）”；
- 本地起服务访问正常，但用
file://打开就空白或 404 - App 内 WebView 加载离线包后，首次显示正常，杀进程重启后页面无法渲染
实操建议：
- 确保
CACHE:段第一行就是当前 HTML 文件路径，例如：index.html或/app/index.html（路径需与实际请求路径一致） - 路径区分大小写，
Index.html和index.html是两个资源 - 避免在
NETWORK:段写*，否则 HTML 会被排除出缓存
缓存清单文件本身必须触发更新机制
改了 JS 文件、加了新 CSS，但用户设备上永远不更新？根本原因不是资源没变，而是 cache.manifest 文件字节内容没变。浏览器只对比清单文件的原始字节，空格、注释、换行都算数。
实操建议：
- 每次发布前，必须改动清单文件任意一行，比如加
# v20260701或改一个空格 - 服务器必须返回正确的 MIME 类型：
Content-Type: text/cache-manifest，否则浏览器直接忽略该文件 - 开发阶段用
chrome://appcache-internals/查看“Last updated”时间是否变化，没变说明根本没拉新清单
WebView 加载离线 HTML 时路径解析容易错乱
用 file:// 协议加载本地 HTML 时，所有相对路径（如 src="js/app.js"）默认按文件系统路径解析，但 Android/iOS WebView 对 file:// 有严格限制：JS 无法发起跨协议跳转，fetch 读本地 JSON 会被拦截，localStorage 也因同源策略失效。
真正可行方案不是修 HTML，而是绕过 file://：
- Android：用
webView.loadDataWithBaseURL("https://app.local/", htmlStr, "text/html", "UTF-8", null)，再重写shouldInterceptRequest拦截https://app.local/js/app.js并返回 assets 流 - iOS：注册自定义 scheme（如
applocal://），配合WKURLSchemeHandler拦截请求，base URL 必须带协议和域名，不能是空字符串或http:// - 切记：仅靠前端改
<base href="...">或location.href无法突破协议隔离
关键点不在 HTML 写得多规范，而在于它运行的上下文是否可控。离线 HTML 的质量整改，本质是把“静态文件交付”升级为“可控资源加载闭环”——前端负责结构与降级逻辑，原生层负责路径映射与拦截响应。漏掉任一环，都会在特定机型或系统版本上突然失效。
