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
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 备份,备份失败或读写失败会终止启动。正常重复启动不增加备份;备份不自动清理,用户可在确认配置正常后删除。运行时设置写入仍严格校验,非法修改不会恢复默认值或改变原配置。