React/Vue 全栈开发：状态持久化与离线优先的 PWA 架构实践

React/Vue 全栈开发：状态持久化与离线优先的 PWA 架构实践

一、断网之痛：Web 应用的"在线依赖症"

现代 Web 应用几乎都假设用户始终在线。当网络断开时，页面白屏、数据丢失、操作中断——用户体验瞬间归零。对于独立开发者而言，这个问题更加尖锐：用户可能在地铁上、飞机上、信号差的咖啡馆里使用你的产品，而你的应用在这些场景下完全不可用。

Progressive Web App（PWA）的离线优先（Offline-First）架构正是为解决这一问题而生。它通过 Service Worker 拦截网络请求、IndexedDB 持久化本地数据、Background Sync 同步离线操作，让应用在断网时依然可用，联网后自动同步。

但离线优先不是简单地"缓存一切"。它需要重新思考数据流架构：本地数据是唯一的数据源，远程服务器是同步目标而非数据源。本文将从架构设计、状态持久化和冲突解决三个维度，展示如何构建一个生产级的离线优先 PWA。

二、架构设计：从"在线优先"到"离线优先"的范式转换

2.1 数据流架构对比

flowchart TD subgraph "在线优先：服务器是数据源" OA1[用户操作] --> OA2[发送请求到服务器] OA2 --> OA3{网络可用?} OA3 -->|是| OA4[服务器处理] OA4 --> OA5[返回结果] OA5 --> OA6[更新 UI] OA3 -->|否| OA7[报错/白屏] end subgraph "离线优先：本地是数据源" OB1[用户操作] --> OB2[写入本地 IndexedDB] OB2 --> OB3[立即更新 UI] OB2 --> OB4[加入同步队列] OB4 --> OB5{网络可用?} OB5 -->|是| OB6[批量同步到服务器] OB6 --> OB7[处理冲突] OB7 --> OB8[更新本地数据] OB5 -->|否| OB9[等待网络恢复] OB9 --> OB5 end

2.2 核心组件

离线优先 PWA 的三大核心组件：

Service Worker：拦截网络请求，实现缓存策略和离线回退。是 PWA 的"网络代理层"。

IndexedDB：浏览器内置的 NoSQL 数据库，支持结构化数据存储和事务。是离线数据的"本地数据库"。

Background Sync：在网络恢复时自动触发同步任务，即使用户已关闭页面。是"离线操作的可靠投递"。

三、工程实现：离线优先 PWA 的核心模块

3.1 Service Worker 缓存策略

// service-worker.ts — Service Worker 缓存策略 const CACHE_NAME = 'app-v1'; const STATIC_ASSETS = [ '/', '/index.html', '/manifest.json', '/icons/icon-192.png', '/icons/icon-512.png', ]; // 安装：预缓存静态资源 self.addEventListener('install', (event) => { event.waitUntil( caches.open(CACHE_NAME).then((cache) => { return cache.addAll(STATIC_ASSETS); }) ); // 立即激活，不等待旧 Worker 关闭 self.skipWaiting(); }); // 激活：清理旧缓存 self.addEventListener('activate', (event) => { event.waitUntil( caches.keys().then((names) => { return Promise.all( names .filter((name) => name !== CACHE_NAME) .map((name) => caches.delete(name)) ); }) ); self.clients.claim(); }); // 请求拦截：根据资源类型选择缓存策略 self.addEventListener('fetch', (event) => { const url = new URL(event.request.url); // API 请求：网络优先，离线回退缓存 if (url.pathname.startsWith('/api/')) { event.respondWith(networkFirstWithCache(event.request)); return; } // 静态资源：缓存优先，后台更新 if (isStaticAsset(url.pathname)) { event.respondWith(cacheFirstWithUpdate(event.request)); return; } // HTML 页面：网络优先，离线回退缓存 event.respondWith(networkFirstWithCache(event.request)); }); // 网络优先 + 离线缓存回退 async function networkFirstWithCache(request: Request): Promise<Response> { try { const networkResponse = await fetch(request); // 成功时更新缓存 const cache = await caches.open(CACHE_NAME); cache.put(request, networkResponse.clone()); return networkResponse; } catch (error) { // 网络失败时返回缓存 const cachedResponse = await caches.match(request); if (cachedResponse) { return cachedResponse; } // 缓存也不存在：返回离线页面 return caches.match('/offline.html'); } } // 缓存优先 + 后台更新（Stale-While-Revalidate） async function cacheFirstWithUpdate(request: Request): Promise<Response> { const cachedResponse = await caches.match(request); // 后台更新缓存（不阻塞响应） const fetchPromise = fetch(request).then((networkResponse) => { const cache = caches.open(CACHE_NAME); cache.then((c) => c.put(request, networkResponse.clone())); return networkResponse; }); return cachedResponse || fetchPromise; } function isStaticAsset(pathname: string): boolean { return /\.(js|css|png|jpg|svg|woff2)$/.test(pathname); }

3.2 IndexedDB 状态持久化

// local-db.ts — IndexedDB 封装层 import { openDB, DBSchema, IDBPDatabase } from 'idb'; interface AppDB extends DBSchema { notes: { key: string; value: { id: string; title: string; content: string; updatedAt: number; syncedAt: number | null; // null 表示未同步 version: number; // 乐观锁版本号 deleted: boolean; // 软删除标记 }; indexes: { 'by-synced': number; 'by-updated': number }; }; syncQueue: { key: number; value: { id: number; operation: 'create' | 'update' | 'delete'; entityType: string; entityId: string; payload: any; timestamp: number; retryCount: number; }; indexes: { 'by-timestamp': number }; }; } class LocalDB { private db: IDBPDatabase<AppDB> | null = null; async init(): Promise<void> { this.db = await openDB<AppDB>('app-db', 1, { upgrade(db) { // 笔记存储 const noteStore = db.createObjectStore('notes', { keyPath: 'id' }); noteStore.createIndex('by-synced', 'syncedAt'); noteStore.createIndex('by-updated', 'updatedAt'); // 同步队列 const syncStore = db.createObjectStore('syncQueue', { keyPath: 'id', autoIncrement: true, }); syncStore.createIndex('by-timestamp', 'timestamp'); }, }); } // 创建/更新笔记：写入本地 + 加入同步队列 async saveNote(note: Omit<AppDB['notes']['value'], 'syncedAt' | 'version'>): Promise<void> { const tx = this.db!.transaction('notes', 'readwrite'); const store = tx.objectStore('notes'); // 获取现有版本号（乐观锁） const existing = await store.get(note.id); const version = existing ? existing.version + 1 : 1; const record: AppDB['notes']['value'] = { ...note, updatedAt: Date.now(), syncedAt: null, // 标记为未同步 version, deleted: false, }; await store.put(record); // 加入同步队列 const syncTx = this.db!.transaction('syncQueue', 'readwrite'); await syncTx.objectStore('syncQueue').add({ operation: existing ? 'update' : 'create', entityType: 'note', entityId: note.id, payload: record, timestamp: Date.now(), retryCount: 0, }); } // 获取未同步的记录 async getUnsyncedNotes(): Promise<AppDB['notes']['value'][]> { const tx = this.db!.transaction('notes', 'readonly'); const index = tx.store.index('by-synced'); // syncedAt 为 null 的记录 return index.getAll(null); } // 标记为已同步 async markSynced(id: string): Promise<void> { const tx = this.db!.transaction('notes', 'readwrite'); const note = await tx.store.get(id); if (note) { note.syncedAt = Date.now(); await tx.store.put(note); } } }

3.3 同步引擎与冲突解决

// sync-engine.ts — 离线同步引擎 class SyncEngine { private db: LocalDB; private isSyncing: boolean = false; constructor(db: LocalDB) { this.db = db; this.setupBackgroundSync(); this.setupOnlineListener(); } // 注册 Background Sync private setupBackgroundSync(): void { if ('serviceWorker' in navigator && 'SyncManager' in window) { navigator.serviceWorker.ready.then((registration) => { registration.sync.register('sync-data'); }); } } // 监听网络恢复 private setupOnlineListener(): void { window.addEventListener('online', () => { this.sync(); }); } // 执行同步 async sync(): Promise<SyncResult> { if (this.isSyncing) return { status: 'already_syncing' }; if (!navigator.onLine) return { status: 'offline' }; this.isSyncing = true; try { // 第一步：拉取服务器更新 const serverUpdates = await this.pullFromServer(); // 第二步：合并冲突 await this.mergeConflicts(serverUpdates); // 第三步：推送本地变更 const unsynced = await this.db.getUnsyncedNotes(); await this.pushToServer(unsynced); return { status: 'success', syncedCount: unsynced.length }; } catch (error) { return { status: 'error', error: String(error) }; } finally { this.isSyncing = false; } } // 冲突解决：Last-Write-Wins + 版本号校验 private async mergeConflicts( serverUpdates: ServerNote[] ): Promise<void> { for (const serverNote of serverUpdates) { const localNote = await this.db.getNote(serverNote.id); if (!localNote) { // 本地不存在：直接写入 await this.db.putNote(serverNote); continue; } if (localNote.version === serverNote.version) { // 版本一致：无冲突 continue; } // 版本不一致：Last-Write-Wins if (serverNote.updatedAt > localNote.updatedAt) { // 服务器更新：以服务器为准 await this.db.putNote(serverNote); } // 本地更新：保留本地版本，等待推送 } } }

四、离线优先的代价：PWA 架构的权衡

4.1 数据一致性延迟

离线优先架构下，本地数据和服务器数据可能不一致。用户在设备 A 上修改的数据，在设备 B 上可能看不到，直到同步完成。对于多设备用户，这种延迟可能导致困惑。

4.2 存储空间限制

IndexedDB 的存储空间受浏览器限制（通常为可用磁盘空间的 50-80%）。在数据量大的场景下（如离线图片库），可能触发存储配额限制。

4.3 调试复杂度

Service Worker 的生命周期和缓存行为增加了调试难度。缓存未更新、Worker 未激活、请求未拦截等问题需要使用 DevTools 逐一排查。

4.4 适用边界

离线优先 PWA 最适合：笔记工具、任务管理、文档编辑等数据量可控、冲突概率低的场景。不适合：实时协作编辑、金融交易、多人在线游戏等对数据一致性要求极高的场景。

五、总结

离线优先架构将 Web 应用的可用性从"必须在线"提升到"始终可用"。通过 Service Worker 缓存策略、IndexedDB 本地存储和 Background Sync 自动同步，用户可以在任何网络条件下正常使用应用。工程实践中的核心挑战是冲突解决——Last-Write-Wins 简单但不公平，CRDT 精确但复杂。对于独立开发者，建议从 Last-Write-Wins 开始，在用户反馈驱动下逐步升级冲突策略。离线优先不是技术炫技，而是对用户真实场景的尊重——好的产品，不应该因为网络不好就不可用。