企业官网建设流程全解析

KOReader插件开发避坑指南：新手最常踩的5个坑，一次讲清

【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader

KOReader 是一款支持 PDF、EPUB、DjVu、FB2 等格式的开源电子书阅读器，跑在 Kindle、Kobo、PocketBook 和 Android 上。给 KOReader 扩展功能最快的路就是写个 Lua 插件，而第一次做 KOReader插件开发 的人，几乎都会在下面这五件事上卡住。每节都独立成篇，卡在哪就跳去哪。

为什么 main.lua 放好了却没反应：目录名差一个后缀

加载器在扫描目录时，只认以.koplugin结尾的文件夹，插件名直接取目录名去掉后缀。名字差一个点、多个空格，这个目录会被静默跳过——不报错，也不提示，菜单里就是没有它。放自定义插件的位置有两处：源码树里的plugins/目录，以及阅读器数据目录下的plugins/子目录，把myplugin.koplugin放进任一处都会被扫描到。

需要对照官方实现时，git clone https://gitcode.com/GitHub_Trending/ko/koreader拉一份源码只做本地参考，plugins/ 目录 里每个官方插件都是现成的范本，仓库是只读的，别在里头动手改。

⚠️ 命名规则就一条：xxx.koplugin，全小写、带后缀。差一个字符，插件约等于不存在。

菜单注册其实就三行：_meta.lua 和 main.lua 的分工

_meta.lua是插件名片：fullname显示在插件管理菜单里，description是它下面的说明，两处都套上 gettext 的_()，以后做翻译才不会漏。main.lua是插件本体，加载器靠它return出来的表判断"加载成功"——忘了return，插件在加载时直接报错消失，网上 Lua 插件教程讲得最透的结构就是这个分工。

入口注册分两步：init()里调self.ui.menu:registerToMainMenu(self)这一行完成"把插件挂进菜单"；然后在addToMainMenu里往menu_items塞一张表，hello.koplugin 官方示例 就是这套结构的最小形态。

main.lua里真正要写的其实只有这个函数：text是菜单文字，sorting_hint决定挂在哪个菜单组（more_tools即"更多工具"），callback是点下去要干的事。

function MyPlugin:addToMainMenu(m) m.my_plugin = { text = _("My Plugin"), sorting_hint = "more_tools", callback = function() UIManager:show(InfoMessage:new{ text = _("Hi") }) end, } end

💡 先照抄 hello 的结构改三行字跑通，再谈功能——能跑通，才轮到谈功能。这就是 ko 插件制作 的地基。

设置存到哪、怎么读回来：用 LuaSettings 别手搓

新手最常见的错误是用os.execute或写死一个绝对路径去存设置——换台设备，路径就全变了。正确姿势是LuaSettings：一个帮你把 Lua 表读写成文件的小工具，配合格式化的文件存进设备数据目录，gestures 插件的settings_file就指向DataStorage:getSettingsDir()下的专属文件。

device参数取"global"表示整机一份设置，取"doc"表示每本书一份——字体大小这种偏好就该是 doc 级，亮度偏好则是 global 级。

设置文件指向数据目录：self.settings = LuaSettings:new{ device = "global", file = DataStorage:getSettingsDir() .. "/myplugin.lua" }，之后self.settings:saveSetting("font_size", 24)一行落盘，readSetting原样读回，读写都不用碰文件本身。

插件崩了为什么没提示：调试日志怎么开

加载器会把插件里所有以on开头的事件处理函数包进沙箱，用pcall捕获异常——报错不会弹到屏幕上，只会写进日志。所以"菜单点了没反应"九成是callback里抛了异常，屏幕上的安静不等于没出错。

排查靠logger.dbg：它输出的行带DEBUG前缀，大多数平台上落在阅读器数据目录的crash.log里。doc/Hacking.md 还有一句要紧的提醒：Lua 的函数参数永远先求值，别往 logger 里内联复杂表达式，真需要就先用if包一层。

打一行调试日志，重启后翻crash.log里第一处DEBUG：

local logger = require("logger") logger.dbg("myplugin: got", value)

改界面别每次都重启整个阅读器：在源码根目录跑./kodev wbuilder，它会起一个最小 UI 环境，widget 的改动几秒内就能在窗口里看到效果。

💡 界面调试用 wbuilder 走秒级反馈，行为调试翻 crash.log，两条路别混着走。

没有触摸屏的机器上，你的插件跑得动吗

KOReader 是跨平台项目，同一段代码既跑在纯触屏墨水屏上，也跑在带实体按键的 Kindle 上。官方 gestures 插件在main.lua开头就检查Device:isTouchDevice()，不是触屏直接return { disabled = true }，加载器看到disabled就把它移进禁用列表；hotkeys 的默认键位则按Device:hasKeyboard()逐条开关。做 koreader 自定义 插件时照这个套路：能力检查放最前，没有就干净利落地禁用，而不是让功能在半残状态里报错。

main.lua开头先问设备要能力，没有就直接声明禁用，后面一行都不会执行：

local Device = require("device") if not Device:isTouchDevice() then return { disabled = true } end

现在重启阅读器，打开 设置 → 插件管理，确认你的插件出现在列表里且开关是开的；再点一次你注册的菜单入口，弹不出提示就去crash.log里找第一行DEBUG——五个坑里只要还有任何一个没过，答案都在那行日志里。

【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader