【跨平台】露营装备离线档案·04:uni-app 离线同步冲突:装备勾选如何合并【共创稿事节】
家人在两台手机上修改同一份露营清单:一台将炉具标记为已打包,另一台删除了炉具。若简单比较谁最后同步,就可能把被删除的装备重新创建出来。
实践中先收紧输入与输出,比第一时间增加新框架更容易获得可解释的结果。 我们围绕“露营装备清单”的“同步冲突”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

从两台设备的不一致说起
同步需要记录身份、版本、修改时间和删除墓碑。updatedAt 只是辅助信息,设备时间可能不准确;真正可冲突合并的系统还需要服务端版本或操作序列来界定先后。
如果只把“同步冲突”当作一个可见页面,开发时很容易忽略操作背后的状态流。实际应用有用户重复点击、进程被回收、页面重新进入、系统权限被拒绝等情况;这些变化并不会自动遵守 Vue 组件的生命周期。建议先把 updatedAt 的调用条件写成可阅读的规则,再决定在哪个页面事件里触发。
对“露营装备清单”而言,页面组件需要能够回答三个问题:当前展示的数据是否已确认、用户现在还能执行什么动作、失败后哪些数据应继续保留。若这三个问题的答案依赖一个模糊的布尔值,后续出现空态、加载态和待确认态时就会不断补丁式增加判断。
从工程划分来看,services/merge.ts 是本篇关键实现位置。页面与公共服务不应互相猜测对方的数据形状:应明确参数类型、正常返回和需要处理的失败分类;读取与写入的规则在代码审查时分别核对。在装备清单里,本地可恢复性比立刻接入云服务更重要。状态更新的时间、持久化完成的时间与跨设备同步完成的时间,应该是三个独立概念;任何一个尚未完成,页面都要避免使用含糊的“已同步”。
变更顺序不能靠猜
记录保留 deleted 字段和 revision。示例提供可测试的纯合并函数,采用更高 revision 优先、同版本出现分歧时标注 conflict 的保守策略,不擅自用本地时间覆盖对端变更。
“最后写入者获胜”看似容易,但依赖的时间不能总被信任。两台手机的时钟可能差几分钟,脱机期间也无法获得权威服务器时间。所以本例用 revision 比较已知的先后;同一 revision 内容不同就标成冲突,等待用户确认。这不是完全的协同算法,而是一种保守、容易审计的同步规则。删除必须作为可传播的 tombstone 而不是立即抹除,否则另一台离线设备同步时会把它重新传回来。只有保留冲突记录,用户才知道哪些字段没有被合并。
落地时先声明最小业务模型,再决定它的持有者。由页面驱动的暂态数据可以用 ref 或 computed;需要在刷新后恢复的结果必须明确读写入口;属于服务端最终决定的字段则不能因为按钮点击而直接写成成功。对“同步冲突”的每一种可见状态,都建议找到对应的数据依据。
纯合并函数设计
下面保留了与“同步冲突”直接相关的核心实现。示例以标准 uni-app Vue3 工程为目标,服务端地址、业务表结构和平台授权按照项目实际环境配置。连载文章与前文按相同文件职责衔接:前面建立的类型与仓库不在后篇随意改名;独立文章则可以单独复制相应页面或服务进行验证。
// services/merge.ts
interface GearRecord {
id: string; packed: boolean; deleted: boolean;
revision: number; title: string;
}
interface MergeResult { merged: GearRecord[]; conflicts: string[] }
export function mergeRecords(local: GearRecord[], remote: GearRecord[]): MergeResult {
const l = new Map(local.map(v => [v.id, v]));
const r = new Map(remote.map(v => [v.id, v]));
const ids = new Set([...l.keys(), ...r.keys()]);
const merged: GearRecord[] = [];
const conflicts: string[] = [];
for (const id of ids) {
const a = l.get(id); const b = r.get(id);
if (!a && b) { merged.push(b); continue; }
if (!b && a) { merged.push(a); continue; }
if (!a || !b) continue;
if (a.revision !== b.revision) {
merged.push(a.revision > b.revision ? a : b);
} else if (JSON.stringify(a) === JSON.stringify(b)) {
merged.push(a);
} else { conflicts.push(id); merged.push(a); }
}
return { merged, conflicts };
}
// 冲突项保留本地展示态,不能在后台自动覆写服务端。
从源码阅读顺序看,先定位 services/merge.ts 中的输入,再找到 updatedAt 相关调用,最后确认界面状态或存储写回点。第一件事是确定调用的输入从哪里来:它可能来自路由参数、响应式状态,也可能来自本地持久化。第二件事是确定输出由谁消费:不应让 UI 组件直接承担重试协议或数据迁移。第三件事是检查失败路径是否有出口,不能永远停在加载中。
代码里最值得注意的是边界上的显式判断。它比向页面堆一个万能 catch 更有价值,因为不完整的数据、权限拒绝和无法联网,分别决定了用户接下来能做什么。业务组件只接收已经整理好的返回结果,才能独立处理加载、取消与重进页面。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

跨端同步的必要前提
本文讨论的是数据算法,不假定 uni.setStorageSync 自带多设备同步,也不声称没有服务端就能感知另一台手机。需要后台提供可靠的变更列表、设备标识和冲突回执,才能形成完整闭环。
Web / H5:H5 多标签页编辑同一清单时,本地缓存可能被交替覆盖,可在恢复时比较 revision 并展示冲突标记。 在“同步冲突”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。
微信小程序:小程序只知道当前设备的离线快照,不会因为用户登录相同微信账号就自然拥有另一台设备的操作序列。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。
App:App 离线修改后恢复网络仍需后台对账,删除墓碑和冲突记录必须随同步协议传递。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。
三端一致的部分应尽量体现在数据契约与业务语义中,三端不同的部分则应被清楚标识。比如“同步冲突”对用户呈现的保存、取消、重试这些动作应同义,但它们内部调用的权限检查、资源路径或系统接口可以不同。只有这样,平台迁移才不会变成整页复制。

用确定性样例检查算法
冲突常被最后一次写入掩盖,短期看似“同步成功”,几天后才发现记录丢失。对删除、重命名和勾选分别定义冲突优先级,排查时记录 revision 而不是泄露私人数据全文。
针对“露营装备清单”,排查时不要把所有可见异常归入同一个“操作失败”。先问失败发生在输入校验、页面状态转换、平台 API 调用、后台返回还是存储恢复;这五个位置至少要能在日志或可见状态中区分。对用户而言,保留已填写内容通常比重复弹窗更重要;对开发者而言,保留最小触发路径比截取一张成功页更有价值。
建议采用有限的日志字段:模块、动作、错误类别、必要的状态编号和构建版本。对于 updatedAt 所涉及的调用,敏感值、文件内容及完整用户资料不应输出。将错误按是否可重试划分之后,页面才能选择展示“重试”“继续编辑”或“前往授权”,而不是遇到任何问题都自动再执行一次。
回归时建议按下面五项逐条操作,不依赖“看起来正常”的主观判断:
1)不同 id 的装备变更能无冲突合并。 先对照本文定义的数据契约确认结果是否可解释,再检查不同运行容器是否走了相同的业务路径。出现差异时应保存最小输入和相应的代码版本,避免凭印象改动多个模块。 对“同步冲突”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。
2)同 id 且 revision 相同但 packed 不同应报告冲突。 验收的目标不是证明代码没有任何风险,而是把最容易造成用户损失的边界提前显露。记录触发动作、预期状态、实际状态与修复位置,并在下一次构建时用同一用例回归。 对“同步冲突”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。
3)删除墓碑不会被旧版本轻易复活。 复现时要保留输入条件与触发顺序,先判断页面是否给出确定状态,再核对存储或后台是否真正变化。尤其注意不要把一次偶然成功当作稳定结论;重复执行并检查边界值,能发现只在第二次出现的状态残留。 对“同步冲突”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。
4)两次合并输入相同得到相同输出。 把该项拆成操作、预期和失败证据三部分:操作必须能由另一个开发者重做;预期尽量描述可见的 UI 或稳定字段;失败证据只记录必要的错误分类和接口状态,不携带隐私信息。 对“同步冲突”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。
5)缺少 revision 的旧记录先迁移再合并。 不要只测正常网络和一台设备。若涉及异步步骤,至少安排一次连续快速触发以及一次人为中断;若涉及本地数据,则重新打开页面确认恢复结果。这样比盯着开发者工具里的成功提示可靠。 对“同步冲突”来说,只有这一项前后的业务记录与页面反馈能够对应,才能把结果记为通过。
为了小团队可维护性,本篇采用显式冲突待确认而非复杂 CRDT。需要多人高频协同且离线编辑密集时,再评估带操作日志的合并模型,勿把简单列表当协同数据库。
如果本次只维护一条流程,优先把数据契约、失败状态和用户可执行的下一步做扎实。新增功能前再审视公共服务与平台分支是否仍然清晰;对于需要真实联网、后端配置或设备权限的步骤,应在目标环境执行相应测试,不宜直接把源码静态检查描述成实际编译或真机验证。
收尾与适用范围
这篇围绕“同步冲突”建立了一条从数据边界、调用实现到多端验收的路径。它并不依赖于某种固定配色或 UI 库,重要的是业务动作在正常、取消、中断和重新进入时保持可解释。后续迭代可以更换组件和数据源,但输入、失败状态以及用户操作的语义应当持续稳定。
露营装备离线档案系列后续继续沿用本篇的记录身份与保存规则,不通过更换 Key 或重置全部本地数据来绕开兼容问题。
本文所用平台 API 与工程约束可对照 uni-app 官方参考、Vue3 组合式 API 以及 条件编译文档。若使用新版 HBuilderX 或开发 HarmonyOS Next 应以目标版本的文档与设备支持表为准。
更多推荐

所有评论(0)