离线页HTML在混合应用中易出兼容问题，因file://协议下Service Worker不可用，WebView内核碎片化导致HTML解析、路径解析、ES语法、DOM操作等多环节失效，必须严格遵循DOCTYPE首行、lang声明、双引号属性、同步脚本、绝对路径五条底线规则。
离线页 HTML 为什么在混合应用里容易出兼容问题
混合应用（如 Cordova、Capacitor、WebView 容器）中，离线页的 HTML 往往直接从本地文件系统加载（file:// 协议），而 Service Worker 只能在 https 或 localhost 下注册——这意味着你写的离线缓存逻辑根本不会生效，但 HTML 本身却要承担“断网兜底”职责。这时候，HTML 代码质量就不是“写得漂亮”的问题，而是“能否被 WebView 正确解析并渲染”的问题。
常见现象包括：document.querySelector 返回 null、fetch 报 Failed to execute 'fetch' on 'Window': Failed to parse URL、CSS 里的相对路径失效、import 语句静默失败、甚至整个 不渲染。
- WebView 内核版本碎片化严重（尤其 Android 低版本 WebKit/Chrome WebView），对 HTML5 特性支持不一
-
file://下跨域限制更严：XHR/fetch 默认禁用，localStorage可能被禁用或清空 - 未声明
DOCTYPE或lang时，部分 WebView 会降级到 Quirks Mode，导致盒模型错乱 - 内联
style或script中用了 ES6+ 语法（如箭头函数、可选链），老 WebView 直接报错中断执行
离线页 HTML 必须强制遵守的五条底线规则
这些不是“建议”，是混合应用离线页能跑起来的前提。任何一条不满足，都可能在某台设备上白屏或样式崩坏。
-
<!DOCTYPE html>必须存在且独占首行，不能有 BOM 或前置空格 -
<html lang="zh-CN">必须显式声明，避免屏幕阅读器和某些 WebView 的 fallback 行为 - 所有属性值必须用双引号包裹：
<img src="logo.png" alt="离线提示">，单引号或无引号在部分 WebView 里解析失败 - 禁止使用
async/defer加载关键 JS ——file://下资源加载顺序不可靠，应改用<script>...</script>同步内联或按需document.write注入 - 所有 CSS/JS 路径必须为绝对路径（以
/开头），例如<link href="/css/offline.css" rel="stylesheet">；相对路径（./css/、css/）在不同入口 HTML 下解析基准不同，极易 404
WebView 环境下离线页的 JS 兼容性收缩策略
你不能假设用户手机里的 WebView 支持 Promise、fetch 或 class。离线页的 JS 必须是“最小可行兼容体”。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- ES5 是安全基线：避免箭头函数、模板字符串、解构赋值；用
var替代let/const - 网络检测不用
navigator.onLine（它在file://下常返回true却实际断网），改用定时Image或XMLHttpRequest探活（如new Image().src = '/health.png?'+Date.now()） - DOM 操作前必须判空：
if (document.body) { ... }，因为某些 WebView 会在 DOM 尚未 ready 时就执行 script - 避免依赖
serviceWorkerAPI —— 在file://下navigator.serviceWorker是undefined，直接访问会报错；加if ('serviceWorker' in navigator)保护 - 第三方库必须打包为 IIFE + UMD，且明确指定目标浏览器版本（如 Babel target:
{"chrome":"49", "android":"4.4"}）
离线页 HTML 的结构与资源组织陷阱
混合应用里，离线页往往被打包进 APK/IPA，路径层级固定但引用关系易错。一个看似简单的 <img src="icon.png"> 就可能因构建工具路径重写或 WebView 加载机制失效。
- 所有静态资源（图片/CSS/JS）必须放在根目录或明确子目录（如
/assets/），并在 HTML 中用完整路径引用；不要依赖构建时的 public 目录映射逻辑 - 避免在 HTML 中硬编码版本号（如
app.js?v=1.2.3），混合应用更新包时无法自动刷新；改用时间戳或构建哈希注入（如<script src="/js/app.js?build=20260630"></script>） - 离线页的
<head>里禁止出现<meta http-equiv="refresh">或跳转脚本，某些 WebView 会拦截并触发异常重定向 - 如果使用内联 SVG，确保
<svg>标签闭合完整（</svg>），部分旧 WebView 对自闭合<svg/>解析失败 - 字体文件（
@font-face）优先用 base64 内联或 WOFF（非 WOFF2），Android 4.x WebView 不支持 WOFF2
离线页的 HTML 不是“写一次、到处跑”的产物，它是针对具体 WebView 环境反复打磨的产物。最常被忽略的是：路径是否真实存在、JS 是否真能执行完、以及页面是否在所有目标设备上至少能显示一行文字。其他都是锦上添花。
