Neovim 插件工程化：从架构到发布的完整指南

-- 一个现代插件的入口文件：lua/hello_nvim/init.lua
local M = {}

-- setup() 约定：接收用户配置，合并默认值
function M.setup(opts)
    opts = vim.tbl_deep_extend("force", {
        greet = "Hello",
        keymaps = true,
    }, opts or {})

    if opts.keymaps then
        vim.keymap.set("n", "<leader>h", function()
            print(opts.greet .. ", Neovim!")
        end)
    end
end

return M

hello-nvim/
├── lua/
│   ├── hello_nvim/
│   │   ├── init.lua       # 入口，提供 setup()
│   │   ├── commands.lua   # 命令注册
│   │   ├── lsp.lua        # LSP 相关逻辑
│   │   └── ui/
│   │       └── picker.lua # UI 组件
│   └── hello_nvim.lua     # 可选：单文件入口
├── plugin/                # 启动时自动加载的脚本
│   └── hello_nvim.lua
├── doc/
│   └── hello-nvim.txt     # help 文档
├── tests/
│   └── ...
└── README.md

-- plugin/hello_nvim.lua —— 启动时只注册命令
local function setup_commands()
    -- 使用 nvim_create_user_command，命令体在调用时才 require 模块
    vim.api.nvim_create_user_command("HelloStats", function()
        require("hello_nvim.stats").show()
    end, {})
end

setup_commands()

local M = {}

function M.setup()
    -- 用户命令：支持范围、参数、补全
    vim.api.nvim_create_user_command("Hello", function(args)
        local who = args.args ~= "" and args.args or "World"
        vim.notify("Hello, " .. who .. "!", vim.log.levels.INFO)
    end, {
        nargs = "*",
        range = true,
        complete = function(arg_lead)
            return { "Neovim", "Lua", "Plugin" }
        end,
    })
end

return M

local M = {}

function M.setup()
    local group = vim.api.nvim_create_augroup("HelloNvim", { clear = true })

    -- 文件类型事件：进入 Lua 文件时启动统计
    vim.api.nvim_create_autocmd("FileType", {
        group = group,
        pattern = "lua",
        callback = function(ev)
            require("hello_nvim.stats").start_for(ev.buf)
        end,
    })

    -- Buffer 事件：写入时格式化
    vim.api.nvim_create_autocmd("BufWritePre", {
        group = group,
        pattern = "*.lua",
        callback = function()
            local changed = vim.lsp.buf.format({ async = false })
            -- changed 为 true 表示有格式化
        end,
    })
end

return M

-- lua/hello_nvim/lsp.lua
local M = {}

function M.setup()
    local lspconfig = require("lspconfig")

    lspconfig.lua_ls.setup {
        on_attach = function(client, bufnr)
            -- 为 attach 的 buffer 设置 LSP 相关 keymap
            vim.keymap.set("n", "gd", vim.lsp.buf.definition, { buffer = bufnr })
            vim.keymap.set("n", "K", vim.lsp.buf.hover, { buffer = bufnr })
            vim.keymap.set("n", "<leader>rn", vim.lsp.buf.rename, { buffer = bufnr })
        end,
        capabilities = {
            -- 声明支持补全列表项
            textDocument = {
                completion = { completionItem = { snippetSupport = true } },
            },
        },
    }
end

return M

-- 用自定义浮窗展示 hover 结果
vim.lsp.handlers["textDocument/hover"] = function(_, result, ctx, config)
    local contents = result.contents
    local lines = vim.lsp.util.convert_input_to_markdown_lines(contents)
    vim.lsp.util.open_floating_preview(lines, "markdown", {
        border = "rounded",
        max_width = 60,
    })
    return true
end

vim.api.nvim_create_autocmd("BufWritePre", {
    callback = function()
        local bufnr = vim.api.nvim_get_current_buf()
        local clients = vim.lsp.get_clients({ bufnr = bufnr })
        for _, client in ipairs(clients) do
            if client.server_capabilities.codeActionProvider then
                -- 触发 quickfix 类代码动作
            end
        end
    end,
})

-- 遵循 vim.ui 抽象，UI 后端可被替换
local M = {}

function M.pick(items)
    vim.ui.select(items, {
        prompt = "选择一个选项:",
        format_item = function(item)
            return "[" .. item.id .. "] " .. item.name
        end,
    }, function(choice)
        if choice then
            vim.notify("你选择了: " .. choice.name)
        end
    end)
end

return M

-- lua/hello_nvim/ui/picker.lua
local M = {}

function M.picker(items, on_choose)
    local buf = vim.api.nvim_create_buf(false, true)   -- 临时 buffer
    vim.api.nvim_buf_set_lines(buf, 0, -1, false, items)

    local width = 40
    local height = math.min(10, #items)
    local opts = {
        relative = "editor",
        row = math.floor((vim.o.lines - height) / 2),
        col = math.floor((vim.o.columns - width) / 2),
        width = width,
        height = height,
        border = "rounded",
        style = "minimal",
    }
    local win = vim.api.nvim_open_win(buf, true, opts)

    -- 按键处理：回车确认、q 关闭
    vim.keymap.set("n", "<CR>", function()
        local line = vim.api.nvim_get_current_line()
        vim.api.nvim_win_close(win, true)
        if on_choose then on_choose(line) end
    end, { buffer = buf })

    vim.keymap.set("n", "q", function()
        vim.api.nvim_win_close(win, true)
    end, { buffer = buf })
end

return M

-- 默认配置集中管理，便于文档化
local defaults = {
    keymaps = {
        open = "<leader>ho",
        stats = "<leader>hs",
    },
    notifications = true,
}

function M.setup(opts)
    local config = vim.tbl_deep_extend("force", defaults, opts or {})
    -- ... 使用 config
end

-- tests/hello_spec.lua
local hello = require("hello_nvim")

describe("hello_nvim", function()
    it("setup 注册命令", function()
        hello.setup { greet = "Hi" }
        local ok = vim.fn.exists(":Hello") == 2
        assert.is_true(ok)
    end)
end)

# 用 Neovim headless 执行 plenary 测试
nvim --headless -u NONE \
  -c "PlenaryBustedFile tests/hello_spec.lua" \
  -c "qa!"

# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        nvim-version: [stable, nightly]
    steps:
      - uses: actions/checkout@v4
      - uses: rhysd/action-setup-vim@v1
        with:
          neovim: true
          version: ${{ matrix.nvim-version }}
      - run: nvim --headless -u NONE -c "PlenaryBustedFile tests/hello_spec.lua" -c "qa!"

# 发布流程示例
git tag -a v0.2.0 -m "feat: 支持浮窗选择器；fix: 清理 buffer 泄漏"
git push origin v0.2.0