Neovim：版本管理、升级与故障隔离

一次编辑器更新可能同时涉及 Neovim、LazyVim、插件、parser、语言服务器和 SDK。把这些变化一起进行，出错后就很难判断是哪一层改变了行为。维护时先记录版本，再逐层更新和验证。

锁文件能固定什么

lazy-lock.json 记录插件所使用的提交。将它与配置一起提交，可以回到已知插件组合；它不固定 Neovim 可执行文件、Mason 安装的所有外部工具、系统 SDK 或项目依赖。

详细行为见 lazy.nvim 锁文件。

升级前建立检查基线

先保存正在编辑的文件，并确认配置仓库无未解释的修改。记录 nvim --version 和当前锁文件，选择一个熟悉的小项目。

基线任务应覆盖实际使用的功能：打开文件、项目搜索、LSP 定义跳转、手动格式化、测试、中文输入与剪贴板。如果日常依赖 Zellij，再验证一次跨边界移动。

只在基线正常时升级。先阅读发行版和相关插件的变更说明，通过 :Lazy 查看待更新项；更新后执行同一组任务。仅确认“启动没有报错”不足以证明语言服务和键位没有变化。

从症状选择第一项检查

日志可能包含本地路径或项目内容。对外报告时保留足够定位的信息，并去掉与问题无关的数据。

用最小环境缩小范围

先打开同一个普通文本文件：

nvim --clean notes.md

如果问题仍在，继续检查终端、输入法或 Neovim 本身。如果消失，再通过独立 NVIM_APPNAME 配置逐项加入所需插件，不要直接删除日常配置和插件数据目录。

语法检查与执行也要区分。下面只检查某个 Lua 文件是否能被编译，不运行里面的配置：

nvim --clean --headless '+lua assert(loadfile("init.lua"))' +qa

在目标配置目录执行。通过表示 Lua 语法可解析，不证明模块存在或插件 API 兼容。

启动时间可记录为：

nvim --startuptime /tmp/nvim-startup.log +qa

使用不包含私人文件的空启动进行比较。一次快慢不能说明稳定差异，缓存和网络也会影响结果；先找到最耗时阶段，再决定是否调整插件加载事件。

恢复到已知可用状态

先保存当前故障配置和日志，再从配置仓库取回已知可用的 Lua 与锁文件。随后在 lazy.nvim 中执行 :Lazy restore，让插件回到锁文件记录的提交。

恢复后重启并重复基线任务。如果问题来自 Neovim 主程序或外部语言服务器，插件锁文件的恢复不会改变它们，需要通过对应的包管理或工具链机制处理。

不要无差别删除 data、state、cache 来“重装一遍”。这样可能同时移除插件、历史和用于定位的日志，却仍未触及真正的故障来源。

保留可维护的本地改动

优先在配置规格中覆盖公开选项。对插件内部函数的临时替换，应记录插件提交、触发场景、上游问题链接和移除条件。

旧版 smart-splits 的边界探测补丁就是这种情况：本地配置仍保留兼容覆盖，但当前已安装插件的相关实现已经返回固定结果。升级复核应检查补丁是否仍有必要，而不是把它不断复制到新环境。

每次维护最终留下两样东西：一套已验证的配置，以及一份能解释版本变化和恢复方式的简短记录。