【跨平台】露营装备离线档案·03:uni-app 数据升级策略:老版本装备记录如何迁移【共创稿事节】
上线数月后新增了装备重量和携带人字段。新页面读取旧用户存储时出现 undefined,若用“清空缓存即可修复”,用户多年整理的内容就会消失。
先看用户的一次具体操作,通常比从 API 名称出发更容易找到真正的工程约束。 我们围绕“露营装备清单”的“数据修复”收紧范围:既要写清实际功能的输入与状态,也要让代码能够被移入 uni-app Vue3 + TypeScript 工程中逐步验证。本文不把普通 uni-app 与 uni-app x 的运行机制混同;平台专用能力会在使用位置说明约束。

旧缓存不是可丢弃的垃圾
数据迁移应是从版本 N 到版本 N+1 的有序纯函数,不应散落在每个列表组件。对未知版本、已损坏数据和缺省字段,要分别定义恢复或拒绝策略。
如果只把“数据修复”当作一个可见页面,开发时很容易忽略操作背后的状态流。实际应用有用户重复点击、进程被回收、页面重新进入、系统权限被拒绝等情况;这些变化并不会自动遵守 Vue 组件的生命周期。建议先把 schemaVersion 的调用条件写成可阅读的规则,再决定在哪个页面事件里触发。
对“露营装备清单”而言,页面组件需要能够回答三个问题:当前展示的数据是否已确认、用户现在还能执行什么动作、失败后哪些数据应继续保留。若这三个问题的答案依赖一个模糊的布尔值,后续出现空态、加载态和待确认态时就会不断补丁式增加判断。
从工程划分来看,services/migrate.ts 是本篇关键实现位置。页面与公共服务不应互相猜测对方的数据形状:应明确参数类型、正常返回和需要处理的失败分类;读取与写入的规则在代码审查时分别核对。在装备清单里,本地可恢复性比立刻接入云服务更重要。状态更新的时间、持久化完成的时间与跨设备同步完成的时间,应该是三个独立概念;任何一个尚未完成,页面都要避免使用含糊的“已同步”。
将迁移看作可测试函数
保留 v1 的原始解析器,显式补齐 v2 的 weightGram 和 owner,再交由 v3 规范化分类字段。迁移完先做验证,再把新格式写回存储,不能在中途覆盖旧快照。
迁移脚本必须有明确的“不可逆”意识:一旦把旧重量字段覆盖成新单位,用户就无法知道原始值含义。为此迁移前先读取版本,版本不认识就停下;不要对未知版本尝试“猜测字段”。本例中旧数据没有重量,用 0 表达未填值很直观,但在统计页面里要避免把它当成真实重量。对同名历史记录生成 id 也是风险点,如果原始版本缺乏唯一标识,迁移程序应保证顺序稳定或提供人工合并入口。
落地时先声明最小业务模型,再决定它的持有者。由页面驱动的暂态数据可以用 ref 或 computed;需要在刷新后恢复的结果必须明确读写入口;属于服务端最终决定的字段则不能因为按钮点击而直接写成成功。对“数据修复”的每一种可见状态,都建议找到对应的数据依据。
版本升级代码
下面保留了与“数据修复”直接相关的核心实现。示例以标准 uni-app Vue3 工程为目标,服务端地址、业务表结构和平台授权按照项目实际环境配置。连载文章与前文按相同文件职责衔接:前面建立的类型与仓库不在后篇随意改名;独立文章则可以单独复制相应页面或服务进行验证。
// services/migrate.ts
interface V1 { id: string; title: string; category: string;
packed: boolean; updatedAt: number; }
export interface V2 extends V1 { weightGram: number; owner: string;
revision: number; deleted: boolean; }
interface Stored { schemaVersion: number; items: unknown[] }
function migrateV1(items: V1[]): V2[] {
return items.map(item => ({
id: item.id, title: item.title, category: item.category,
packed: item.packed === true, updatedAt: item.updatedAt,
weightGram: 0, owner: '未指定', revision: 1, deleted: false
}));
}
export function migrate(raw: Stored): {schemaVersion: 2; items: V2[]} {
if (raw.schemaVersion === 2) {
if (!Array.isArray(raw.items) || raw.items.some(v =>
!v || typeof v.id !== 'string' || typeof v.title !== 'string')) {
throw new Error('字段校验失败');
}
return { schemaVersion: 2, items: raw.items as V2[] };
}
if (raw.schemaVersion !== 1 || !Array.isArray(raw.items)) {
throw new Error('未知的清单数据版本');
}
const next = migrateV1(raw.items as V1[]);
if (next.some(v => !v.id || !v.title)) throw new Error('字段校验失败');
return { schemaVersion: 2, items: next };
}
// 调用处应先保留 raw,校验通过后一次写回新快照。
从源码阅读顺序看,先定位 services/migrate.ts 中的输入,再找到 schemaVersion 相关调用,最后确认界面状态或存储写回点。第一件事是确定调用的输入从哪里来:它可能来自路由参数、响应式状态,也可能来自本地持久化。第二件事是确定输出由谁消费:不应让 UI 组件直接承担重试协议或数据迁移。第三件事是检查失败路径是否有出口,不能永远停在加载中。
代码里最值得注意的是边界上的显式判断。它比向页面堆一个万能 catch 更有价值,因为不完整的数据、权限拒绝和无法联网,分别决定了用户接下来能做什么。业务组件只接收已经整理好的返回结果,才能独立处理加载、取消与重进页面。 这正是把逻辑拆成可测试片段的原因:当业务规则改变时,可以只替换数据整形或平台适配逻辑,而不用让每个点击处理函数再次复制错误分支。

容器升级和数据升级不同
本地缓存的清理策略由宿主容器决定,迁移不是数据备份服务。App 卸载、小程序缓存清除或浏览器存储策略造成的真实删除,不能靠 schemaVersion 恢复。
Web / H5:H5 用户可能从多个浏览器版本进入同一站点,迁移应对老格式采取只读检查,不要在读取瞬间立即删除原数据。 在“数据修复”的部署检查里,必须使用正式目标域名和真实构建产物再走一次主操作;调试服务器的放宽策略、浏览器缓存和桌面设备输入方式都可能掩盖差异。
微信小程序:小程序更新版本后同一用户可能保留此前缓存,应该为迁移输入准备不同版本的样本,而不是只测新安装。 需要将开发者工具调试结果和用户手机上的表现分开保存,重点核对对应权限、域名、生命周期及页面栈规则,避免在调试工具开启“不校验”后宣布兼容。
App:App 升级后的本地记录通常仍存在,需要检查旧版字段、类型和数值单位都按约定迁移;卸载并不属于升级场景。 iOS 与 Android 还应独立执行安装和重进页面流程;涉及鸿蒙 Next 时需遵循 uni-app Vue3 的鸿蒙开发专题与目标 HBuilderX 版本,不能直接假设传统 plus 模块在鸿蒙上可用。
三端一致的部分应尽量体现在数据契约与业务语义中,三端不同的部分则应被清楚标识。比如“数据修复”对用户呈现的保存、取消、重试这些动作应同义,但它们内部调用的权限检查、资源路径或系统接口可以不同。只有这样,平台迁移才不会变成整页复制。

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

所有评论(0)