📚 Neovim 学习系列
阶段一：安装与入门 ✅
✓ 01 安装与入门
阶段二：核心操作与编辑语法 ✅
✓ 02 核心操作与编辑语法
阶段三：缓冲区/窗口/标签页 ✅
✓ 03 缓冲区/窗口/标签页
阶段四：Lua 基础与配置
04 Lua 基础与配置（当前篇）
阶段五至八共4篇，后续持续更新
读完本篇你将能：读懂 Lua 基本语法（table / function / require），用 vim.opt 设置选项，用 vim.keymap.set 绑定快捷键，用 kickstart.nvim 模板快速搭建自己的 Neovim 配置。
📑 本文目录
01Lua 语言基础
02Neovim 配置体系与 init.lua
03选项设置：vim.opt
04键位映射：vim.keymap.set
05autocmd 自动命令
06kickstart.nvim 起步
Neovim Lua 配置入门：init.lua 与 kickstart.nvim
难度：进阶 | 阅读约 22 分钟
01 Lua 语言基础
Neovim 选择 Lua 作为配置语言而非传统的 Vimscript，因为 Lua 快、轻、嵌入简单。配置 Neovim 只需要掌握 Lua 的几个核心概念，不需要学完整个语言。
配置 Neovim 用到的 Lua 语法只占语言全貌的 20%。以下是必须掌握的三个核心：
变量与数据类型
Lua
-- 局部变量用 local，全局变量不推荐
local name = "neovim"
local version = 0.12
local is_active = true
-- 字符串拼接用 ..
local msg = name .. " v" .. version
table（表）—— Lua 唯一的复杂数据结构
Lua 没有 dict、list、set 的区分——全靠 table 一个结构。既当数组又当字典，Neovim 配置中大量使用 table。
Lua
-- 当字典用（键值对）
local opts = {
noremap = true,
silent = true,
desc = "保存文件"
}
-- 当数组用（索引从1开始！）
local colors = { "red", "green", "blue" }
-- colors[1] == "red"，不是 colors[0]
⚠️ 常见错误
Lua 数组从 0 开始 — Lua 索引从 1 开始！colors[0] 是 nil（空值），colors[1] 才是第一个元素。这是 C/Python 背景的人最常踩的坑。
function（函数）与 require（模块加载）
Lua
-- 定义函数
local function save_file()
vim.cmd("w")
end
-- 加载模块（另一个 .lua 文件）
local options = require("config.options")
-- require 查找路径：
-- ~/.config/nvim/lua/config/options.lua
require() 是 Lua 的模块加载函数。当配置文件变大后，你把它拆分成多个 .lua 文件，用 require() 在 init.lua 中引入。查找路径是 ~/.config/nvim/lua/ 下的对应文件。
02 Neovim 配置体系与 init.lua
Neovim 的配置入口是 init.lua，位于 ~/.config/nvim/init.lua（macOS/Linux）或 ~/AppData/Local/nvim/init.lua（Windows）。Neovim 启动时自动执行这个文件。
| 配置文件 |
路径 |
说明 |
init.lua |
~/.config/nvim/init.lua |
启动入口，所有配置从这里开始 |
lua/ 子目录 |
~/.config/nvim/lua/ |
模块目录，用 require 加载 |
:checkhealth |
命令行 |
诊断配置问题 |
修改配置后，用 :source % 在当前文件中重新加载，或者重启 Neovim。% 代表当前文件名。
03 选项设置：vim.opt
选项就是你在 Normal 模式下用 :set 设置的东西。在 Lua 中，用 vim.opt 设置，行为和 :set 完全一致。
Lua (~/.config/nvim/init.lua)
-- 行号
vim.opt.number = true
vim.opt.relativenumber = true
-- 缩进
vim.opt.tabstop = 2
vim.opt.shiftwidth = 2
vim.opt.expandtab = true
-- 搜索高亮
vim.opt.hlsearch = true
vim.opt.incsearch = true
-- 系统剪贴板
vim.opt.clipboard = "unnamedplus"
-- 真彩色支持
vim.opt.termguicolors = true
每个选项的含义可以用 :help '选项名' 查看。比如 :help 'tabstop'。这是写配置时最常用的查询方式。
💡 小贴士
vim.opt vs vim.o：前者像 :set，后者像直接读写变量。vim.opt.number = true 和 vim.o.number = true 效果相同。但 vim.opt 能正确处理 list 类型选项（如 vim.opt.listchars），推荐统一用 vim.opt。
04 键位映射：vim.keymap.set
键位映射是 Neovim 配置的核心——把常用操作绑到好按的键上。API 是 vim.keymap.set(mode, key, action, opts)，四个参数：
| 参数 |
含义 |
示例 |
| mode |
模式 |
"n" Normal / "i" Insert / "v" Visual |
| key |
触发的按键 |
"<leader>w" |
| action |
执行的操作 |
":w<CR>" 或函数 |
| opts |
附加选项 |
{noremap=true, silent=true, desc="保存"} |
Lua
-- 设置 leader 键（默认 \，改为空格更顺手）
vim.g.mapleader = " "
-- 空格+w 保存
vim.keymap.set("n", "<leader>w", "<cmd>w<CR>",
{ noremap = true, silent = true, desc = "保存文件" })
-- 空格+q 退出
vim.keymap.set("n", "<leader>q", "<cmd>q<CR>",
{ noremap = true, silent = true, desc = "退出" })
-- Esc 清除搜索高亮
vim.keymap.set("n", "<Esc>", "<cmd>nohlsearch<CR>",
{ silent = true })
-- 在 Insert 模式中用 jk 回到 Normal
vim.keymap.set("i", "jk", "<Esc>",
{ noremap = true, desc = "退出Insert" })
noremap = true 表示非递归映射——按下的键不会触发其他映射，避免循环引用。silent = true 表示执行命令时不显示底部消息。desc 是描述文字，后续用 which-key 插件时会显示为提示文本。
⚠️ 常见错误
忘加 noremap = true — 不加 noremap 时是递归映射。如果你把 x 映射到 dd，又把 d 映射到别的命令，dd 会触发新映射而非原始 dd。95% 的场景都应该加 noremap。
05 autocmd 自动命令
autocmd 是"事件驱动"——当某件事发生时（打开文件、离开窗口、输入文本）自动执行操作。比如打开 YAML 文件自动设 2 空格缩进，或者保存时自动格式化。
Lua
-- 创建 autocmd 组（避免重复加载）
local grp = vim.api.nvim_create_augroup("MyConfig", {})
-- 打开 YAML 文件时设缩进
vim.api.nvim_create_autocmd("FileType", {
pattern = "yaml",
group = grp,
callback = function()
vim.opt.tabstop = 2
vim.opt.shiftwidth = 2
end,
})
-- 保存 Lua 文件时自动重新加载
vim.api.nvim_create_autocmd("BufWritePost", {
pattern = "*.lua",
group = grp,
callback = function(ev)
vim.cmd("source " .. ev.file)
end,
})
augroup 的作用是分组管理——每次 :source 重新加载配置时，同名组内旧的 autocmd 会被清除，避免重复注册导致同一事件触发多次。
06 kickstart.nvim 起步
从零手写 init.lua 需要面对大量样板代码。Neovim 官方推荐的 kickstart.nvim 是一个单文件配置模板——一个 init.lua，约 600 行，注释完善，包含了选项设置、键位映射、插件管理、LSP、补全等基础设施。
它的价值不在于"直接用"，而在于"边读边改"——你逐段阅读注释，理解每段配置的作用，然后按自己需求修改。这比从空白文件开始高效得多。
Shell
# 备份原有配置（如有）
mv ~/.config/nvim ~/.config/nvim.bak
# 克隆 kickstart.nvim
git clone https://github.com/nvim-lua/kickstart.nvim.git \
~/.config/nvim
# 启动 Neovim，自动安装插件
nvim
kickstart.nvim 内置了 lazy.nvim 插件管理器（下一篇详细讲），所以首次启动会自动下载并安装配置中声明的所有插件。启动后你看到的是一个完整的 Neovim 环境——有语法高亮、有 LSP、有补全、有快捷键提示。
kickstart.nvim 的配置结构：
| 配置段落 |
作用 |
本章涉及 |
Setting options |
vim.opt 选项设置 |
✓ 本篇第 03 节 |
Basic Keymaps |
vim.keymap.set 基础键位 |
✓ 本篇第 04 节 |
Autocmds |
vim.api.nvim_create_autocmd |
✓ 本篇第 05 节 |
lazy.nvim |
插件管理器引导 |
→ 下一篇详解 |
colorscheme |
主题配色 |
下方说明 |
colorscheme 通过 Lua 设置：vim.cmd.colorscheme("tokyonight")。kickstart 默认用 tokyonight 主题。要换主题，先确保已通过 lazy.nvim 安装对应插件，再修改这一行。注意 vim.cmd 用于执行 Vimscript 命令，:colorscheme 没有纯 Lua 等价物。
💡 小贴士
kickstart.nvim 的设计理念是"单文件可读"。如果你更喜欢多文件结构，可以把它拆分到 lua/ 目录下，但建议先在单文件状态下阅读完整注释，理解整体结构后再拆分。过早拆分会丢失上下文。
🎯 分级练习
基础（巩固记忆）
1.创建 ~/.config/nvim/init.lua，写入 print("Hello from Lua")，启动 Neovim 确认输出
2.用 vim.opt 设置行号和缩进，修改后 :source % 确认生效
3.用 vim.keymap.set 绑定 <leader>w 保存文件
进阶（组合应用）
4.写一个 autocmd：打开 Python 文件时自动设 4 空格缩进，YAML 设 2 空格
5.克隆 kickstart.nvim 到 ~/.config/nvim，启动后逐段阅读注释，找到选项设置部分
6.修改 kickstart 中的 colorscheme 行，切换到其他内置主题（如 vim.cmd.colorscheme("habamax")）
挑战（综合实战）
7.在 kickstart 基础上自定义：设置 leader 为空格、绑定 5 个常用快捷键（保存/退出/清除高亮/切换 buffer/分屏），加 desc 描述
8.创建 ~/.config/nvim/lua/options.lua 和 keymaps.lua，在 init.lua 中用 require 加载
#Lua基础
#init.lua
#vim.opt
#vim.keymap.set
#autocmd
#kickstart.nvim
#require模块
下一篇预告
05 插件管理 — kickstart.nvim 给你搭好了配置骨架，下一篇将深入 lazy.nvim 插件管理器：spec 结构、lazy loading 按需加载、事件驱动模式，以及第一批效率插件（which-key 键位提示、lualine 状态栏、surround 配对编辑、comment 注释、indent-blankline 缩进线等）的安装与配置。