Lua Academy · 课时

打包插件

Q: 「打包插件」这节课中我会学到什么？

组织并分享插件。 你通过在浏览器中直接运行的动手代码来练习 Lua Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

组织并分享插件。

打包插件 是 CoddyKit 上的免费 Lua Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Lua Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Lua Academy 课程共包含 4 节课。

插件目录结构

Neovim 插件本质上就是 runtimepath 上的一个目录。按照惯例，插件的顶层文件夹具有特定用途，Neovim 会对它们进行特殊处理。

主要目录包括：用于模块的 lua/、用于自动加载初始化代码的 plugin/、用于文件类型脚本的 ftplugin/、用于帮助文档的 doc/，以及用于后期覆盖的 after/。

-- myplugin/
--   lua/myplugin/init.lua
--   plugin/myplugin.lua
--   doc/myplugin.txt

lua/ 目录

lua/ 下的文件可以通过 require 访问。位于 lua/myplugin/init.lua 的模块会作为 require('myplugin') 加载。

嵌套目录会对应点分路径：lua/myplugin/config.lua 会变为 require('myplugin.config')。插件正是通过这种方式提供简洁的公共命名空间。

-- in lua/myplugin/init.lua
local M = {}
function M.hello() print('hi') end
return M

返回模块表

惯用的模块模式是声明一个局部表 M，向其挂载函数，然后返回它。调用方就可以访问 require('myplugin').hello()。

请将内部辅助函数保留为普通局部函数，这样只有预期的接口会对外公开。这与其他生态系统中的模块封装方式相似。

local M = {}
local function private() end
function M.run() private() end
return M

setup() 约定

大多数插件都会提供一个 setup(opts) 函数。它会将用户选项与默认值合并，并执行初始化操作，例如创建命令和自动命令。

请使用 vim.tbl_deep_extend('force', defaults, opts or {})，这样即使用户只提供部分配置，也能获得所有默认值。

local M = {}
local defaults = { width = 40 }
function M.setup(opts)
  M.config = vim.tbl_deep_extend('force', defaults, opts or {})
end
return M

plugin/ 目录

plugin/ 中的脚本会在 Neovim 启动时自动运行，此时 runtimepath 已经构建完成。请让这些脚本保持精简。

常见用途是注册命令或设置加载保护机制，让大型模块按需延迟加载。请避免在这里执行开销大的操作；将其推迟到 setup 或自动命令中，以保持快速启动。

-- in plugin/myplugin.lua
if vim.g.loaded_myplugin then return end
vim.g.loaded_myplugin = true

加载保护

如果文件被加载两次，加载保护可以防止重复初始化。请设置一个 vim.g.loaded_* 标志，并在再次进入时立即退出。

这非常重要，因为插件管理器和 :runtime 都可能再次加载文件，而重复的命令或自动命令会导致隐蔽错误。

if vim.g.loaded_myplugin == 1 then return end
vim.g.loaded_myplugin = 1

延迟加载

快速启动意味着只在需要时加载代码。请在 plugin/ 中注册一个轻量级命令，让它在首次使用时加载大型模块。

lazy.nvim 等插件管理器通过 cmd、ft 和 keys 触发器将这一机制标准化，因此在模块被调用之前，它都不会被加载。

vim.api.nvim_create_user_command('MyStart', function()
  require('myplugin').run()
end, {})

运行时路径与包路径

Neovim 会通过扫描 runtimepath 来发现插件。原生软件包系统会自动加载 pack/*/start/ 下的目录，并通过 :packadd 按需加载 pack/*/opt/ 下的目录。

大多数用户依赖插件管理器，但理解 runtimepath 有助于您了解 Neovim 如何找到这些文件夹。

print(vim.o.runtimepath:sub(1, 60))
-- :packadd loads an opt plugin manually

健康检查

请提供一个包含 check 函数的 lua/myplugin/health.lua，这样用户就可以运行 :checkhealth myplugin。请使用 vim.health 接口报告状态。

请使用 vim.health.start、vim.health.ok、vim.health.warn 和 vim.health.error，清楚地指出缺失的依赖项。

local M = {}
function M.check()
  vim.health.start('myplugin')
  vim.health.ok('all good')
end
return M

文档与标签

请提供一个 doc/myplugin.txt 帮助文件。运行 :helptags doc/（或让插件管理器完成此操作）来生成标签索引，这样 :help myplugin 就能正常工作。

优秀的文档应列出命令、setup 选项和默认按键映射，让用户可以在 Neovim 内部找到您的插件。

-- generate tags from the doc directory
vim.cmd('helptags ' .. vim.fn.expand('%:p:h'))

版本管理与发布

请将插件托管在 git 仓库中；用户可以通过 owner/repo 路径安装它。请遵循语义化版本规范为发布版本添加标签，以便插件管理器固定版本。

请提供一个 README，其中包含适用于常用插件管理器的安装代码片段、许可证和最小配置示例，从而降低用户采用插件的门槛。

-- lazy.nvim spec
-- { 'owner/myplugin', config = function()
--     require('myplugin').setup({})
--   end }

快速检查

请确认您对插件打包的理解。

回顾：打包插件

插件是一个位于 runtimepath 上的目录，其中包含 lua/ 模块、自动运行的 plugin/ 脚本，以及可选的 doc/、ftplugin/ 和健康检查文件。

请返回模块表，提供一个合并默认值的 setup，防止重复加载，延迟加载大型代码，通过帮助标签编写文档，并使用带有语义化版本标签的 git 发布插件。

常见问题解答

「打包插件」课时是免费的吗？

是的 — 「打包插件」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Lua Academy 课程的其余内容，请升级到 CoddyKit PRO。 Lua Academy 课程共包含 4 节课。

「打包插件」这节课中我会学到什么？

组织并分享插件。你通过在浏览器中直接运行的动手代码来练习 Lua Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Lua Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Lua Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「打包插件」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Lua Academy 课中编写并运行代码吗？

能。每节 Lua Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Lua Academy