Local-First 软件架构实战：用 CRDT 实现离线优先的协作应用

Figma 在断网时依然能流畅编辑设计稿，Google Docs 的多人协作几乎零冲突——这些体验背后，是一种正在重塑应用架构范式的技术：Local-First 软件架构。2025 年以来，随着 Yjs、Automerge 2.0、ElectricSQL 等项目的成熟，Local-First 已经从学术概念变成了生产级方案。如果你正在构建需要离线能力或实时协作的应用，理解 CRDT（无冲突复制数据类型）已经不是「加分项」，而是必备技能。

🏗️ 一、Local-First 核心理念与技术选型

什么是 Local-First？

Local-First 不是「离线模式」的美化说法。它是一套完整的架构哲学，核心原则由 Martin Kleppmann 等人在 2019 年的论文中提出：

1. 数据主权：用户数据存储在本地设备，不依赖云端
2. 离线可用：无网络时应用完全可用，联网后自动同步
3. 实时协作：多人同时编辑不冲突，延迟 < 100ms
4. 去中心化：不需要中心服务器，点对点也能同步

💡 **提示：**Local-First ≠ 离线优先（Offline-First）。Offline-First 只是「先用本地缓存，后同步到服务器」，而 Local-First 的数据所有权在用户端，云端只是同步节点之一。

为什么现在是学习 Local-First 的最佳时机？

三个趋势正在推动 Local-First 走向主流：

• 隐私法规收紧：GDPR、中国的《个人信息保护法》都要求数据最小化采集，Local-First 天然合规
• 边缘计算兴起：Cloudflare Workers、Deno Deploy 让「无服务器」成为常态，但无服务器也意味着需要更强的本地能力
• AI 应用爆发：本地运行的 AI 模型（如 Ollama）需要本地数据，Local-First 是最自然的搭档

技术方案对比

⚡ **关键结论：**如果你在做富文本协作，选 Yjs；如果是结构化数据同步，选 Automerge 或 PowerSync；如果要快速出 MVP，选 Liveblocks。

🔬 二、CRDT 深度解析与实战

CRDT 的数学基础

CRDT（Conflict-free Replicated Data Type，无冲突复制数据类型）的核心思想是：设计一种数据结构，使得任意顺序的合并操作都能得到相同的结果。这依赖于两个数学性质：

• 交换律：merge(a, b) = merge(b, a) — 合并顺序无关
• 结合律：merge(merge(a, b), c) = merge(a, merge(b, c)) — 分组合并等价
• 幂等性：merge(a, a) = a — 重复合并安全

⚠️ **警告：**不要自己实现 CRDT。看似简单的逻辑背后有大量的边界情况（幽灵删除、时钟偏移、垃圾回收）。除非你在做学术研究，否则请直接使用 Yjs 或 Automerge。

用 Yjs 构建协作编辑器

下面是一个完整的、可运行的协作编辑器示例。我们使用 Yjs + y-websocket + CodeMirror 6：

# 初始化项目
mkdir collab-editor && cd collab-editor
npm init -y
npm install yjs y-websocket y-codemirror.next @codemirror/view @codemirror/state @codemirror/lang-javascript
npm install -D vite typescript

// server.js — 协作服务端（WebSocket 服务器）
import { WebSocketServer } from 'ws';
import { setupWSConnection } from 'y-websocket/bin/utils';

const wss = new WebSocketServer({ port: 1234 });

wss.on('connection', (ws, req) => {
  // setupWSConnection 处理所有 CRDT 同步逻辑
  setupWSConnection(ws, req, {
    docName: req.url.slice(1) || 'default-doc',
    gc: true, // 启用垃圾回收，清理已删除的内容
  });
});

console.log('✅ 协作服务器已启动: ws://localhost:1234');

// client.js — 协作客户端（浏览器端）
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { yCollab } from 'y-codemirror.next';
import { EditorView, basicSetup } from 'codemirror';
import { EditorState } from '@codemirror/state';
import { javascript } from '@codemirror/lang-javascript';

// 1. 创建 Yjs 文档 — 这是 CRDT 的核心数据结构
const ydoc = new Y.Doc();

// 2. 定义共享文本类型（Y.Text 是专门为文本设计的 CRDT）
const ytext = ydoc.getText('codemirror-content');

// 3. 连接 WebSocket 服务器进行同步
const wsProvider = new WebsocketProvider(
  'ws://localhost:1234',
  'my-collab-doc',  // 文档 ID
  ydoc
);

// 4. 配置用户感知（显示协作者光标和选区）
const awareness = wsProvider.awareness;
awareness.setLocalStateField('user', {
  name: '用户_' + Math.random().toString(36).slice(2, 6),
  color: `hsl(${Math.random() * 360}, 70%, 50%)`,
});

// 5. 创建 CodeMirror 编辑器，绑定 Yjs 协作扩展
const state = EditorState.create({
  doc: ytext.toString(),
  extensions: [
    basicSetup,
    javascript(),
    yCollab(ytext, awareness, {
      undoManager: new Y.UndoManager(ytext), // 支持撤销/重做
    }),
  ],
});

const view = new EditorView({
  state,
  parent: document.getElementById('editor'),
});

// 6. 监听同步状态
wsProvider.on('sync', (synced) => {
  console.log(synced ? '✅ 已同步' : '⏳ 正在同步...');
});

// 7. 监听其他用户的变更
ytext.observe((event) => {
  // event.delta 包含增量变更信息
  // event.delta 的格式: [{ insert: 'abc' }, { retain: 5 }, { delete: 3 }]
  console.log('📝 内容变更:', event.delta);
});

📌 **记住：**Yjs 的 Y.Text 类型内部使用 YATA 算法，每个字符都有一个唯一 ID（clientID + clock），即使两个用户同时在同一位置插入字符，合并后也能保留两者的内容，且最终状态一致。

CRDT 的代价：空间与时间

CRDT 不是免费的午餐。每个字符都携带元数据（创建者 ID、逻辑时钟、删除标记等），这导致：

膨胀率随内容增长而下降，因为固定开销被摊薄。但对于超大文档（> 10MB），需要考虑分片策略。

🔄 三、同步策略与生产实战

三种同步模式对比

在生产环境中，你需要根据应用特点选择合适的同步策略：

// sync-strategy.ts — 三种同步策略的实现对比

// 策略 1：实时 WebSocket 同步（适合协作编辑）
class RealtimeSync {
  private provider: WebsocketProvider;

  constructor(doc: Y.Doc, room: string) {
    this.provider = new WebsocketProvider('wss://sync.example.com', room, doc, {
      connect: true,
      // 指数退避重连：断线后 1s, 2s, 4s, 8s... 重连
      maxBackoffTime: 30000,
    });

    // 二进制编码传输，比 JSON 小 3-5 倍
    this.provider.ws?.binaryType = 'arraybuffer';
  }
}

// 策略 2：IndexedDB 持久化 + 定期同步（适合离线应用）
import { IndexeddbPersistence } from 'y-indexeddb';

class OfflineSync {
  private indexeddbProvider: IndexeddbPersistence;
  private wsProvider: WebsocketProvider | null = null;

  constructor(doc: Y.Doc, docName: string) {
    // 本地持久化：数据存入 IndexedDB，断网不丢失
    this.indexeddbProvider = new IndexeddbPersistence(docName, doc);

    this.indexeddbProvider.on('synced', () => {
      console.log('✅ 本地数据已加载');
      // 本地加载完成后，再连接远程
      this.connectRemote(doc, docName);
    });
  }

  private connectRemote(doc: Y.Doc, docName: string) {
    if (!navigator.onLine) {
      console.log('📴 离线模式，等待网络恢复...');
      window.addEventListener('online', () => {
        this.connectRemote(doc, docName);
      }, { once: true });
      return;
    }

    this.wsProvider = new WebsocketProvider('wss://sync.example.com', docName, doc);
  }
}

// 策略 3：P2P WebRTC 同步（适合局域网/去中心化场景）
import { WebrtcProvider } from 'y-webrtc';

class P2PSync {
  constructor(doc: Y.Doc, room: string) {
    const provider = new WebrtcProvider(room, doc, {
      signaling: ['wss://signaling.example.com'],
      // 加密：所有 P2P 通信使用 AES-256 加密
      password: 'my-secret-room-password',
      maxConns: 20, // 最大连接数
      filterBcConnsByPeerId: true,
    });
  }
}

生产环境避坑指南

在将 Local-First 应用部署到生产环境时，以下问题最容易踩坑：

坑点 1：文档版本管理

// ❌ 错误做法：直接覆盖旧版本，无法回溯
function saveDoc(ydoc: Y.Doc) {
  const stateVector = Y.encodeStateAsUpdate(ydoc);
  localStorage.setItem('doc', stateVector);
}

// ✅ 正确做法：保存版本快照，支持历史回溯
class VersionManager {
  private versions: Map<number, Uint8Array> = new Map();
  private versionCounter = 0;

  saveSnapshot(ydoc: Y.Doc): number {
    const versionId = ++this.versionCounter;
    // encodeStateAsUpdate 创建完整的状态快照
    const snapshot = Y.encodeStateAsUpdate(ydoc);
    this.versions.set(versionId, snapshot);

    // 只保留最近 50 个版本，防止内存溢出
    if (this.versions.size > 50) {
      const oldest = Math.min(...this.versions.keys());
      this.versions.delete(oldest);
    }

    return versionId;
  }

  restoreVersion(ydoc: Y.Doc, versionId: number): boolean {
    const snapshot = this.versions.get(versionId);
    if (!snapshot) return false;

    // 清空当前文档并应用快照
    Y.applyUpdate(ydoc, snapshot);
    return true;
  }
}

坑点 2：大文档的增量同步

// ❌ 错误做法：每次同步完整文档状态（带宽浪费严重）
function fullSync(doc1: Y.Doc, doc2: Y.Doc) {
  const fullState = Y.encodeStateAsUpdate(doc1);
  Y.applyUpdate(doc2, fullState); // 传输整个文档，O(n) 带宽
}

// ✅ 正确做法：只同步差异部分（增量同步）
function incrementalSync(doc1: Y.Doc, doc2: Y.Doc) {
  // 获取 doc2 的状态向量（描述它已知的内容）
  const stateVector2 = Y.encodeStateVector(doc2);

  // 只编码 doc2 缺少的内容
  const diff = Y.encodeStateAsUpdate(doc1, stateVector2);

  // diff 通常远小于完整状态，O(差异) 带宽
  Y.applyUpdate(doc2, diff);

  console.log(`增量同步: ${diff.byteLength} bytes (完整状态: ${
    Y.encodeStateAsUpdate(doc1).byteLength
  } bytes)`);
}

坑点 3：并发删除的「幽灵字符」问题

这是 CRDT 中最经典的坑：用户 A 插入 “hello”，用户 B 删除 “hello”，合并后可能出现 “ghost characters”（幽灵字符）——被删除的字符占据空间但不可见。

// 解决方案：使用 Yjs 的 gc（垃圾回收）选项
const ydoc = new Y.Doc({ gc: true });
// gc: true 会在所有客户端都确认删除后，彻底移除墓碑标记
// gc: false（默认）保留墓碑以支持完整历史回溯

⚠️ **警告：**如果需要版本历史功能，必须设置 gc: false。但代价是文档大小会持续增长。生产环境建议定期创建快照后，再对旧版本启用 gc。

性能基准测试

在一台 4 核 8GB 的服务器上，使用 50 个并发客户端测试不同方案的同步延迟：

Yjs 在延迟和带宽方面表现优秀，仅次于需要大量服务端逻辑的 OT 方案。Automerge 的延迟较高是因为它使用了更通用但更重的 CRDT 实现。

🎯 总结与工具推荐

Local-First 不是银弹，但它解决了一个真实且日益重要的问题：如何在保证数据一致性的同时，让用户拥有数据主权和离线能力。

我的建议是分阶段引入：

1. MVP 阶段：使用 Liveblocks 或 Firebase 快速验证协作功能
2. 成长阶段：迁移到 Yjs + y-websocket，获得更好的性能和离线能力
3. 成熟阶段：引入 IndexedDB 持久化 + P2P 同步，实现完整的 Local-First 架构

⚡ **关键结论：**CRDT 的理论很优雅，但工程落地需要处理大量细节（版本管理、增量同步、垃圾回收、状态压缩）。选对工具比理解算法更重要——先把 Yjs 用起来，再深入研究原理。

推荐工具链：

• ✅ Yjs — 最成熟的 CRDT 库，社区活跃，文档完善
• ✅ y-websocket — 官方 WebSocket 同步提供者
• ✅ y-indexeddb — 浏览器端持久化，断网不丢数据
• ✅ y-webrtc — P2P 同步，适合去中心化场景
• ✅ Automerge — 如果你需要更丰富的数据结构（不只是文本），选它
• ❌ 自己造轮子 — 除非你在做学术研究，否则不要自己实现 CRDT

Local-First 正在从「小众理想主义」走向「主流工程实践」。2026 年，随着 Web 平台对本地存储（OPFS、IndexedDB 2.0）和网络能力（WebTransport、WebRTC）的持续增强，Local-First 应用的开发门槛会越来越低。现在开始学习，正是最佳时机。