JavaScript HTML5 Cache Manifest：离线应用缓存机制考古

HTML5 早期规范曾引入 Application Cache（简称 AppCache）机制，通过 cache manifest 文件实现 Web 应用的离线访问能力。尽管该特性因设计缺陷已在现代标准中被废弃（由 Service Worker 取代），但深入理解其工作原理、实现细节与历史局限，对于掌握 Web 缓存演进脉络、维护遗留系统以及设计现代离线方案仍具有重要参考价值。本文将从基础配置入手，系统剖析 AppCache 的语法规范、工作机制与底层原理，并结合代码与图示呈现其完整技术画像。

❗manifest 属性及 AppCache 机制已在 HTML Living Standard 中被移除，现代浏览器虽仍保留兼容支持，但不建议在新项目中使用。本文旨在技术考古与原理剖析，生产环境请优先采用 Service Worker。

一、Cache Manifest 技术概述

1. 什么是 Cache Manifest

Cache Manifest 是 HTML5 规范定义的一种离线缓存机制，允许开发者通过一个纯文本清单文件（通常以 .appcache 为扩展名）声明需要缓存的资源列表。浏览器下载并解析该文件后，会将指定资源存储到本地应用缓存（Application Cache）中，使得用户在无网络连接时仍能正常访问网页内容。

2. 技术定位与演进状态

timeline title Web 离线缓存技术演进 2008 : HTML5 草案引入 AppCache 2011 : 主流浏览器初步支持 2015 : 社区广泛反馈设计缺陷 2019 : W3C 正式标记为废弃 2020+ : Service Worker 成为标准替代方案

二、Cache Manifest 基础用法与实践

1. manifest 文件配置规范

（1）HTML 标签声明

在根元素 <html> 上添加 manifest 属性，指向清单文件路径：

html 复制代码

<!DOCTYPE html>
<html manifest="demo.appcache">
<head>
    <meta charset="UTF-8">
    <title>Offline App Example</title>
</head>
<body>
    <!-- 页面内容 -->
</body>
</html>

（2）MIME 类型与服务端配置

服务器必须为 .appcache 文件配置正确的 MIME 类型，否则浏览器将忽略该清单：

apache 复制代码

# Apache .htaccess 配置
AddType text/cache-manifest .appcache

nginx 复制代码

# Nginx 配置
location ~ \.appcache$ {
    add_header Content-Type text/cache-manifest;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

php 复制代码

// PHP 动态输出示例
<?php
    header('Content-Type: text/cache-manifest');
    header('Cache-Control: no-cache, must-revalidate');
?>
CACHE MANIFEST
# version: 20240410v1
/main.css
/app.js

2. manifest 文件结构详解

manifest 文件为纯文本格式，由三个逻辑区域组成，各区域以关键字开头，注释以 # 起始：

（1）CACHE MANIFEST 区域

text 复制代码

CACHE MANIFEST
# 版本号注释：修改此行可强制触发缓存更新
# v1.2.3 - 2024-04-10

# 显式声明需缓存的静态资源
/theme.css
/logo.gif
/main.js
/assets/data.json

# 支持通配符（谨慎使用）
CACHE:
*.png
*.jpg

该区域为默认区域 ，可省略 CACHE: 关键字
列出的资源将在首次访问时下载并持久化缓存
注释行（# 开头）的任何变更均会触发缓存重建

（2）NETWORK 区域

text 复制代码

NETWORK:
# 必须在线访问的动态资源
login.php
api/user/profile

# 通配符：除 CACHE/FALLBACK 外的所有资源均需网络
*

声明该区域的资源永远不会被缓存，每次请求均直达服务器
* 通配符表示"白名单模式"：仅缓存显式列出的资源，其余均需联网

（3）FALLBACK 区域

text 复制代码

FALLBACK:
# 语法：在线资源路径 离线回退页面
/ /offline.html
/html5/ /fallback/503.html

# 支持路径前缀匹配（非正则）
/images/ /images/offline-placeholder.png

当用户离线且请求的资源未缓存时，浏览器自动返回对应的 fallback 页面
路径匹配采用前缀匹配 规则，/html5/ 可匹配 /html5/page1.html、/html5/css/style.css 等

3. 缓存更新机制

graph LR A[用户访问页面] --> B{manifest 是否变更？} B -->|字节级不同| C[下载新 manifest] C --> D[并行下载新资源] D --> E{所有资源下载成功？} E -->|是| F[原子替换旧缓存] E -->|否| G[保留旧缓存触发 onerror] B -->|无变更| H[直接使用缓存] I[开发者操作] --> J[修改 manifest 注释/内容] J --> K[服务器部署新文件] K --> B

缓存更新触发条件：

manifest 文件内容变更（包括注释、空格、换行等任意字节变化）
程序调用 window.applicationCache.update() 主动检查更新
用户手动清除浏览器缓存

关键行为：即使服务器上的 main.js 已更新，若 demo.appcache 未变更，浏览器仍会使用旧版缓存。这是 AppCache 最受诟病的"缓存僵化"问题。

三、技术优势与局限性分析

1. 核心优势

（1）声明式配置：通过纯文本清单管理缓存资源，无需编写复杂脚本

（2）离线优先体验：首次加载后，后续访问完全离线可用，提升弱网环境体验

（3）自动缓存管理：浏览器负责资源下载、存储、版本校验，降低开发成本

（4）细粒度控制 ：通过 NETWORK/FALLBACK 实现动态资源与离线回退的精准控制

2. 关键不足与废弃原因

graph TD A[AppCache 设计缺陷] --> B[缓存更新机制反直觉] A --> C[安全边界模糊] A --> D[调试困难] A --> E[与标准缓存头冲突] B --> B1[必须修改 manifest 才能更新即使资源已变] C --> C1[缓存内容可被任意页面注入存在 XSS 风险] D --> D1[无开发者工具支持失败静默] E --> E1[忽略 HTTP 缓存头导致版本混乱]

问题类型	具体表现	影响
更新机制	字节级比对 + 原子替换	小修改触发全量重下载，流量浪费
安全模型	缓存作用域为源（origin）级别	恶意页面可污染同源其他页面的缓存
回退逻辑	FALLBACK 仅匹配离线场景	404/500 等在线错误无法触发回退
容量限制	浏览器实现差异（通常 5MB/源）	大型应用需手动分片，管理复杂
调试支持	无标准 API 查询缓存状态	问题排查依赖浏览器私有面板

四、底层实现原理深度解析

1. 缓存存储架构

classDiagram class ApplicationCache { +status: unsigned short +swapCache() void +update() void +onchecking: Event +onupdateready: Event } class CacheStorage { -manifestURL: string -resourceMap: Map~URL, Blob~ -fallbackMap: Map~prefix, fallbackURL~ -networkWhitelist: Set~URL~ } class ResourceLoader { +fetch(url) Promise~Response~ -checkCachePolicy(url) CacheDecision } ApplicationCache --> CacheStorage : 管理 ResourceLoader --> CacheStorage : 查询/写入

浏览器内部为每个源（origin）维护独立的 Application Cache 存储：

manifest 解析器：校验 MIME 类型、语法合法性，构建资源索引
资源下载器 ：并发下载 CACHE 区域资源，失败则回滚整个更新
匹配决策引擎 ：按 CACHE → FALLBACK → NETWORK 优先级决定资源来源

2. 资源加载决策流程

sequenceDiagram participant Page participant Loader as Resource Loader participant AppCache participant Network Page->>Loader: 请求 /main.js Loader->>AppCache: 查询缓存状态 alt 资源在 CACHE 区域 AppCache-->>Loader: 返回缓存副本 Loader-->>Page: 200 + 缓存内容 else 资源在 FALLBACK 区域且离线 AppCache-->>Loader: 返回 fallback 页面 Loader-->>Page: 200 + fallback 内容 else 资源在 NETWORK 或在线 Loader->>Network: 发起真实请求 Network-->>Loader: 返回服务器响应 Loader-->>Page: 透传响应 else 资源未声明且离线 Loader-->>Page: 404/离线错误页 end

关键决策逻辑伪代码：

javascript 复制代码

function decideResourceSource(requestURL, isOnline, cacheDB) {
    // 1. 优先匹配显式缓存
    if (cacheDB.CACHE.has(requestURL)) {
        return cacheDB.CACHE.get(requestURL);
    }
    
    // 2. 离线时匹配 fallback 规则（前缀匹配）
    if (!isOnline) {
        for (let [prefix, fallback] of cacheDB.FALLBACK) {
            if (requestURL.startsWith(prefix)) {
                return cacheDB.CACHE.get(fallback); // fallback 页本身需已缓存
            }
        }
    }
    
    // 3. 检查 NETWORK 白名单
    if (cacheDB.NETWORK.has('*') || cacheDB.NETWORK.has(requestURL)) {
        return 'fetch-from-network';
    }
    
    // 4. 默认策略：在线则请求网络，离线则失败
    return isOnline ? 'fetch-from-network' : 'error-offline';
}

3. 版本校验与更新触发机制

（1）manifest 变更检测算法

python 复制代码

# 浏览器内部简化逻辑
def check_manifest_update(old_manifest_bytes, new_manifest_bytes):
    # 字节级比对（非语义比对）
    if old_manifest_bytes == new_manifest_bytes:
        return False  # 无变更，复用缓存
    
    # 语法校验
    if not validate_manifest_syntax(new_manifest_bytes):
        trigger_error("Invalid manifest")
        return False
    
    return True  # 触发更新流程

（2）原子更新与回滚机制

graph LR A[检测到 manifest 变更] --> B[创建临时缓存槽] B --> C[并行下载新资源列表] C --> D{所有资源下载成功？} D -->|是| E[原子切换：新缓存激活] D -->|否| F[丢弃临时缓存保留旧版] E --> G[触发 updateready 事件] F --> H[触发 error 事件] I[页面调用 swapCache] --> J[立即使用新缓存无需刷新]

更新过程在后台缓存槽中进行，不影响当前页面使用的旧缓存
仅当所有新资源下载成功后，才原子替换主缓存，避免"部分更新"导致页面崩溃
开发者需监听 updateready 事件并调用 swapCache() 或刷新页面以应用更新

4. 浏览器缓存管理策略

（1）存储配额与驱逐策略

各浏览器实现不同：Chrome 约 5MB/源，Firefox 支持用户配额调整
当存储超限时，按 LRU（最近最少使用）原则驱逐旧缓存项
manifest 文件本身不计入配额，但其引用的资源计入

（2）缓存生命周期管理

javascript 复制代码

// 应用缓存状态机（简化）
const APP_CACHE_STATE = {
    UNCACHED: 0,      // 未关联 manifest
    IDLE: 1,          // 缓存就绪
    CHECKING: 2,      // 检查 manifest 更新
    DOWNLOADING: 3,   // 下载新资源中
    UPDATEREADY: 4,   // 新缓存就绪 等待激活
    OBSOLETE: 5       // manifest 404/无效 缓存将被清除
};

// 监听关键事件
const appCache = window.applicationCache;
appCache.addEventListener('updateready', () => {
    if (appCache.status === APP_CACHE_STATE.UPDATEREADY) {
        // 方案1：静默切换（可能引起资源不一致）
        appCache.swapCache();
        
        // 方案2：提示用户刷新（推荐）
        if (confirm('新版本已就绪，是否刷新应用？')) {
            window.location.reload();
        }
    }
});

五、生产环境实践建议与迁移方案

1. 兼容性检测与降级策略

javascript 复制代码

// 特性检测 + 优雅降级
function initOfflineSupport() {
    // 1. 检测 AppCache 支持（已废弃 仅用于遗留系统）
    if (window.applicationCache) {
        // 监听更新事件 避免静默失败
        window.applicationCache.addEventListener('error', (e) => {
            console.warn('AppCache 更新失败', e);
            // 降级：提示用户或切换轮询方案
        }, false);
    }
    
    // 2. 优先检测 Service Worker（现代方案）
    if ('serviceWorker' in navigator) {
        navigator.serviceWorker.register('/sw.js')
            .then(reg => console.log('SW registered', reg.scope))
            .catch(err => console.warn('SW registration failed', err));
        return;
    }
    
    // 3. 最终降级：基础离线提示
    window.addEventListener('offline', () => {
        document.body.classList.add('offline-mode');
        showToast('当前为离线模式 部分功能受限');
    });
}

2. 向 Service Worker 迁移指南

（1）核心概念映射

AppCache 概念	Service Worker 等效方案	优势
`CACHE MANIFEST`	`caches.open().add()`	精细控制缓存策略
`NETWORK:*`	`fetch()` 直通网络	支持动态条件判断
`FALLBACK`	`fetch` 事件拦截 + `caches.match()`	可编程回退逻辑
manifest 更新	`skipWaiting()` + `clients.claim()`	精准控制激活时机

（2）基础迁移示例

javascript 复制代码

// sw.js - Service Worker 基础模板
const CACHE_NAME = 'app-v1';
const STATIC_ASSETS = [
    '/',
    '/theme.css',
    '/logo.gif',
    '/main.js',
    '/offline.html'
];

// 安装阶段：预缓存核心资源
self.addEventListener('install', event => {
    event.waitUntil(
        caches.open(CACHE_NAME)
            .then(cache => cache.addAll(STATIC_ASSETS))
            .then(() => self.skipWaiting()) // 跳过 waiting 状态
    );
});

// 激活阶段：清理旧缓存
self.addEventListener('activate', event => {
    event.waitUntil(
        caches.keys().then(keys => 
            Promise.all(keys
                .filter(key => key !== CACHE_NAME)
                .map(key => caches.delete(key))
            )
        ).then(() => self.clients.claim()) // 立即接管页面
    );
});

// 请求拦截：实现 CACHE/NETWORK/FALLBACK 逻辑
self.addEventListener('fetch', event => {
    const { request } = event;
    const url = new URL(request.url);
    
    // 模拟 NETWORK:* 行为：动态资源直通网络
    if (url.pathname.endsWith('.php') || url.pathname.startsWith('/api/')) {
        return; // 不拦截 交由网络处理
    }
    
    // 模拟 CACHE + FALLBACK 行为
    event.respondWith(
        caches.match(request).then(cached => {
            if (cached) return cached; // 命中缓存
            
            // 未命中且离线：返回 fallback 页
            if (url.pathname.startsWith('/html5/')) {
                return caches.match('/offline.html');
            }
            
            // 在线则请求网络并缓存新响应（可选策略）
            return fetch(request).then(response => {
                // 仅缓存成功响应
                if (response.ok) {
                    const clone = response.clone();
                    caches.open(CACHE_NAME).then(cache => cache.put(request, clone));
                }
                return response;
            });
        })
    );
});

（3）注册与更新流程

html 复制代码

<!-- index.html -->
<script>
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/sw.js', { scope: '/' })
            .then(registration => {
                // 监听控制器变更（新 SW 激活）
                registration.addEventListener('updatefound', () => {
                    const newSW = registration.installing;
                    newSW.addEventListener('statechange', () => {
                        if (newSW.state === 'installed' && navigator.serviceWorker.controller) {
                            // 有新版本就绪 提示用户
                            showUpdatePrompt(() => {
                                newSW.postMessage({ action: 'skipWaiting' });
                            });
                        }
                    });
                });
            });
    });
}
</script>

javascript 复制代码

// sw.js 中处理 skipWaiting 消息
self.addEventListener('message', event => {
    if (event.data?.action === 'skipWaiting') {
        self.skipWaiting();
    }
});

（4）调试与监控建议

使用 Chrome DevTools → Application → Service Workers 面板调试
通过 caches.keys() 和 caches.match() API 编程式检查缓存状态
记录 fetch 拦截日志，分析缓存命中率与回退触发频率
配合 Workbox 库简化缓存策略配置与版本管理