手动修改兼容配置
游戏内能调的都在界面里，但总有需要动手的时候：批量改、从别人的配置里抄一段、修一份已经失效的旧配置。这一页讲清改哪一层、怎么改、改坏了怎么退回去。
一、先确认你改的是哪一层
| 目录 | 谁写的 | 你改了会怎样 |
|---|---|---|
compat/default/ |
从 JAR 释放 | 升级模组时被覆盖 —— 不要改这里 |
compat/mods/ |
桥接模组安装 | 桥接升级时被覆盖，同样只读 |
compat/user/ |
游戏内编辑、Apply、你自己 | 优先级最高，不会被覆盖（Apply 会先备份再覆盖） |
覆盖是整份替换，不是字段合并：同一个 mod_id，只要 user 层有文件，就整份压过 mods/ 与 default/。所以从别人那里抄一段，要连 mod_versions 一起抄全，别只抄半截。
二、方式一：游戏内编辑（推荐）
- 进 设置 → 模组适配，选中模组，切到「按键绑定」/「界面适配」/「叠层适配」。
- 改完保存，改动直接写进
compat/user/<mod_id>.json，并立即热重载该模组 —— 不用重启。 - 改错了点重置配置，该模组回到内置或已应用的社区默认（等价于删掉 user 层的这份文件）。
规则编辑始终是写时复制：内置与社区文件保持只读，UI 只往 user 层写。这也是为什么你永远不会「改坏」内置配置。
三、方式二：直接编辑 user/<mod_id>.json
- 从
compat/default/<mod_id>.json或已应用的社区文件复制一份 —— 别从零写，字段容易漏。 - 改名成
<mod_id>.json放进config/controlflex/compat/user/。文件名必须对得上，界面与热重载都按这个名字找。 - 只改你要改的字段；不需要的按键直接删掉整条。这份文件会整份生效，不是增量。
- 以 UTF-8 保存，注意别留尾逗号。
- 重启游戏生效。磁盘文件没有 watcher；只有 Apply 与游戏内编辑会走热重载。
JSON 坏掉不会崩游戏：整份文件被跳过，日志里留一条解析错误。所以改完先看日志，别先怀疑手柄。
四、方式三：从配置源手动取一份
不想在游戏里点同步也行：在 cfx-compat-configs 里找到 <mc-version>/<loader>/mods/<mod_id>.json，下载后直接放进 compat/user/ 并重启。适合给整合包预置，或给不方便联网的机器用。
这种方式不会写入 .applied.json，游戏内变体列表不会显示「已应用」，但配置本身照常生效。
五、手改时最容易踩的坑
| 坑 | 说明 |
|---|---|
mod_versions 顺序 |
首个匹配生效；宽区间写在前面会吞掉后面所有版本，通配 "" 一定放最后。 |
| 版本区间语法 | 写坏（缺括号 / 逗号、下界大于上界）→ 整条 entry 被丢弃，不只是这一个字段。 |
| 三个分区必须是对象 | 旧的数组写法会被整段丢弃并警告。 |
分区里的 channels |
它是保留键，表示该分区的默认通道，不会被当成按键名。 |
channels: [] |
显式的空数组有含义：这个键什么都不派发，跟省略字段完全不同。 |
phasePersistentKeys |
必须同时在两个分区里声明该键，只写配对会被忽略（会警告）。 |
mod_id |
必须是已安装模组的 ID；装的是 epicfight，写成 epic_fight 就永远不激活。 |
| 编码 | UTF-8、无尾逗号；Windows 记事本注意别存成 UTF-16，提示文案会直接变乱码。 |
六、改坏了怎么退回去
- 游戏内重置配置 → 回到内置或已应用的社区默认。
- 直接删掉
compat/user/<mod_id>.json→ 自动回落到mods/或default/。 - Apply 覆盖前的旧文件在
compat/backup/<mod_id>-<yyyyMMdd-HHmmss>.json（同一秒内多次备份会加-1、-2）。 - 已应用的记录在
compat/user/.applied.json，以点开头，不会被当成配置解析。
回退之后建议看一眼日志，确认现在生效的是哪一份文件 —— 尤其是你把同一份配置放过好几个层的时候。
七、把改动带进整合包
把 compat/user/*.json 连同 profiles/ 一起放进整合包的 overrides（CurseForge / Modrinth 的 overrides/config/controlflex/）。玩家自己的改动仍然写在 user 层，优先于你预置的文件；但记住整份覆盖语义 —— 玩家一旦编辑同一个 mod_id，你预置的那份就不再参与。
模组升级后 mod_versions 可能不再匹配，配置会静默失效。发版前用新版本模组跑一遍，并在日志里确认配置真的加载了。