You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

2.6 KiB

应用配置与升级迁移

配置文件位于 userData/settings.json。应用身份与用户数据目录应在升级期间保持稳定,否则会读取另一份配置。

应用配置由 src/main/settings/store.ts 管理;通用 JsonStore 保持原有行为,数据库、诊断队列和凭据不会套用配置迁移。RPC 仍只返回 Settings,不暴露磁盘版本元信息。

磁盘格式:

{
  "version": 1,
  "settings": {
    "theme": "dark",
    "language": "zh",
    "launchAtLogin": false,
    "diagnosticUpload": false,
    "window": { "width": 1160, "height": 780 }
  }
}

无版本号的旧文件视为版本 0,自动迁移至版本 1。配置版本独立于应用版本,只有配置格式或含义发生变化才递增。

版本降级保护适用于已采用此机制的程序;早期没有版本校验的程序无法识别新格式,不应直接回退到这些版本。

改动 行为
修改默认值 保留合法用户值,默认值只补缺失字段
新增字段或嵌套对象字段 按 schema 默认配置补齐
删除字段 从新文件中移除,原值留在迁移备份中
无效字段 只恢复该字段默认值,保留其他合法值
字段重命名、类型或含义改变 先通过显式迁移转换旧值,再校验
完整 JSON 损坏 备份原文件后恢复默认配置
配置版本高于程序支持版本 拒绝启动,保持原文件,避免旧程序破坏新配置

修改配置结构时,在 settingsMigrations 末尾追加一个连续版本的 migrate 函数,并更新 settingsSchema 及相关 API。不要修改已经发布的迁移。例如未来将 locale 改名为 language:

{
  version: 2,
  migrate: (value) => ({ ...value, language: value.language ?? value.locale })
}

迁移只处理内存对象,不执行网络、文件或其他副作用。所有迁移完成并校验后才写入文件;异常时不写盘。数组和其他整体值按字段校验,数组内容需要自定义转换时应在迁移函数里处理。

替换已有文件前会生成同目录的时间戳与 UUID .bak 备份,备份失败或读写失败会终止启动。正常重复启动不增加备份;备份不自动清理,用户可在确认配置正常后删除。运行时设置写入仍严格校验,非法修改不会恢复默认值或改变原配置。