兼容与迁移
磁盘格式变化、当前兼容窗口和检查旧数据的方法。
Last updated on
本登记表收录当前仍有兼容读取路径的变化。使用指南只讲现状；这里记录你可能仍持有的旧数据。手动改文件或跨多个版本升级前，请另行备份实例主目录和重要存档。
兼容登记表
| 首次变更版本 | 原先的数据或行为 | 现在的形式 | 最后兼容版本 |
|---|---|---|---|
| 1.10.0 | 所有应用数据集中于 ~/.trident/ | 新安装按平台分别存放配置、数据、缓存与实例 | 未公布；现有旧目录仍被选用 |
| 1.11.2 | purl 字段和 repository:project@version 引用 | pref 字段和 pref://repository/project@version 引用 | 未公布；目前仍支持读取旧格式 |
| 1.13.0 | 包条目中的空 source 字符串 | 散装包没有来源（null） | 未公布；读取时归一化空字符串 |
| 1.13.1 | 旧 Patch 文档和锁定数据中的单个 Java 大版本 | 可兼容 Java 大版本集合 | 未公布；目前仍能读取 format 1 Patch 文档 |
上述项目均未公布兼容移除期限。 当前版本仍可读取表中的旧形式，因此目前并不要求先经过某个中间版本。将来移除某种读取能力前，必须在这里写明最后兼容版本及升级前的操作。读取时自动转换到内存，不代表磁盘上的每个文件、备份和快照都已改写。
数据目录布局（1.10.0）
在 1.10.0 之前，Polymerium 将设置、缓存和实例放在 ~/.trident/。新安装使用按平台分类的路径。若已有旧目录，启动器会继续选用它，不会自动把内容搬到新路径。
搬迁或删除文件前，先确认当前安装使用的主目录。如需保留或有意迁移统一的存储根目录，请关闭启动器后按自定义数据目录操作。不要仅因为新平台目录存在，就删除 ~/.trident/。
包引用（1.11.2）
旧 profile.json 的包条目和规则选择器可能使用 purl 字段；锁定数据和旧快照元数据也可能包含它。现在使用 pref 字段，值从 modrinth:aC3cM3Vq@9I21YYxf 变为 pref://modrinth/aC3cM3Vq@9I21YYxf。规则选择器类型 purl 也改为 pref。包身份和可选版本保持不变。
当前读取器会在内存中转换可识别的旧值。保存实例配置后写出 pref，但仅打开实例并不会改写所有配置、锁文件和快照。无法识别的值会保留原样，不会擅自替换成另一个包。快照数据库另行存储历史配置元数据；打开旧快照不会改写其中的旧记录。
要自行迁移文件，先备份，再把包条目及选择器中的 purl 字段改为 pref，将有效的旧引用转成 pref:// URI，同时检查规则选择器类型。data.lock.json 是生成的版本锁，请通过部署重新生成，不要手动改写。对于旧快照，请保留能读取它们的软件版本，直到你已恢复并用当前格式创建新快照；不建议手动修改快照数据库。现行术语参见 Pref。
包来源空字符串（1.13.0）
部分导入的包清单曾把散装包的 source 写成 "source": ""，并保存到 profile.json。当前读取器将其视为无来源；下次保存实例配置时会写成归一化形式。手动修改时可以移除这个空值或改为 null；不要修改非空的来源 URI，它可能标识整合包、配方或集合。
Java 兼容版本声明（1.13.1）
旧 Patch 文档使用 format 1，可用 launch.javaMajor 一类目标配合 "value": 21 声明单个 Java 大版本。当前 format 2 使用 launch.compatibleJavaMajors 和 "value": [21]，也可以与其他可接受版本取交集。旧 Patch 产物使用 javaMajor 而非 compatibleJavaMajors；旧 data.lock.json 使用 javaMajorVersion 而非版本集合。
当前读取器会把旧单值折叠为单元素集合，仍可读取 format 1 文档；读取 Patch 并不会改写原文档。如果自行维护 Patch JSON，请先备份，再把 format 改为 2，将相关操作的目标和单值改为数组形式，并核对原生 Patch 说明。版本锁由部署重新生成。将来若公布兼容期限，还应检查保留在旧整合包归档中的导入层 Patch。
将来跨过兼容截止版本前
- 跳过多个版本升级前，先在本表确认最后兼容版本和受影响的文件。
- 备份实例目录、本地保留、快照和仍需维护的整合包归档。
- 在仍兼容旧格式的版本中打开并保存受影响的实例配置，或按说明手动调整 JSON 字段；重新部署以生成新的锁定数据。
- 检查打算保留的所有副本，包括旧归档和快照。启动器从未读取的文件不会自动完成迁移。
- 核实这些副本已迁移，或接受旧副本将来可能无法读取的风险，再升级到截止版本之后。
若截止版本写着未公布，当前就没有已公布的强制迁移版本。不能仅凭更新日志或打开过新版软件，就认定所有存量数据已转换。