当前稳定可靠的离线页面方案是 Service Worker + Cache API；排查需依次检查注册激活状态、HTTPS环境、缓存资源写入、fetch拦截逻辑及资源路径完整性。
离线页面在 HTML5 中主要依赖 Application Cache（已废弃） 或更现代的 Service Worker + Cache API 实现。当前稳定可靠的方案是后者。排查离线功能失效，关键不在“有没有写代码”，而在于“是否按浏览器生命周期严格执行缓存策略”。以下是四个最常出问题的环节及对应排查动作：
检查 Service Worker 注册与激活状态
未注册、注册失败或处于 waiting 状态，都会导致离线逻辑完全不生效。
- 打开开发者工具 → Application → Service Workers，确认右侧显示“Active”且无红色警告；若显示“Waiting”，需调用
self.skipWaiting()并刷新两次 - 检查注册脚本是否在 HTTPS 环境下运行（本地
localhost允许，但http://127.0.0.1或文件协议file://不支持） - 查看 Console 是否报错：如
Failed to register a ServiceWorker，大概率是 JS 脚本路径 404 或语法错误中断执行
验证缓存资源是否真实写入 Cache Storage
即使 Service Worker 安装成功，若 caches.open().put() 执行出错或资源返回非 200 响应，缓存就为空。
Wechat Article Html
下载
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。
- 在 Application → Cache Storage 中展开对应缓存名，确认有预期的 HTML、CSS、JS、字体、图片等条目
- 重点检查 HTML 主页是否被缓存——很多模板只缓存了 assets，却漏掉
/index.html，导致离线时加载空白页或 Network Error - 在 Network 面板勾选 “Offline”，刷新页面，观察哪些资源仍显示“from cache”，哪些触发“failed”或“pending”
排查 fetch 事件拦截与响应逻辑漏洞
离线时页面能否正常加载，取决于 fetch 事件中是否正确回传缓存内容，而非直接 return fetch(event.request)。
立即学习“前端免费学习笔记（深入）”；
- 确保
event.respondWith()被完整包裹，且内部逻辑覆盖所有情况：缓存命中 → 返回缓存；缓存未命中 + 在线 → 回源并缓存；缓存未命中 + 离线 → 返回 fallback 页面（如/offline.html） - 避免在
fetch中使用async/await却忘记returnPromise，常见写法错误：event.respondWith( async () => { ... } )❌ 应为event.respondWith( (async () => { ... })() )✅ - 动态资源（如 API 接口）不应盲目缓存，否则可能返回过期数据；建议对非 HTML 资源加
cache-control: no-store响应头，或在 SW 中显式跳过
留意页面内资源引用的相对路径与完整性
HTML 文件虽被缓存，但其中引用的 CSS、JS、图片若路径错误或未纳入缓存列表，仍会加载失败。
- 打开缓存的 HTML，在 Sources 面板中右键 → “Open in new tab”，单独访问该 HTML，看是否出现 404 的资源请求
- 检查所有
<link rel="stylesheet">、<script src></script>、<img src alt="HTML5 中离线页面开发常见坑点怎么排查才能确保稳定运行" >的路径是否为绝对路径（推荐）或相对于 HTML 的正确相对路径 - 特别注意图标（
<link rel="icon">）、Web Font（@font-face中的 url）、SVG Sprite 引用，这些容易被忽略，却会导致 UI 断裂
