1. 离线应用设计目标与技术选型

1.1 离线能力需求分析

在离线应用的初期阶段，明确离线可用的核心页面和资源是关键。通常需要优先缓存首页、主样式表、核心脚本以及关键图片，以确保在网络不可用时仍能呈现可用界面。此阶段的关键点包括离线首屏体验、缓存粒度控制以及对大文件的分段缓存策略。

为了实现可预测的离线行为，应该把资源分组，高优先级资源先缓存，低优先级资源后缓存或按需请求。资源分级缓存策略能显著提升首次离线访问时的可用性，并降低缓存策略的复杂度。

// 典型的离线策略入口点示例（伪代码）
const OFFLINE_RESOURCES = ['/index.html','/styles/main.css','/scripts/app.js','/images/logo.png'
];

1.2 兼容性与渐进增强

在现实场景中，浏览器对离线能力的支持存在差异。渐进增强原则要求在有离线能力的浏览器上提供离线体验，在没有离线能力的浏览器上仍然能正常工作。优雅降级和资源回退页面是实现的核心手段。

技术选型上，优先采用Service Worker + Cache API的现代方案，但也要保留对老浏览器的回退路径，例如在需要时提供一个简单的离线页面。下面的代码演示了两种实现路径的共存思路。

<!-- HTML 引用 manifest（现代方案，见第四节） -->
<link rel="manifest" href="/manifest.json">
</head>

1.3 用户体验指标与监控

离线体验的核心指标包括离线可用性覆盖率、首屏离线渲染时间、以及离线资源的缓存命中率。通过监控这些指标，可以持续优化缓存策略与资源清单。

在开发阶段，应建立一个离线测试用例集，覆盖常见用户行为（打开首页、切换到离线模式、访问图片和交互脚本等），以确保离线路径的稳定性和回退机制的可用性。

2. HTML5离线实现核心：Manifest与AppCache

2.1 Manifest 工作原理与写法

HTML5 应用缓存（AppCache）通过一个 manifest 文件把需要离线的资源列出，浏览器在首次加载后将这些资源缓存起来。CACHE、NETWORK、FALLBACK三大部分决定了缓存行为：CACHE指定离线资源、NETWORK允许网络获取、FALLBACK在网络不可用时的降级页面。

注意：AppCache 已进入弃用阶段，现代应用更推荐使用 Service Worker。但了解 manifest 的工作原理有助于理解离线缓存的演进路径。下面展示一个简单的 AppCache 声明示例。

CACHE MANIFEST
# 版本: 1.0
CACHE:
index.html
styles.css
scripts/app.js
images/logo.pngNETWORK:
*FALLBACK:
/ /offline.html

2.2 AppCache 的链接与资源清单示例

为了使浏览器在离线时仍能访问页面，需要在 HTML 文档中指向 manifest 文件。manifest 属性一旦设置，浏览器将自动处理缓存过程。下述示例展示了如何在文档头部引入 AppCache 清单。

离线演示

重要点：AppCache 的资源清单需保持与上线资源的严格对应，任何变更都需要重新发布 manifest 文件并让浏览器重新下载缓存。

2.3 限制与迁移建议

AppCache 具有一些已知局限，例如对动态请求、跨域资源的缓存策略支持不足，以及缓存更新的复杂性。迁移到 Service Worker是当前主流做法，能实现更细粒度的缓存控制和更灵活的离线策略。

若仍需要兼容性测试，请把 AppCache 与现代实现并行开发，并在上线前明确告知团队的技术路线与维护成本。以下代码块展示了迁移思路中的一个过渡点：保留老缓存入口，同时准备 Service Worker 的注册逻辑。

if ('serviceWorker' in navigator) {window.addEventListener('load', function() {navigator.serviceWorker.register('/service-worker.js').then(function(reg) { console.log('SW registered (legacy path).', reg); }).catch(function(err) { console.error('SW registration failed', err); });});
}

3. 现代离线实现：Service Worker 与 Cache API

3.1 Service Worker 基础

Service Worker 是实现离线能力的核心：它作为独立于网页的脚本，在后台运行，拦截网络请求并进行缓存处理。install、activate、fetch三个阶段决定了缓存的创建、更新与数据提供的时序。

为了获得稳定的离线体验，通常在 install 阶段完成对关键资源的预缓存，在 fetch 阶段对资源进行命中与回退处理，并在 activate 阶段清理历史缓存。

// service-worker.js
const CACHE_NAME = 'app-cache-v2';
const URLs_TO_CACHE = ['/','/index.html','/styles/main.css','/scripts/app.js','/images/logo.png'
];self.addEventListener('install', event => {event.waitUntil(caches.open(CACHE_NAME).then(cache => cache.addAll(URLs_TO_CACHE)));self.skipWaiting();
});

3.2 缓存策略：Cache-first、Network-first、Stale-while-Revalidate

不同场景下可选的缓存策略会影响应用的响应时间和数据的新鲜度。Cache-first适合静态资源，优先从缓存读取再请求网络；Network-first适合需要最新数据的页面；Stale-while-Revalidate在缓存和网络之间做折中，先返回缓存，再异步更新。

以下示例实现了一个简单的 Cache-first 策略，遇到未缓存的请求才从网络获取，并将新响应更新缓存。

self.addEventListener('fetch', event => {event.respondWith(caches.match(event.request).then(cacheResp => {if (cacheResp) return cacheResp;return fetch(event.request).then(netResp => {if (netResp && netResp.ok) {caches.open(CACHE_NAME).then(cache => cache.put(event.request, netResp.clone()));}return netResp;});}).catch(() => {// 离线兜底return caches.match('/offline.html');}));
});

3.3 安全性、版本控制与更新策略

为避免旧版本缓存阻塞更新，需要在 activate 阶段清理过期缓存，并在新版本就绪时立刻生效。此外，跨站请求与第三方资源的缓存策略要格外谨慎，确保不会暴露敏感数据。

常见做法包括：在新的 Service Worker 注册后使用 skipWaiting、clients.claim 让页面立即由新 SW 控管、以及为每次版本变更改名缓存标识符（如 app-cache-v3）。

self.addEventListener('activate', event => {const cacheWhitelist = [CACHE_NAME];event.waitUntil(caches.keys().then(keys => Promise.all(keys.map(key => {if (!cacheWhitelist.includes(key)) return caches.delete(key);}))));return self.clients.claim();
});

4. Web App Manifest 与离线体验的集成

4.1 manifest.json 字段解释

Web App Manifest 是用于描述离线安装体验的 JSON 文件，帮助浏览器以“应用模式”启动网页。重要字段包括 name、short_name、start_url、display、background_color、theme_color，以及 icons，用于离线设备的离线图标与启动画面。

通过将 manifest.json 与应用主体分离，可以在不修改页面代码的情况下更新图标与启动页体验。以下是一个典型的 manifest.json 结构。

{ "name": "离线应用演示","short_name": "离线演示","start_url": "/index.html","display": "standalone","background_color": "#ffffff","theme_color": "#4CAF50","icons": [{"src":"/icons/icon-192.png","sizes":"192x192","type":"image/png"},{"src":"/icons/icon-512.png","sizes":"512x512","type":"image/png"}]
}

4.2 manifest.json 与 service worker 的协同

两者的协同核心在于：页面加载时通过 link 标签引入 manifest，而离线能力通过 Service Worker 提供的缓存能力实现。使用 manifest 提供的图标和启动页信息，可以提升离线安装后的第一屏体验。

在实际项目中，确保服务端对 manifest.json 的正确 MIME 类型和缓存策略进行配置，避免浏览器因为缓存了旧的 manifest 文件而导致界面启动异常。

<link rel="manifest" href="/manifest.json">

4.3 启动体验与离线资源的优先级

在离线状态下，优先渲染与启动相关的页面与资源，例如 start_url 对应的页面、核心样式与字体、以及唯一标识应用的离线图标。这样可以确保用户在离线时仍能快速进入应用。

为了提升用户感知速度，可以在页面加载阶段为离线资源提供短路路径，例如在未联网时直接呈现离线页模板（offline.html），并在网络恢复后再进行背景更新。

5. 全流程实战：从零到上线

5.1 代码结构与资源清单

完整的离线应用通常需要清晰的资源清单和代码分层：index.html、styles、scripts、images等要在离线策略中覆盖。将核心入口、离线页、以及服务工作者脚本放在明确的目录中，便于后续维护与版本管理。

在设计阶段，建立一个可追踪的资源清单表格，标注资源的优先级、缓存时间与变更版本，确保每次上线都可回溯。

项目结构示例
/
├─ index.html
├─ offline.html
├─ manifest.json
├─ service-worker.js
├─ styles/
│  └─ main.css
├─ scripts/
│  └─ app.js
└─ images/└─ logo.png

5.2 资源清单与自动化构建

通过构建脚本自动生成资源清单，有助于避免手工维护的错误。常见做法是：在构建阶段扫描静态资源目录，输出用于缓存的清单文件，并在 service worker 或 manifest 中引用这些清单。

示例目标：在构建完成后，生成一个包含所有需要缓存资源的数组，并将其注入 service-worker 或主动发布 manifest。

// 伪构建脚本输出示例
const RESOURCES = ['/','/index.html','/styles/main.css','/scripts/app.js','/images/logo.png'
];
// 将 RESOURCES 写入 service-worker.js 的缓存名单中

5.3 触发离线更新与调试测试

离线体验的一个关键点是缓存的版本控制。通过在 service worker 中维护 CACHE_NAME 的版本号，当版本改变时能够触发缓存更新与旧资源的清理。此外，开发阶段应使用浏览器开发者工具的离线模式进行严格测试，确保在没有网络时应用仍可访问。

调试要点包括：注册与激活顺序、缓存命中率、离线兜底页面可用性，以及跳过等待与立即激活的行为是否符合预期。

// 版本更新示例
const CACHE_NAME = 'app-cache-v3';
self.addEventListener('activate', event => {event.waitUntil(caches.keys().then(keys => Promise.all(keys.map(key => key !== CACHE_NAME && caches.delete(key)))));return self.clients.claim();
});

5.4 上线前的离线体验审核

上线前应进行一次完整的离线体验审核，覆盖以下要点：首页离线可用性、资源不足时的降级页、字体和图片的可离线性、以及更新后对旧版本的平滑迁移。同时，确保应用的离线能力不会阻塞网络条件良好时的性能表现。

最终目标是实现一个稳定的离线优先路径，同时提供良好的网络优先回退策略，以确保用户在不同网络环境下都能获得一致的使用体验。