# 应用配置与升级迁移 配置文件位于 userData/settings.json。应用身份与用户数据目录应在升级期间保持稳定,否则会读取另一份配置。 应用配置由 src/main/settings/store.ts 管理;通用 JsonStore 保持原有行为,数据库、诊断队列和凭据不会套用配置迁移。RPC 仍只返回 Settings,不暴露磁盘版本元信息。 磁盘格式: ```json { "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: ```ts { version: 2, migrate: (value) => ({ ...value, language: value.language ?? value.locale }) } ``` 迁移只处理内存对象,不执行网络、文件或其他副作用。所有迁移完成并校验后才写入文件;异常时不写盘。数组和其他整体值按字段校验,数组内容需要自定义转换时应在迁移函数里处理。 替换已有文件前会生成同目录的时间戳与 UUID .bak 备份,备份失败或读写失败会终止启动。正常重复启动不增加备份;备份不自动清理,用户可在确认配置正常后删除。运行时设置写入仍严格校验,非法修改不会恢复默认值或改变原配置。