local-first

本地优先

概述

本地优先是一种架构，应用会读取和写入本地数据库，并在后台将更改同步到服务器。本地数据库是 UI 的事实来源，默认支持即时读取、离线使用和乐观写入。

适用场景： 需要离线支持的协作应用、注重延迟且即时响应至关重要的 UI、网络条件不可靠的应用、实时多人游戏功能、连接时断时续的移动应用。

不适用场景： 网络连接可靠的简单 CRUD 应用、由服务器控制的工作流（支付、库存）、交互极少且内容繁多的网站、每次渲染都必须确保数据与服务器保持最新的应用。

快速参考

决策	选项	关键考量
架构模式	基于服务器、本地优先、混合	离线需求和延迟容忍度决定选择
读取路径	从服务器获取、读取本地数据库、先缓存后请求网络	本地读取即时完成；从服务器读取会受网络延迟影响
写入路径	服务器端变更、乐观更新、本地优先写入	本地写入永不失败；由同步负责传输
同步引擎	Electric、Zero、PowerSync、Replicache、LiveStore	Postgres 集成与框架无关之间的取舍
客户端存储	IndexedDB、OPFS、SQLite WASM、PGlite	容量限制、查询能力、浏览器支持
冲突解决	LWW、CRDT、服务器优先、字段级合并	复杂度与正确性之间的取舍
数据模型	规范化表、文档存储、CRDT 文档	查询模式决定最佳模型
部分复制	Shapes、订阅、基于查询的同步	只同步客户端需要的数据
渐进式增强	以服务器为先并搭配本地缓存、完全本地优先	从简单方案开始，逐步添加本地优先能力
CQRS 分离	分离读写模型、统一模型	本地优先天然会将读取与写入分离
初始同步	完整快照、增量同步、渐进式加载	首次加载性能与完整性之间的取舍
身份验证集成	基于令牌的 shape 筛选、行级安全性	安全性由同步层而非客户端负责
架构演进	增量迁移、版本化 shapes	本地数据库架构必须在不丢失数据的情况下演进
状态管理	替换 React Query、共存、混合方案	本地优先可以替换或补充服务器状态
测试策略	模拟同步引擎、测试离线场景、填充本地数据库	在线和离线代码路径都要测试

常见错误

错误	正确做法
简单的 CRUD 应用也优先采用本地优先架构	除非确实需要离线支持或低延迟，否则使用基于服务端的架构
尚未定义数据模型就选择同步引擎	先定义读写模式，再选择合适的引擎
拖到后期才考虑冲突解决	从一开始就将冲突策略与数据模型一同设计
将整个数据库同步到每个客户端	使用部分复制（shapes、订阅）来同步相关数据
把本地数据库当作缓存	本地数据库是 UI 的事实来源，而非缓存层
什么场景都使用 CRDT	对大多数字段而言，LWW 或服务端优先更简单且足够
跳过渐进增强	先从服务端优先开始，再为高价值交互添加本地优先功能
没有规划架构迁移	本地数据库和服务端数据库一样需要迁移策略

委派

如果有 electricsql 技能，请将 ElectricSQL 的配置、shapes、身份验证和写入模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y 如果有 realtime-sync 技能，请将 WebTransport、pub/sub 和 CRDT 实现细节委派给它。 如果有 tanstack-db 技能，请将集合配置、实时查询和乐观变更模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-db -a claude-code -y 如果有 tanstack-start 技能，请将服务端函数代理和 SSR 集成委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s tanstack-start -a claude-code -y

• 架构审查：使用 Plan Agent 评估本地优先与基于服务端架构之间的权衡
• 同步引擎对比：使用 Explore Agent 调研当前引擎的能力
• 存储基准测试：使用 Task Agent 针对特定数据模式测试存储选项

参考资料

• 架构模式与决策框架
• 同步引擎对比与选择指南
• 客户端存储选项与限制
• 冲突解决策略
• 离线韧性模式
• 架构版本管理与迁移
• 多租户数据治理模式
• 本地优先应用的测试策略
• 同步数据的端到端加密
• DevTools 与调试工具
• 从服务端优先迁移到本地优先的指南