---
title: Neovim のバージョン、更新、故障切り分け
url: https://doc.liz6.com/ja/tools/nvim/07-maintenance
locale: ja
area: tools
tags:
- Neovim
- 開発ツール
date: 2026-09-15
modified: 2026-09-15
description: 設定、プラグイン、外部ツール、キャッシュを区別し、lockfile と最小環境で更新後の問題を調べて復旧する。
---

# Neovim のバージョン、更新、故障切り分け

更新は Neovim、LazyVim、プラグイン、parser、言語サーバー、SDK に及ぶ。一度に変えると原因が分からなくなるため、バージョンを記録して層ごとに検証する。

## lockfile の範囲

lazy-lock.json はプラグインのコミットを固定する。Neovim 本体、全 Mason ツール、SDK、プロジェクト依存をまとめて固定するものではない。

| 対象 | 保存方法 |
| --- | --- |
| Lua と extras | 設定リポジトリ |
| プラグイン版 | lazy-lock.json |
| 本体と外部ツール | 環境・パッケージ記録 |
| プロジェクト依存 | 各 lock/toolchain ファイル |
| キャッシュとログ | ツールごとの管理と再生成 |

[lazy.nvim lockfile](https://lazy.folke.io/usage/lockfile)

## 更新前の基準

編集中のファイルを保存し、設定の未コミット変更を説明できる状態にする。`nvim --version` と lockfile を保存して、慣れた小さなプロジェクトを選ぶ。

ファイル、検索、定義移動、整形、テスト、入力法、コピーを確認する。Zellij を常用する場合は境界移動も含める。既知の正常状態から更新し、変更説明と `:Lazy` の対象を読む。

更新後に同じ操作を繰り返す。起動エラーがないだけでは言語機能やキーの正しさを確認できない。

## 症状ごとの入口

| 症状 | 確認 |
| --- | --- |
| Lua エラー | messages、スタック、API 変更 |
| キー変化 | verbose nmap、局所マッピング、順序 |
| 一言語だけ失敗 | LSP health、クライアント、実行パス |
| 保存で過剰変更 | ConformInfo、autocmd、整形規則 |
| ダウンロード失敗 | Lazy ログ、DNS、Git、通信 |
| 大ファイルが遅い | parser、診断、Git 装飾、描画の比較 |

ログにはパスやコードを含む場合がある。診断に必要な情報を残し、無関係なデータは公開しない。

## 最小環境で比較する

```bash
nvim --clean notes.md
```

ここでも再現するなら端末、入力法、本体を調べる。消えるなら別 NVIM_APPNAME で必要プラグインを順に追加する。日常の設定やデータを削除して切り分けない。

対象設定ディレクトリで Lua を実行せず構文だけ確認する例：

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

成功はモジュールの存在や API 互換性を保証しない。

空起動の時間を記録する例：

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

キャッシュと通信で時間は変わるため、一回の速さだけで判断しない。重い段階を見つけてから読み込みイベントを調整する。

## 正常状態へ戻す

故障した設定とログを保存し、既知の Lua と lockfile を Git から戻す。`:Lazy restore` で該当コミットを復元し、再起動後に基準操作を行う。

本体や外部サーバーが原因なら、プラグイン復元だけでは戻らない。該当するパッケージ・ツールチェーンの仕組みを使う。data/state/cache の無差別削除は履歴や証拠を失わせる場合がある。

## ローカル適合を保守する

公開 opts を優先し、内部関数の上書きには対象コミット、再現条件、上流問題、除去条件を残す。

旧 smart-splits の境界検出回避は、導入済み実装が固定値を返すようになってもローカルに残っていた。更新時は必要性を再確認する。

保守の結果として、検証済み設定と、変えた版・戻し方を説明する短い記録を残す。