Neovim Runbook

症状 Neo-treeでファイル/フォルダのアイコンが表示されず、豆腐（□）や文字化けになる 結論：まずこれを確認 Nerd Fonts対応フォントがインストールされているか ターミナルでそのフォントを使用しているか nvim-web-devicons プラグインがインストールされているか 操作フロー flowchart TD A[アイコンが表示されない] --> B{ターミナルで<br>Nerd Fontsを使用?} B -->|No| C[Nerd Fontsをインストール] B -->|Yes| D{nvim-web-devicons<br>インストール済?} C --> C1[ターミナル設定を変更] C1 --> D D -->|No| E[プラグインを追加] D -->|Yes| F{:checkhealth<br>nvim-web-devicons} E --> F F -->|エラーあり| G[エラー内容を確認] F -->|OK| H[neo-tree設定を確認] G --> I[該当セクションへ] H --> J[アイコン設定を確認] よくある原因 Nerd Fontsがインストールされていない - アイコン表示に必須のフォント ターミナルで通常フォントを使用している - インストールしても設定が必要 nvim-web-deviconsがインストールされていない - neo-treeの依存プラグイン フォントのバージョンが古い - Nerd Fonts v3で変更された箇所がある SSHやtmux経由で接続している - ローカル側のフォント設定が影響 GUIのNeovim（Neovide等）でフォント未設定 - 別途guifont設定が必要 操作手順 ステップ1: Nerd Fontsのインストール状態を確認する ターミナルで以下のコマンドを実行し、Nerd Fonts対応フォントがあるか確認する。 ...

症状 Neovim起動時に Error detected while processing や E5113 などのLua構文エラーが表示される 結論：まずこれを確認 エラーメッセージの行番号を確認する luacheck または lua コマンドで構文チェックを実行する 該当行の括弧・カンマ・クォートの対応を確認する 操作フロー flowchart TD A[Neovim起動時にエラー] --> B{エラーメッセージに行番号あり?} B -->|Yes| C[該当行を確認] B -->|No| D[luacheckで全体チェック] C --> E{括弧/カンマ/クォート} E -->|不一致| F[対応を修正] E -->|問題なし| G[前後の行も確認] D --> H[エラー箇所を特定] F --> I[Neovim再起動で確認] G --> I H --> C よくある原因 括弧の閉じ忘れ - { ( [ に対応する閉じ括弧がない カンマの過不足 - テーブル定義の最後に余分なカンマ、または途中でカンマ漏れ クォートの不一致 - ' と " の混在、または閉じ忘れ 予約語の誤使用 - end local function などの位置が不正 インデントの問題 - コピペ時にタブとスペースが混在 マルチバイト文字 - 全角スペースや全角括弧の混入 プラグイン設定の書式ミス - 各プラグインが期待する形式と異なる 操作手順 ステップ1: エラーメッセージを確認する Neovim起動時に表示されるエラーを確認する。 ...

症状 lazy.nvimでインストールしたプラグインが読み込まれない、または設定が反映されない 結論：まずこれを確認 :Lazy でプラグインの状態を確認（Installed / Not Installed / Error） :checkhealth lazy でlazy.nvim自体のエラーを確認 プラグイン定義の config や opts の記述ミスを確認 操作フロー flowchart TD A[プラグインが動作しない] --> B{:Lazyでステータス確認} B -->|Not Installed| C[インストール実行] B -->|Installed| D{:checkhealth lazy} B -->|Error表示| E[エラーメッセージを確認] C --> F[:Lazy sync を実行] D -->|エラーあり| G[設定ファイルを修正] D -->|エラーなし| H{遅延読み込み設定を確認} E --> G H -->|event/cmd/ft設定あり| I[トリガー条件を確認] H -->|設定なし| J[依存関係を確認] I --> K[該当操作を実行してみる] J --> L[dependencies設定を確認] よくある原因 プラグインがインストールされていない - :Lazy sync が実行されていない 設定ファイルのパスが間違っている - ~/.config/nvim/lua/plugins/ 配下に配置されていない 遅延読み込み設定でトリガーされていない - event, cmd, ft の条件を満たしていない Lua構文エラー - テーブル定義のカンマ忘れ、括弧の不一致 依存プラグインが読み込まれていない - dependencies の設定漏れ config 関数内でエラー発生 - プラグイン固有の設定ミス プラグイン名の記述ミス - GitHubリポジトリ名と一致していない 操作手順 ステップ1: lazy.nvimの状態を確認する Neovimを起動して以下を実行する。 ...

症状 mason.nvimでLSPサーバーをインストールしようとするとエラーが表示され、インストールが完了しない。 結論：まずこれを確認 :checkhealth mason を実行して依存関係を確認する git, curl, unzip がインストールされているか確認する ネットワーク接続とプロキシ設定を確認する 操作フロー flowchart TD A[インストール失敗] --> B{:checkhealth mason} B -->|ERROR表示| C[依存ツール不足] B -->|OK| D{ログを確認} C --> E[git/curl/unzipをインストール] D -->|network error| F[ネットワーク確認] D -->|permission denied| G[パーミッション確認] D -->|その他| H[個別エラーを調査] F --> I[プロキシ設定確認] G --> J[mason.nvimのデータディレクトリ確認] よくある原因 git がインストールされていない - 多くのLSPサーバーはgitでクローンされる curl または wget がない - ダウンロードに必要 unzip がない - zipファイルの展開に必要 npm/cargo/pip がない - 言語別のパッケージマネージャが必要なサーバーがある ネットワーク接続の問題 - ファイアウォールやプロキシで遮断されている データディレクトリの権限不足 - ~/.local/share/nvim/mason への書き込み権限がない ディスク容量不足 - ダウンロードや展開に必要な空き容量がない 操作手順 ステップ1: checkhealthで依存関係を確認する Neovimで以下を実行する： ...

症状 telescope.nvimで :Telescope find_files を実行してもファイルが表示されない、または特定のファイルが検索結果に出てこない。 結論：まずこれを確認 rg（ripgrep）または fd がインストールされているか確認 .gitignore や telescope の file_ignore_patterns で除外されていないか確認 :checkhealth telescope でエラーがないか確認 操作フロー flowchart TD A[ファイルが見つからない] --> B{:checkhealth telescope} B -->|エラーあり| C[依存ツールを確認] B -->|エラーなし| D{hidden files?} C --> E[rg/fd をインストール] D -->|隠しファイル| F[hidden=true を設定] D -->|通常ファイル| G{.gitignore確認} G -->|除外されている| H[no_ignore設定] G -->|除外されていない| I[file_ignore_patterns確認] E --> J[再度検索] F --> J H --> J I --> J よくある原因 ripgrep/fd 未インストール - telescope の find_files は外部ツールに依存する .gitignore による除外 - Git管理下のファイルはデフォルトで .gitignore を尊重する file_ignore_patterns 設定 - telescope 設定で特定パターンを除外している 隠しファイル（dotfiles） - デフォルトでは . で始まるファイルは非表示 cwd の指定ミス - 検索対象ディレクトリが意図と異なる プラグイン未読み込み - lazy loading で telescope が読み込まれていない キャッシュの問題 - 古いキャッシュが残っている 操作手順 ステップ1: 依存ツールの確認 # ripgrep の確認 which rg rg --version # fd の確認 which fd fd --version 🔍 チェックポイント: バージョン番号が表示されればインストール済み ...

症状 Neovimでnvim-treesitterを導入したが、シンタックスハイライトが表示されない、または一部の言語でハイライトが効かない。 結論：まずこれを確認 :TSInstall {言語名} でパーサーがインストールされているか確認 :TSModuleInfo でhighlightモジュールが有効か確認 :checkhealth nvim-treesitter でエラーがないか確認 操作フロー flowchart TD A[ハイライトが効かない] --> B{:TSInstallInfo で<br>パーサー確認} B -->|未インストール| C[:TSInstall 言語名] B -->|インストール済| D{:TSModuleInfo で<br>highlight確認} D -->|false| E[init.luaで<br>highlight有効化] D -->|true| F{:checkhealth<br>nvim-treesitter} F -->|エラーあり| G[エラー内容に従い対処] F -->|エラーなし| H[vim.cmd構文<br>競合を確認] C --> I[再起動して確認] E --> I G --> I H --> J[syntax offを確認] よくある原因 パーサー未インストール - 言語ごとのパーサーを個別にインストールする必要がある highlightモジュールが無効 - 設定でtreesitter highlightを有効化していない Neovimのバージョンが古い - nvim-treesitterは最新のNeovimを要求する 従来のsyntax highlightとの競合 - syntax on が残っていると競合する場合がある パーサーのビルドエラー - C コンパイラがないとパーサーがビルドできない プラグインマネージャの読み込み順 - treesitterの設定が読み込まれていない filetype未検出 - ファイルタイプが正しく認識されていない 操作手順 ステップ1: パーサーのインストール状態を確認する Neovimを起動し、以下を実行する。 ...

症状 Neovimでカラースキームを設定したが、色が反映されない・デフォルトのままになる。 結論：まずこれを確認 カラースキームがインストールされているか確認: :colorscheme <Tab>で補完候補に出るか vim.cmd("colorscheme テーマ名") の記述位置がプラグイン読み込み後になっているか termguicolors が有効になっているか: :set termguicolors? 操作フロー flowchart TD A[カラースキームが反映されない] --> B{:colorscheme Tab で候補に出る?} B -->|No| C[プラグインがインストールされていない] B -->|Yes| D{エラーメッセージが出る?} D -->|Yes| E[エラー内容を確認] D -->|No| F{termguicolorsは有効?} F -->|No| G[termguicolorsを設定] F -->|Yes| H{設定の読み込み順序は正しい?} H -->|No| I[colorscheme行の位置を修正] H -->|Yes| J[ターミナルの色設定を確認] C --> K[プラグインマネージャーで再インストール] E --> L[該当セクションへ] よくある原因 プラグインがインストールされていない - プラグインマネージャーの設定ミスや同期忘れ colorscheme の記述位置が早すぎる - プラグイン読み込み前に実行している termguicolors が無効 - True Color対応テーマは24bitカラーが必要 テーマ名のスペルミス - 大文字小文字やハイフン/アンダースコアの違い ターミナルがTrue Colorに非対応 - 古いターミナルや設定不足 背景色(background)の設定不一致 - light/darkの指定がテーマと合っていない init.luaの構文エラー - 途中でエラーが発生し後続が実行されない 操作手順 ステップ1: カラースキームの存在を確認する Neovimを起動し、以下を実行する。 ...

症状 Neovimで設定したキーマッピングが動作しない、または反映されない。 結論：まずこれを確認 :verbose map <キー> で該当キーのマッピング状態を確認する 設定ファイルの読み込みエラーを :messages で確認する 他のプラグインによる上書きを :checkhealth で確認する 操作フロー flowchart TD A[キーマッピングが効かない] --> B{:verbose map で確認} B -->|マッピングなし| C[設定ファイルを確認] B -->|別の場所で定義| D[競合を特定] B -->|意図通りの定義| E[モード設定を確認] C --> F{:messages でエラー確認} F -->|エラーあり| G[構文エラーを修正] F -->|エラーなし| H[設定の記述位置を確認] D --> I[プラグイン設定を調整] E --> J[対象モードを見直す] よくある原因 設定ファイルの構文エラー - Luaの文法ミスで後続の設定が読み込まれていない プラグインによる上書き - 後から読み込まれたプラグインが同じキーを使用している モード指定のミス - ノーマルモード用の設定をインサートモードで使おうとしている <leader> キーの未設定 - mapleader を設定する前にマッピングを定義している 設定ファイルのパスが違う - Neovimが読み込む設定ファイルが想定と異なる ターミナルのキー入力の問題 - 特殊キーがターミナルで正しく送信されていない noremap と map の違い - 再帰的マッピングによる意図しない動作 操作手順 ステップ1: マッピングの現在状態を確認する :verbose map <Space> :verbose nmap <leader>f :verbose imap <C-j> 🔍 チェックポイント: 「Last set from」に表示されるファイルパスを確認する。意図したファイルでなければ競合が発生している。 ...

症状 Neovimで "+y や "*p を使ってもシステムクリップボードにコピー・貼り付けができない。 結論：まずこれを確認 :checkhealth を実行し、clipboard の項目を確認する xclip または xsel（X11環境）、wl-copy（Wayland環境）がインストールされているか確認する init.lua に vim.opt.clipboard = "unnamedplus" が設定されているか確認する 操作フロー flowchart TD A[クリップボードが使えない] --> B{:checkhealth を実行} B -->|clipboard: ERROR| C[provider が見つからない] B -->|clipboard: OK| D[設定ファイルを確認] C --> E[xclip/xsel/wl-copy をインストール] E --> F[Neovim を再起動] D --> G{clipboard オプション設定あり?} G -->|なし| H[init.lua に設定を追加] G -->|あり| I[SSH/tmux 環境を確認] F --> J[再度 :checkhealth で確認] H --> J I --> K[環境変数 DISPLAY を確認] よくある原因 clipboard provider がインストールされていない - xclip/xsel/wl-copy などが必要 clipboard オプションが設定されていない - vim.opt.clipboard の設定漏れ SSH 接続で X11 forwarding が無効 - -X オプションなしで接続している Wayland 環境で X11 用ツールを使っている - wl-clipboard が必要 tmux 内で clipboard 共有が無効 - tmux.conf の設定が必要 Neovim のバージョンが古い - clipboard 機能に問題がある可能性 WSL2 で Windows 側との連携が未設定 - win32yank などが必要 操作手順 ステップ1: checkhealth でクリップボード状態を確認する Neovim を起動し、以下を実行する： ...

症状 Neovimでnvim-cmpをインストールしたが、補完候補が表示されない・ポップアップが出ない。 結論：まずこれを確認 :checkhealth nvim-cmp を実行してエラーがないか確認する 補完ソース（cmp-nvim-lsp, cmp-buffer等）がインストールされているか確認する sources の設定でソースが指定されているか確認する 操作フロー flowchart TD A[補完が表示されない] --> B{:checkhealth nvim-cmp} B -->|エラーあり| C[エラー内容を確認] B -->|エラーなし| D{補完ソースを確認} C --> E[プラグインを再インストール] D -->|ソース未設定| F[sources設定を追加] D -->|ソース設定済み| G{LSPが起動しているか} G -->|起動していない| H[:LspInfoで確認] G -->|起動している| I[キーマッピングを確認] H --> J[LSP設定を見直す] I --> K[mapping設定を見直す] よくある原因 補完ソースがインストールされていない - nvim-cmp本体だけでは補完候補が生成されない sourcesの設定がない - どのソースから補完するか指定が必要 LSPが起動していない - cmp-nvim-lspを使う場合、LSPが動いている必要がある setup()が呼ばれていない - require(“cmp”).setup() の記述漏れ プラグインの読み込み順序が不正 - 依存関係のあるプラグインが先に読み込まれていない キーマッピングの競合 - 他のプラグインがTab等のキーを上書きしている filetype未検出 - ファイルタイプが検出されずLSPが起動しない 操作手順 ステップ1: checkhealthを実行する :checkhealth nvim-cmp 🔍 チェックポイント: OK 以外の表示がないか確認する。ERROR や WARNING があれば該当箇所を修正する。 ...