正文

html5离线缓存应用实战手把手教你做离线网页与pwa开发离线存储方案与manifest配置详解

/0 浏览量
1009

嘿，朋友，我是 Agnes。今天咱们不聊那些枯燥的理论，我要带你真正上手做点东西。你肯定有过这种尴尬时刻：在地铁里刷着喜欢的网页，突然信号格变空，页面瞬间报错，心情也跟着掉进谷底。或者你开发了一个很棒的小应用，结果用户没网就打不开，流失率直线上升。

其实，解决这个问题的方案早就就在我们手边了。很多人一听到“离线开发”就想到复杂的服务器配置，或者觉得 PWA（渐进式Web应用）是遥不可及的高级技术。但真相是，从 HTML5 的 App Cache（虽然已废弃，但原理重要）到现代的 Service Worker，再到 Manifest 文件，这一套组合拳打好了，你的网页就能像原生 App 一样，在没网的时候也能飞起来。

咱们今天就把这些技术揉碎了，手把手带你搭建一个真正的离线网页应用。我会用代码说话，用例子证明，让你不仅看懂，还能直接拿去用。

为什么我们需要离线能力？这不仅仅是“不报错”

首先，咱们得搞清楚，为什么现在的大厂都在推 PWA？除了用户体验，还有几个硬核原因。

第一，性能即正义。 哪怕网络很好，第一次加载一个重型网页也需要时间。如果你把资源缓存好了，第二次访问几乎是秒开。这带来的留存率提升是巨大的。

第二，流量成本。 对于很多用户，尤其是海外或流量昂贵的地区，能省一点是一点。离线可用的应用，天然节省了后续的带宽消耗。

第三，技术门槛的降低。 过去做个 App 得写 iOS 和 Android 两套代码。现在，一个 PWA 可以覆盖所有平台。你写一遍 HTML/CSS/JS，它在手机桌面上有图标，可以全屏运行，还能收到推送通知。

但这里有个关键的分水岭，我得先跟你讲清楚：HTML5 App Cache 已经死了，别再用它。 很多人还在网上搜到老教程，教你在 HTML 标签里加 manifest="app.manifest"，我劝你赶紧忘掉它。虽然它的原理很直观，但它有一个致命的 Bug：一旦缓存设定，极难更新，且不可逆。现代 Web 开发的标准答案是 Service Worker。

核心引擎：Service Worker 完全解析

Service Worker 是运行在浏览器后台的脚本，它独立于你的网页页面，能拦截和修改网络请求。你可以把它想象成一个“交通指挥官”，所有的 HTTP 请求都得经过它的手。

它的三大核心能力

  1. 离线缓存：预存资源，没网也能访问。
  2. 推送通知：即使用户关掉了页面，服务器也能发消息来。
  3. 后台同步：等网络恢复了，再把刚才没发出去的数据补发。

生命周期：理解它才能用好它

Service Worker 的生命周期有点复杂，但咱们用大白话来讲。

  • 注册（Registration）：你的网页决定是否启用 Service Worker。
  • 安装（Install）：Service Worker 启动，通常会在这个阶段把文件缓存起来。
  • 激活（Activate）：旧的 Service Worker 被清除，新的接管一切。
  • 监听（Fetch）：每次用户发请求，它都在后台盯着。

第一步：编写 Service Worker 脚本

咱们先建一个文件夹结构，这样你看得清楚：

my-offline-app/
├── index.html
├── style.css
├── app.js
├── sw.js          <-- 这是我们的 Service Worker
├── icons/
│   └── icon-192.png
│   └── icon-512.png
└── assets/
    └── data.json  <-- 我们想缓存的数据

现在，我们写 sw.js。这是整个离线的灵魂。

// 定义缓存的名称，每次改这个名字，浏览器就会认为是新的缓存，强制更新
const CACHE_NAME = 'offline-app-v1.2';

// 定义需要缓存的静态资源列表
const ASSETS = [
  '/',
  '/index.html',
  '/style.css',
  '/app.js',
  '/icons/icon-192.png',
  '/icons/icon-512.png'
];

// 1. 安装阶段：把资源塞进缓存
self.addEventListener('install', (event) => {
  console.log('[SW] Install event fired');
  
  // waitUntil 确保 Service Worker 在缓存完成之前不会被认为是“已安装”
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then((cache) => {
        console.log('[SW] Caching apps');
        return cache.addAll(ASSETS);
      })
      .then(() => {
        return self.skipWaiting(); // 跳过等待，立即激活
      })
  );
});

// 2. 激活阶段：清理旧缓存，释放空间
self.addEventListener('activate', (event) => {
  console.log('[SW] Activate event fired');
  
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames.map((cacheName) => {
          // 如果缓存名字不是当前的，就删掉它
          if (cacheName !== CACHE_NAME) {
            console.log('[SW] Deleting old cache:', cacheName);
            return caches.delete(cacheName);
          }
        })
      );
    }).then(() => {
      return self.clients.claim(); // 立即控制所有页面
    })
  );
});

// 3. 请求拦截阶段：核心逻辑
self.addEventListener('fetch', (event) => {
  // 我们只关心 get 请求，且只处理同源请求
  if (event.request.method !== 'GET') return;

  event.respondWith(
    caches.match(event.request)
      .then((cachedResponse) => {
        // 情况A：缓存里有，直接返回缓存（离线首选）
        if (cachedResponse) {
          console.log('[SW] Returning from cache:', event.request.url);
          return cachedResponse;
        }

        // 情况B：缓存里没有，去网络拿
        // 这里用 networkFirst 策略：先试网络，失败了再试缓存
        return fetch(event.request)
          .then((networkResponse) => {
            if (networkResponse && networkResponse.status === 200 && networkResponse.type === 'basic') {
              // 拿到网络响应后，顺手更新一下缓存，保证内容是最新的
              const responseToCache = networkResponse.clone();
              caches.open(CACHE_NAME)
                .then((cache) => {
                  cache.put(event.request, responseToCache);
                });
            }
            return networkResponse;
          })
          .catch(() => {
            // 情况C：网络也失败了，尝试返回一个离线兜底页面（如果是HTML请求）
            if (event.request.destination === 'document') {
              return caches.match('/offline.html');
            }
          });
      })
  );
});

代码写得有点长，但我给你拆解一下逻辑。你看那个 install 事件，它就像是在仓库里进货，把图片、CSS、JS 全部搬进去。activate 事件像是在大扫除，把以前过期的缓存扔出去。最关键是 fetch 事件，它像一个聪明的快递员：先看看仓库（缓存）有没有货？有就给你；没货就去店里（网络）买，买到了还得回来补一个库存，以防下次没网。

注意：我在代码里加了 self.skipWaiting() 和 self.clients.claim()。这是很多新手踩坑的地方。默认情况下，新装的 Service Worker 要等所有页面关闭才会生效。加上这两行，强制它立即接管，方便我们调试。

第二步：在网页中注册 Service Worker

有了脚本还不够，你得告诉浏览器：“嘿，我要用这个守护者。” 在 index.html 的 <head> 或者 <body> 末尾加上这段 JS：

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then((reg) => {
        console.log('[SW] Registration successful, scope is:', reg.scope);
      })
      .catch((err) => {
        console.log('[SW] Registration failed, err:', err);
      });
  });
} else {
  console.log('Browser does not support Service Workers.');
}

这时候，你打开开发者工具（F12），切换到 Application 面板，你应该能在 Service Workers 栏看到你的脚本状态是 “Activated”。

Manifest 文件：让网页“变身”为 App

光能离线还不够，用户得能在桌面上看到图标，点开来是全屏的，对吧？这就是 Web App Manifest 的作用。它是一个 JSON 文件，告诉浏览器：“我是个应用，别按普通网页处理我。”

配置文件详解

我们在根目录创建 manifest.json：

{
  "name": "Agnes离线助手",
  "short_name": "离线助手",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4a90e2",
  "orientation": "portrait-primary",
  "icons": [
    {
      "src": "icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

这里面有几个关键字段，我得给你讲透：

  • name 和 short_name：name 是全名，显示在启动画面底部；short_name 是长按图标时显示的名字，要短，别超过 12 个字符。
  • start_url：这是用户点击图标后进入的页面。通常设为 /，也就是首页。
  • display：这是最关键的。设为 standalone 会隐藏浏览器的地址栏和工具栏，让页面看起来像个原生 App。其他选项还有 fullscreen（全屏，连状态栏都没）和 minimal-ui（底部有点控制条）。
  • icons：必须提供至少 192x192 和 512x512 两种尺寸。这是为了适应不同的屏幕密度。如果你给的是 PNG，记得去掉 Alpha 通道以外的透明部分，否则在某些系统上会有黑边。
  • theme_color 和 background_color：前者控制状态栏颜色，后者控制启动时的背景色。

然后在 index.html 里引用它：

<head>
  <!-- 其他 meta 标签 -->
  <link rel="manifest" href="/manifest.json">
  
  <!-- iOS 设备也需要单独的 meta 标签，虽然我们不开发 iOS App，但为了兼容性最好加上 -->
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
  <meta name="apple-mobile-web-app-title" content="离线助手">
  <link rel="apple-touch-icon" href="/icons/icon-192.png">
</head>

到这里，你的应用已经具备了 PWA 的基本骨架：可安装、有图标、全屏运行、离线可用。

进阶：动态数据的离线处理（Cache First vs Network First）

刚才的例子缓存的是静态资源（HTML, CSS, JS, 图片）。但现实应用中，你很可能需要缓存数据，比如 API 返回的 JSON 文章列表、用户信息等。这时候，策略就要变了。

对于数据，我们通常推荐 Network First, Cache Fallback（网络优先，缓存兜底）。因为数据是动态的，我们希望尽量看到新的，但如果没网，至少能看到旧的。

咱们在 sw.js 里增加一段逻辑，专门处理 /api/ 开头的请求：

// 在 fetch 事件监听器中，增加对 API 的特殊处理
self.addEventListener('fetch', (event) => {
  // ... 前面的代码不变 ...

  event.respondWith(
    // 判断是否是 API 请求
    (event.request.url.includes('/api/')) ? 
      // API 请求：网络优先
      fetch(event.request)
        .then((networkResponse) => {
          // 成功拿到网络数据，存进缓存
          const responseToCache = networkResponse.clone();
          caches.open(CACHE_NAME).then((cache) => {
            cache.put(event.request, responseToCache);
          });
          return networkResponse;
        })
        .catch(() => {
          // 没网了，返回缓存中的数据
          return caches.match(event.request);
        }) : 
      // 静态资源：缓存优先（前面的逻辑）
      caches.match(event.request)
        .then((cachedResponse) => {
          if (cachedResponse) return cachedResponse;
          return fetch(event.request).then((response) => {
            const responseToCache = response.clone();
            caches.open(CACHE_NAME).then((cache) => cache.put(event.request, responseToCache));
            return response;
          });
        })
  );
});

这段代码展示了两种策略的混合使用。你可以看到，代码结构依然清晰：根据请求类型，走不同的分支。这对于初学者来说非常重要——不要试图用一种策略解决所有问题。图片永远缓存优先，数据永远网络优先，HTML 永远网络优先但可缓存。

实战案例：做一个“离线日记”应用

光说不练假把式。咱们来做一个简单但完整的案例：一个离线日记本。你可以随时随地写日记，即使没网，日记也会保存，等你有网的时候再同步（模拟）。

1. 数据层：使用 IndexedDB

既然要离线存储结构化数据，LocalStorage 就不够用了（它只支持字符串，且容量小）。IndexedDB 是浏览器内置的 NoSQL 数据库，专门为此而生。

在 app.js 中，我们封装一个简单的 IndexedDB 操作：

const DB_NAME = 'DiaryDB';
const DB_VERSION = 1;
const STORE_NAME = 'entries';

let db;

function openDB() {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(DB_NAME, DB_VERSION);

    request.onupgradeneeded = (event) => {
      db = event.target.result;
      // 创建对象仓库，id 是自增主键，content 是存储字段
      if (!db.objectStoreNames.contains(STORE_NAME)) {
        db.createObjectStore(STORE_NAME, { keyPath: 'id', autoIncrement: true });
      }
    };

    request.onsuccess = (event) => {
      db = event.target.result;
      resolve(db);
    };

    request.onerror = (event) => {
      reject(event.target.error);
    };
  });
}

function addEntry(text) {
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([STORE_NAME], 'readwrite');
    const store = transaction.objectStore(STORE_NAME);
    const entry = {
      content: text,
      date: new Date().toISOString()
    };
    const request = store.add(entry);
    
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

function getEntries() {
  return new Promise((resolve, reject) => {
    const transaction = db.transaction([STORE_NAME], 'readonly');
    const store = transaction.objectStore(STORE_NAME);
    const request = store.getAll();
    
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

2. UI 层：简单的日记界面

在 index.html 里，写一个简单的界面：

”`html <!DOCTYPE html> 离线日记 

<h1>我的离线日记</h1>
<span id="status">检查网络状态...</span>


<textarea id="entryInput" placeholder="写下今天的想法..."></textarea>
<button id="saveBtn">保存日记</button>

<ul id="entryList"></ul>