离线优先（Offline-First）架构的核心理念在于：应用默认运行于无网络环境，所有用户交互直接作用于本地存储，不依赖任何远程服务响应。通过这种范式转变，能够确保用户在零网络条件下依然获得毫秒级响应、无白屏的完整功能体验。针对 Web 端与 Native 端，离线缓存机制的实现路径存在显著差异。

一、 PWA 离线缓存机制：Service Worker 与 Cache API

PWA 的离线能力主要依托于 Service Worker 这一独立运行的后台脚本，通过拦截网络请求并结合 Cache API 实现资源的本地化存储与分发。

1. 核心缓存策略：针对不同资源类型，PWA 需采取差异化的缓存策略以平衡响应速度与数据新鲜度：
   • CacheFirst（缓存优先）：优先从缓存读取，未命中再请求网络。适用于图片、字体等不常变更的静态资源。
   • NetworkFirst（网络优先）：优先请求网络，失败时回退至缓存。适用于 HTML 页面导航及动态内容。
   • StaleWhileRevalidate（后台更新）：立即返回缓存内容，同时在后台发起网络请求更新缓存。适用于频繁变更的 API 数据。
2. 工程化实践：原生编写 Service Worker 学习曲线陡峭且代码量大。当前主流方案采用 Workbox 等工具库，通过少量配置即可自动生成资源清单、实现版本检测与旧缓存清理，大幅降低开发门槛。

1. 差异化缓存策略配置 (sw.js)

利用 Workbox 针对不同资源类型实现精细化的缓存控制。

// sw.js import { registerRoute } from 'workbox-routing'; import { CacheFirst, NetworkFirst, StaleWhileRevalidate } from 'workbox-strategies'; import { ExpirationPlugin } from 'workbox-expiration'; // 1. 静态资源：CacheFirst（缓存优先） registerRoute( ({ request }) => ['style', 'script', 'worker'].includes(request.destination), new CacheFirst({ cacheName: 'static-assets', plugins: [ new ExpirationPlugin({ maxEntries: 60, maxAgeSeconds: 30 * 24 * 60 * 60 }) // 缓存30天 ] }) ); // 2. 页面导航：NetworkFirst（网络优先） registerRoute( ({ request }) => request.mode === 'navigate', new NetworkFirst({ cacheName: 'pages', plugins: [] }) ); // 3. API 数据：StaleWhileRevalidate（后台更新） registerRoute( ({ url }) => url.pathname.startsWith('/api/'), new StaleWhileRevalidate({ cacheName: 'api-data', plugins: [ new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 5 * 60 }) // 缓存5分钟 ] }) );

2. 离线写操作与后台同步队列

在离线状态下拦截写操作，并交由 Service Worker 在网络恢复时处理。

// offlineSync.js export async function queueOfflineAction(actionData) { // 将离线操作存入 IndexedDB 队列 const db = await openDB('sync-queue', 1, { upgrade(db) { db.createObjectStore('actions', { autoIncrement: true }); } }); await db.add('actions', actionData); // 注册后台同步任务 if ('serviceWorker' in navigator && 'SyncManager' in window) { const reg = await navigator.serviceWorker.ready; await reg.sync.register('sync-offline-actions'); } } // 在 sw.js 中监听同步事件 self.addEventListener('sync', (event) => { if (event.tag === 'sync-offline-actions') { event.waitUntil(syncPendingActions()); } }); async function syncPendingActions() { const db = await openDB('sync-queue', 1); const actions = await db.getAll('actions'); for (const action of actions) { await fetch(action.url, { method: action.method, body: JSON.stringify(action.payload) }); await db.delete('actions', action.id); // 成功后从队列移除 } }

二、 Native 离线缓存机制：本地数据库与状态持久化

Native 应用的离线能力建立在设备原生的持久化存储之上，通常结合网络状态检测库（如 NetInfo）实现动态的数据读写策略。

1. 数据分层与持久化：Native 端通常采用多层次缓存策略。通过 AsyncStorage、SQLite 或 Realm 等库，将 Redux 状态、GraphQL 数据或业务配置持久化至本地。即使完全断网，应用仍能加载并展示已缓存的内容。
2. 请求失败兜底：在发起网络请求时，若捕获到网络异常，应用会自动降级读取本地缓存数据。这种机制避免了传统“在线优先”架构下常见的提交失败弹窗与状态丢失痛点。
3. 增量同步机制：当网络恢复时，Native 应用仅同步发生变化的数据（增量 diff），而非全量覆盖。这大大减少了数据流量消耗，并保障了跨设备数据的一致性。

1. 全局状态持久化 (Zustand + MMKV)

结合高性能 KV 存储，确保 Redux/Zustand 状态在断网或 App 重启后瞬间恢复。

// store/useAppStore.ts import { create } from 'zustand'; import { persist, createJSONStorage } from 'zustand/middleware'; import { mmkvStorage } from './mmkvStorage'; // 自定义 MMKV 适配器 export const useAppStore = create( persist( (set) => ({ user: null, articles: [], setUser: (user) => set({ user }), setArticles: (articles) => set({ articles }), }), { name: 'app-storage', storage: createJSONStorage(() => mmkvStorage), // 使用 MMKV 替代 AsyncStorage } ) );

2. 网络状态监听与请求兜底

在数据请求层自动感知网络状态，实现无缝的缓存降级。

// utils/fetchWithCache.ts import NetInfo from "@react-native-community/netinfo"; export async function fetchWithCache(url: string, cacheKey: string) { const netState = await NetInfo.fetch(); // 1. 离线状态：直接读取本地缓存 if (!netState.isConnected) { const cached = await mmkvStorage.getItem(cacheKey); if (cached) return JSON.parse(cached); throw new Error('当前无网络且无本地缓存'); } // 2. 在线状态：请求网络并更新缓存 try { const response = await fetch(url); const data = await response.json(); await mmkvStorage.setItem(cacheKey, JSON.stringify(data)); return data; } catch (error) { // 3. 网络异常兜底：尝试读取旧缓存 const cached = await mmkvStorage.getItem(cacheKey); if (cached) return JSON.parse(cached); throw error; } }

三、 离线体验优化与后台操作

除了数据与资源的缓存，完善的离线体验还需要关注用户交互与后台任务的调度：

1. 友好的状态反馈：当设备离线时，应用应展示精心设计的离线页面或 Toast 提示；当网络恢复时，通过事件总线或消息通知提醒用户重新加载以获取最新内容。
2. 后台同步（Background Sync）：对于用户在离线状态下产生的写操作（如发送邮件、提交表单），PWA 可通过后台同步 API 将任务交由 Service Worker 托管。待设备重新联网后，浏览器会自动唤醒 Service Worker 执行任务，确保数据最终成功同步至服务端。

1. 离线写操作入队与后台同步触发

在离线状态下拦截写操作，存入本地队列，并在网络恢复时触发 Service Worker 同步。

// offlineSync.js export async function queueOfflineAction(actionData) { // 1. 将离线操作存入 IndexedDB 队列 const db = await openDB('sync-queue', 1, { upgrade(db) { if (!db.objectStoreNames.contains('actions')) { db.createObjectStore('actions', { autoIncrement: true }); } } }); await db.add('actions', { ...actionData, timestamp: Date.now() }); // 2. 注册后台同步任务 if ('serviceWorker' in navigator && 'SyncManager' in window) { const reg = await navigator.serviceWorker.ready; await reg.sync.register('sync-offline-actions'); } } // sw.js - 在 Service Worker 中监听同步事件 self.addEventListener('sync', (event) => { if (event.tag === 'sync-offline-actions') { event.waitUntil(syncPendingActions()); } }); async function syncPendingActions() { const db = await openDB('sync-queue', 1); const actions = await db.getAll('actions'); for (const action of actions) { try { await fetch(action.url, { method: action.method, body: JSON.stringify(action.payload), headers: { 'Content-Type': 'application/json' } }); await db.delete('actions', action.id); // 成功后从队列移除 } catch (e) { console.warn('同步失败，等待下次重试', e); break; // 遇到网络问题中断循环，等待下次触发 } } }

2. 网络状态监听与 UI 反馈

通过全局事件总线或状态管理，实时响应网络变化并提供视觉反馈。

// hooks/useNetworkStatus.ts import { useState, useEffect } from 'react'; export function useNetworkStatus() { const [isOnline, setIsOnline] = useState(navigator.onLine); useEffect(() => { const handleOnline = () => setIsOnline(true); const handleOffline = () => setIsOnline(false); window.addEventListener('online', handleOnline); window.addEventListener('offline', handleOffline); return () => { window.removeEventListener('online', handleOnline); window.removeEventListener('offline', handleOffline); }; }, []); return isOnline; } // UI 组件中使用 const NetworkBanner = () => { const isOnline = useNetworkStatus(); if (isOnline) return null; return ( <div style={{ background: '#ff4d4f', color: '#fff', textAlign: 'center', padding: '8px' }}> ⚠️ 当前处于离线模式，部分功能可能受限 </div> ); };

四、 复杂数据冲突解决与 CRDTs 算法

当多个设备在离线状态下对同一份数据进行修改，并在重新联网时尝试同步，必然会产生冲突。

• Last-Write-Wins (LWW) 策略：对于简单的状态数据，可通过在本地数据库记录updated_at时间戳，在同步时以最新的时间戳覆盖旧数据。这种方式实现简单，但可能会丢失用户的离线编辑。
• CRDTs (无冲突复制数据类型)：针对富文本编辑、协同文档等复杂场景，引入 CRDTs 算法（如 Yjs 或 Automerge）。该算法能在数学层面保证多端并发修改最终收敛到一致状态，彻底消除人工解决冲突的烦恼。

1. 安装 Yjs 依赖

npm install yjs

2. 基于 Yjs 的离线协同文档引擎

// crdt/DocumentStore.ts import * as Y from 'yjs'; export class DocumentStore { private ydoc: Y.Doc; private ytext: Y.Text; constructor() { this.ydoc = new Y.Doc(); // 创建一个名为 'content' 的共享文本类型 this.ytext = this.ydoc.getText('content'); } // 获取当前文档内容 getContent(): string { return this.ytext.toString(); } // 本地插入文本（自动处理并发冲突） insertText(index: number, text: string): void { this.ydoc.transact(() => { this.ytext.insert(index, text); }); } // 本地删除文本 deleteText(index: number, length: number): void { this.ydoc.transact(() => { this.ytext.delete(index, length); }); } // 监听文档变更（用于同步至 UI 或其他设备） onChange(callback: (event: Y.YTextEvent) => void): () => void { const observer = (event: Y.YTextEvent) => callback(event); this.ytext.observe(observer); return () => this.ytext.unobserve(observer); } // 导出文档状态用于离线持久化或网络传输 exportState(): Uint8Array { return Y.encodeStateAsUpdate(this.ydoc); } // 导入外部状态（如从 IndexedDB 恢复或接收网络同步数据） importState(update: Uint8Array): void { Y.applyUpdate(this.ydoc, update); } }

3. 结合离线队列的 CRDT 同步

// 在应用初始化时恢复离线数据 const docStore = new DocumentStore(); // 从本地存储恢复 CRDT 状态 const savedState = localStorage.getItem('ydoc-state'); if (savedState) { docStore.importState(new Uint8Array(JSON.parse(savedState))); } // 监听变更并自动保存 docStore.onChange(() => { const state = docStore.exportState(); localStorage.setItem('ydoc-state', JSON.stringify(Array.from(state))); // 如果在线，可将 state 推送至服务端进行广播 });

五、 跨端状态同步与单向数据流

离线优先架构下，本地数据库是唯一的“数据真相来源（Truth Source）”。

• UI 与本地数据强绑定：应用 UI 应直接订阅本地数据库（如 SQLite 或 IndexedDB）的变更事件。无论是网络拉取的新数据，还是离线写入的旧数据，只要本地库发生变化，UI 自动响应刷新，彻底解耦网络层与视图层。
• 状态持久化与恢复：在 Native 端，结合 Redux Persist 或 WatermelonDB 等库，将全局状态树自动序列化至本地。即使应用被系统强杀，重启后也能瞬间恢复到用户离开前的完整状态。

六、 网络状态感知与优雅降级机制

优秀的离线体验不仅在于“能用”，更在于“无感”。

• 全局网络探针：在应用底层建立网络状态监听器（如使用@react-native-community/netinfo或 PWA 的navigator.onLine）。当检测到断网时，自动将 HTTP 请求拦截并路由至本地缓存读取，并在 UI 顶部展示“当前处于离线模式”的横幅。
• 写操作的乐观更新（Optimistic UI）：在离线状态下提交表单时，不要等待网络响应。直接在本地数据库写入数据并立即更新 UI，给用户“操作已成功”的即时反馈。待网络恢复后，后台静默队列再将变更同步至服务端；若服务端校验失败，再在 UI 上提示用户重试。

七、 后台同步（Background Sync）的兜底与重试策略

PWA 的 Background Sync API 并非在所有浏览器中都完美支持，必须建立健壮的降级机制。

• 任务队列持久化：将离线时的写操作（如发帖、点赞）封装为任务对象，存入 IndexedDB 的任务队列中。
• 多重触发机制：优先尝试注册syncManager.register()，让浏览器在网络恢复时自动唤醒 Service Worker 执行队列。若浏览器不支持，则降级为在应用重新打开（onPageShow）或定时器轮询时，手动触发队列消费逻辑，确保数据绝不丢失。