Neovim 工程手册
Neovim 自带 LSP 客户端，不自带你的语言服务器
“Neovim 支持 LSP”常被简化成“安装后就有 IDE 能力”。实际运行链更长：Neovim 提供客户端框架和编辑器 API；配置决定 root、启动命令与能力；外部 language server 仍要由系统、项目或受控工具管理；编译、测试和 formatter 又属于项目工具链。只要其中一层从另一个 PATH、cwd 或包管理器解析，补全可以正常，构建却在另一套依赖世界失败。
Vim 的 vimrc、原生 package、quickfix 与极简远端降级见 Vim 工程手册。Neovim 能读取 Vimscript，也继承大量编辑命令，但 XDG 路径、Lua、RPC provider、内置 LSP 和发布兼容策略使它成为另一款产品，不应把两者写成同一份安装配置教程。
安装通道决定更新与回滚责任
Neovim 官方安装文档提供系统包、官方归档、AppImage、Windows ZIP/MSI 和包管理器入口。发行版仓库适合跟随系统维护，版本可能落后；官方制品能较快获得新 API，但团队必须归档校验、更新和卸载方式；nightly 只适合隔离验证，不应进入默认开发基线。
安装后不要只看欢迎页：
command -v nvim
nvim --version
nvim --clean +'lua print(vim.fn.stdpath("config"))' +q
nvim --clean +'checkhealth' +qWindows 用 Get-Command nvim 定位，尤其要排除旧 ZIP、Scoop/Chocolatey/WinGet 与手工 PATH 并存。macOS 区分 Homebrew 与官方 tarball；Linux 检查 AppImage/FUSE 或归档路径。版本记录包含 release、commit/build type 与 runtime path，因为插件可能依赖具体 API，而不只是“0.x”。
卸载前先分清二进制、配置、data、state 与 cache。删除软件包不应自动删除 dotfiles、shada、插件源码和 LSP 下载；清理这些目录必须确认没有其他 profile 使用并保留回退。企业分发还要核对第三方组件许可证，而不是只记录 Neovim 主项目许可证。
XDG 路径把配置、数据、状态和缓存分开
Neovim 启动文档说明用户配置位于 stdpath('config')，通常是 Unix 的 $XDG_CONFIG_HOME/nvim 和 Windows 的本地 AppData nvim。不要把所有目录都猜成 ~/.config/nvim，直接查询：
:echo stdpath('config')
:echo stdpath('data')
:echo stdpath('state')
:echo stdpath('cache')
:echo $MYVIMRC
:set runtimepath?
:set packpath?init.lua 或 init.vim 二选一作为主配置。配置仓库保存声明与锁文件；data 往往保存插件、parser 或工具下载；state 保存 shada 等运行状态；cache 保存可重建派生物。故障时按 owner 清一层，比删除整个 ~/.local/share/nvim 更容易保留证据和回滚。
为测试另一个 profile，可临时改变 XDG 路径或使用 Neovim 的应用名隔离机制，但要在文档中显式记录。不要把 shell 的全局 HOME 改指向临时目录，这会连带影响 Git、SSH 和其他工具。
nvim --clean 是无用户配置的可用基准，nvim -u NONE --noplugin 更彻底地排除主配置与插件。两者都能打开文件而日常配置失败，故障就在配置或派生状态；clean 也失败，则调查二进制、runtime、终端或文件系统。
Lua 模块要可定位、可失败、可回滚
官方 Lua guide说明 init.lua 可以通过 require() 加载 runtimepath 中 lua/ 下的模块，并且模块会进入 package.loaded cache。把全部配置放在一个上千行文件里，会让启动顺序和失败来源难以定位；更稳的结构按 options、keymaps、autocmds、LSP、plugin 与 local override 拆分。
入口只加载确定存在的模块，机器差异用明确的本地文件和 pcall() 控制。pcall 不是吞掉所有错误的理由：必需模块失败应打印模块名与修复提示，并保留 clean 入口；可选模块才允许降级。开发时 reload 一个 Lua 模块要注意 require cache，最可靠的验收仍是启动一个新进程。
Lua 配置能执行系统命令、创建 RPC channel、访问环境和网络。init.lua、插件 spec 与 lock 都是代码，必须评审。不要把 token、私有 registry 口令、用户绝对路径或内网主机写进 table；由外部 secret 工具和环境按最小权限注入。
启动故障用下面的证据组合：
nvim --startuptime nvim-startup.log sample.txt再查看 :messages、:scriptnames、:verbose set <option>? 与 :verbose map <key>。日志进入工单前清理本机路径和仓库名称，不因排障泄露项目身份。
项目根是 LSP、formatter 和测试共同输入
Neovim 的 cwd、当前 buffer 路径、LSP workspace folder 与插件推导 root 可以各不相同。根目录错了会让 language server 扫描上级 monorepo、读取另一份配置或索引整个用户目录；formatter 和 test runner 又可能从当前 shell cwd 找到不同依赖。
团队先定义 marker 优先级，例如显式 workspace 文件、语言 manifest、.git，并给诊断命令输出最终 root。不要让每个插件维护一套向上搜索规则。LSP 的 root_dir、启动 cmd_cwd 和传给项目命令的 cwd 需要有意区分：language server workspace 可能是 module 根，构建命令可能必须在 monorepo 根运行。
接入项目时先从外部终端执行仓库正式 bootstrap/build/test，保存二进制路径、版本和退出码。再从任意子目录启动 Neovim，打开同一文件，检查 LSP workspace、formatter executable 与测试 cwd。只有两种入口得到同一项目事实，配置才算可迁移。
内置 LSP 需要外部 server 与明确生命周期
Neovim LSP 文档把 vim.lsp 定义为客户端框架，并明确要求另行安装 language server。当前配置 API 会演进，文章不复制一整套容易过期的第三方 preset；团队以支持的 Neovim release 和 :help lsp 为准，保存最小 server 配置、root 规则、启动命令和能力覆写。
排查时先运行：
:checkhealth vim.lsp
:LspInfo
:lua =vim.lsp.get_clients({bufnr = 0})然后在终端确认 server executable、--version 和项目依赖。LSP cmd 中的 ~ 等 shell 语法不会自动按交互 shell 展开；使用可解析命令名或绝对路径来源，并避免把个人绝对路径提交到配置。私有依赖的 proxy、CA 与凭证属于 language server/构建工具的外部环境，不写进 LSP settings。
正向实验选择一个已知符号，验证 definition、references、diagnostic 与 rename；再制造一个确定的语法或类型错误，确认 diagnostic 来自预期 client。反例是临时移除项目 marker 或从上级目录启动，预期 :LspInfo 暴露错误 workspace，跳转或索引范围随之异常。恢复 marker 规则后重启 client，同一 buffer 应回到正确 root。
退出 Neovim 后检查 language server 是否按 shutdown/exit 协议停止。官方客户端允许配置停止等待与强制退出行为；长期残留的 server 会继续占用内存、文件句柄和网络。团队验收不能止于“补全出现”，还要验证 client detach、编辑器退出和孤儿进程清理。
Provider 是另一组外部运行时
Python、Node、Ruby 等 provider 用于 remote plugin host，它们与 LSP server 不是一回事。插件提示缺少 pynvim 时，不应随手 pip install 到系统 Python；先从 :checkhealth provider 找到实际 host，再决定由项目隔离环境、用户工具环境或组织包提供。
provider 路径配置是机器层信息。团队声明需要的语言 major、包与安装方式，不提交某台机器的 interpreter 绝对路径。升级 Python/Node 后运行 health check 和代表插件功能；provider 能启动不代表插件协议兼容，插件版本与 provider 包仍需一起测试。
一个典型失败现场是终端里的 Python 能 import pynvim，Neovim health 仍报告缺失。原因通常是 Neovim 解析到另一个解释器，或 shell manager 只在交互启动脚本中生效。证据应比较 provider host、sys.executable、包路径与 Neovim 环境，而不是继续向多个 Python 重复安装。
插件管理器必须留下可复现制品
Neovim 原生 package 与 runtimepath 定义加载位置，不固定版本。插件管理器可以延迟加载、解析依赖和生成 lock，但真正的团队合同是：spec、精确 commit/lock、来源、构建步骤和回滚一起进入评审。只提交 init.lua 而忽略 lock，会让每台机器获得不同代码。
插件首次安装或更新可能执行 build hook、下载 parser、二进制、language server 或 formatter。它们以开发者权限读取源码、环境和网络，属于供应链。来源、维护者、许可证、发布签名或 commit、安装脚本、遥测与数据发送都要审查；不让插件管理器在每次启动时自动更新。
升级从独立 profile 和代表项目开始，一次限制插件数量。运行启动时间、health、LSP、formatter、quickfix、测试与退出验证，保留上一 lock。失败后先回退 lock 与 data 中对应插件，再判断是否需要回退 Neovim；不要同时清空 cache、重装工具和切换 release，把根因全部抹掉。
Tree-sitter parser、插件源码、Mason 或其他工具下载、shada 和 undo 各有不同 owner。文章不指定某个第三方管理器为唯一入口；采用它们时必须记录安装目录、网络源、版本锁、离线策略和清理边界。工具下载器也不能替仓库声明构建依赖。
项目本地配置与自动命令都是执行面
Neovim 支持 modeline，并能在启用相应选项时读取项目本地配置。陌生仓库中的配置、filetype 脚本、session 和插件工作区 hook 都可能执行代码。默认不自动信任当前目录脚本；确需项目配置时，以 allowlist/哈希或明确确认绑定仓库身份，变更后重新审查。
modelineexpr 保持关闭，modeline 仅承载有限格式 option。autocmd 用 API 创建明确 group，限制 pattern 与 buffer，避免每次 reload 重复注册。发生“打开文件就运行命令、切 cwd 或访问网络”时，查看 :verbose autocmd 和配置来源，不用 silent! 把异常消音。
插件、LSP、provider 和终端可以继承 SSH agent、云凭证与代理。远端 SSH 环境尤其要限制 agent forwarding 与 secret 暴露；日志、shada、命令历史和 terminal buffer 在共享机器上有保留风险。团队配置从不包含真实凭证，调试示例使用无秘密占位符。
故障恢复先回答是哪一层坏了
Neovim 启动失败：比较 --clean 与正常模式，查看 startup log 和首个 Lua traceback。LSP 不附着：比较 root、server executable、client log 与 checkhealth。补全正常但测试失败：回到项目 cwd、runtime 和依赖，不把 LSP 当构建证据。provider 失败：核对 host interpreter 与包。插件命令消失：检查 spec、lock、runtimepath、加载条件和 build hook。
磁盘增长时分别统计 data、state、cache、undo 和插件工具目录；CPU 持续升高时用 client 列表、job、profile 和进程树定位。删除前保存日志与未提交配置，先移动单一派生目录到临时回退位置，再启动验证。禁止一个“重装 Neovim”脚本递归删除整个 XDG 用户目录。
恢复顺序通常是：修正一项配置；回退插件 lock；重建单个 plugin/parser/tool；新建隔离 profile；切回旧 Neovim release。每一步都重复项目根、LSP 正反实验、构建测试和进程退出，直到变量可归因。
团队基线必须同时支持完整模式与 clean 模式
Neovim 适合希望以 Lua 组合编辑能力、需要异步 LSP/RPC 和终端一致性的团队。维护成本不在编辑器包本身，而在外部 server/provider、插件供应链、API 兼容和多平台工具解析。若团队没有 owner 维护这些对象，一个预集成 IDE 可能更经济。
基线应登记 Neovim release 与安装渠道、XDG 目录边界、配置仓库和 lock、root 规则、支持的 server/provider、插件准入、升级窗口、资源与退出条件。偏好可以个人化，项目命令、安全默认和证据采集应统一。
最后的验收不是一张漂亮启动页：干净账号能从配置与锁重建；外部终端和 Neovim 调用同一项目工具链；LSP/provider 可诊断；失败能退到 --clean；退出后没有 server 和调试进程；移除 Neovim 后仓库仍能构建。满足这些条件，Neovim 才是可替换的工程入口，而不是由插件缓存维持的个人工作站。