用户补丁（User Patches）—— KOReader 深度定制
什么是用户补丁
用户补丁是 KOReader 最强大也最危险的定制功能——允许你直接修改 KOReader 内部的 Lua 代码逻辑。如果说配置文件是"调参数"，用户补丁就是"改代码"。
两者的区别：
| 维度 | 配置文件 | 用户补丁 |
|---|---|---|
| 作用 | 调整预设参数 | 修改/替换内置 Lua 逻辑 |
| 难度 | 简单（界面操作） | 高（需要 Lua 基础） |
| 影响范围 | 单本书/某类书 | KOReader 全局行为 |
| 风险 | 无（坏了重新调） | 可能导致 KOReader 崩溃 |
新手跳过此页。只有在你觉得"KOReader 默认行为哪里都对但就差一点点"时才需要用户补丁。
用户补丁的存储位置
补丁文件放在 KOReader 配置目录下的 patch/ 子目录，通常是 .patch、.diff 或 .lua 文件。
安装社区补丁
第一步：找到补丁
KOReader 社区维护了补丁库——GitHub issues 中搜索 "user patch" 或去 MobilRead 论坛的 KOReader 专区。常见补丁类型：
| 补丁类型 | 作用 |
|---|---|
| 刷新频率调整 | 改变墨水屏刷新策略 |
| 翻页动画 | 替换默认翻页效果 |
| 菜单定制 | 增加/隐藏菜单项 |
| 排版算法 | 修改流式重排引擎 |
| 新手势 | 新增手势映射 |
| 快捷键 | 新增键盘快捷键 |
第二步：放置补丁文件
把补丁文件复制到 KOReader 配置目录的 patch/ 子目录。
第三步：重启 KOReader
重启后进入「设置 → 用户补丁」：
- 查看已识别的补丁列表
- 勾选启用
- 某些补丁需要重启才完全生效
自己写补丁
KOReader 是 Lua 编写的，补丁本质是 Lua 模块的重载或 monkey-patching。
示例：禁用双指滑动手势
-- patch/disable_two_finger_swipe.lua
local Device = require("device")
local originalGesture = Device.EventListener.onTwoFingerSwipe
Device.EventListener.onTwoFingerSwipe = function(self, gesture, direction)
-- 什么都不做，覆盖默认行为
end把上面的代码存为 patch/override_gesture.lua，启用后 KOReader 的双指滑动就失效了。
补丁调试技巧
启用日志
在 KOReader 设置中启用开发者模式，开启详细日志。补丁崩溃时日志会明确告诉你哪个文件哪一行出了问题。
逐步添加代码
不要一次把 200 行补丁放进去——先加 10 行看能不能跑，再逐步扩展。
对比原生行为
补丁前先在无补丁状态下确认 KOReader 能正常工作。补丁生效后如果行为变了，说明补丁在起作用——不管是对是错。
风险与备份
风险：用户补丁是 Lua 代码，直接执行，有 bug 就会导致 KOReader 不稳定、崩溃、甚至无法启动。
必须做的事：
- 备份配置目录：放补丁前先把 KOReader 配置目录整体复制到电脑
- 一个补丁一个文件：出问题时容易定位
- 新补丁先单启用：逐个启用，一次一个，找出是哪个有问题
- 先读代码再启用：不要启用看不懂的补丁
补丁导致 KOReader 无法启动怎么办
这是最坏情况，但一定能救回来：
- KOReader 启动前会尝试加载
patch/目录下所有补丁 - 补丁有 bug → KOReader 启动时崩溃 → 循环崩溃 → 无法进入界面
- 修复方法：用文件管理器（USB 连接/KOReader SSH/SFTP）进入 KOReader 配置目录 → 删除问题补丁文件 → 重启 KOReader
所以一定要一个补丁一个文件——删哪个一目了然。
与插件的区别
| 维度 | 用户补丁 | 插件 |
|---|---|---|
| 定位 | 替换内部逻辑 | 增加新功能 |
| 稳定性 | 可能影响全局 | 模块化，崩溃隔离 |
| 更新 | 随 KOReader 更新可能失效 | 随 OTA 一并更新 |
| 推荐度 | 仅进阶用户 | 所有用户 |
常见问题
补丁随 KOReader 更新会失效吗？
可能。KOReader 的 Lua 代码结构会随版本变化——补丁引用的模块名、函数签名可能变了。如果补丁让新版本 KOReader 崩溃，去社区找对应新版本的补丁。
多个补丁冲突？
可能。如果两个补丁都替换了同一个内部函数，只有后加载的那个生效。解决方法：合并补丁，或改用插件系统。
能不能在 Kindle KOReader 上用？
可以。用户补丁是 Lua 层面的，不受平台限制——只要 KOReader 支持该 Lua 模块。