症状

Neovimで設定したキーマッピングが動作しない、または反映されない。

結論：まずこれを確認

  1. :verbose map <キー> で該当キーのマッピング状態を確認する
  2. 設定ファイルの読み込みエラーを :messages で確認する
  3. 他のプラグインによる上書きを :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」に表示されるファイルパスを確認する。意図したファイルでなければ競合が発生している。

ステップ2: 設定ファイルのエラーを確認する

    :messages

エラーがある場合、Neovimを再起動して最初に表示されるエラーメッセージも確認する：

    nvim --startuptime /tmp/startup.log
cat /tmp/startup.log | grep -i error

🔍 チェックポイント: E5108 や E5113 などのLuaエラーが表示されていないか確認する。

ステップ3: 設定ファイルのパスを確認する

    :echo stdpath('config')

通常のパス：

  • Linux/macOS: ~/.config/nvim/
  • Windows: ~/AppData/Local/nvim/

設定ファイルの存在確認：

    ls -la ~/.config/nvim/init.lua
# または
ls -la ~/.config/nvim/init.vim

🔍 チェックポイント: init.lua と init.vim が両方存在する場合、init.lua が優先される。

ステップ4: キーマッピングの正しい記述を確認する

~/.config/nvim/init.lua での基本的な記述例：

    -- leaderキーは最初に設定する（マッピングより前）
vim.g.mapleader = " "
vim.g.maplocalleader = " "

-- 基本的なキーマッピング
vim.keymap.set("n", "<leader>w", ":w<CR>", { desc = "Save file" })
vim.keymap.set("n", "<leader>q", ":q<CR>", { desc = "Quit" })

-- 複数モードに設定
vim.keymap.set({ "n", "v" }, "<leader>y", '"+y', { desc = "Yank to clipboard" })

-- バッファローカルなマッピング
vim.keymap.set("n", "<leader>f", function()
  print("Function called")
end, { buffer = true, desc = "Buffer local mapping" })

🔍 チェックポイント: vim.g.mapleader の設定が vim.keymap.set より前にあるか確認する。

ステップ5: プラグインとの競合を確認する

    :checkhealth

特定のプラグインが使用しているキーを確認：

    :verbose map <leader>

競合を避けるため、プラグインの設定内でキーマッピングを上書きする：

    -- lazy.nvim の例
{
  "nvim-telescope/telescope.nvim",
  keys = {
    { "<leader>ff", "<cmd>Telescope find_files<CR>", desc = "Find files" },
  },
}

🔍 チェックポイント: :verbose map の出力で、意図しないプラグインファイルが表示されていないか確認する。

ステップ6: モードの確認と修正

各モードの略称：

モード 略称 説明
ノーマル n 通常のコマンド入力
インサート i 文字入力
ビジュアル v 選択
コマンドライン c : の後
ターミナル t ターミナルモード 
    -- ノーマルモードのみ
vim.keymap.set("n", "<C-h>", "<C-w>h")

-- インサートモードのみ
vim.keymap.set("i", "jk", "<Esc>")

-- 全モード（非推奨、明示的に指定する）
vim.keymap.set("", "<F5>", ":make<CR>")

🔍 チェックポイント: 意図したモードでキーを押しているか、現在のモードを左下で確認する。

NG行動（やってはいけないこと）

  • 設定ファイル全体を削除して作り直す - 問題の切り分けにならず、他の設定も失われる
  • エラーを確認せずにマッピングを追加し続ける - 構文エラーで後続の設定が読み込まれていない可能性がある
  • noremap = false を安易に使う - 再帰的マッピングによる無限ループの原因になる
  • 複数の設定ファイルに同じマッピングを書く - 読み込み順序で上書きされ、デバッグが困難になる

よくある質問（FAQ）

Q1: <leader> キーを押しても何も起きない場合は？

A: vim.g.mapleader の設定位置を確認する。マッピング定義より後に書かれていると、leaderキーがデフォルト（\）のまま登録される。設定ファイルの最初に vim.g.mapleader = " " を記述する。

Q2: 特定のファイルタイプでだけマッピングを有効にするには？

A: ftplugin ディレクトリを使用するか、autocmd で設定する：

    vim.api.nvim_create_autocmd("FileType", {
  pattern = "python",
  callback = function()
    vim.keymap.set("n", "<leader>r", ":!python %<CR>", { buffer = true })
  end,
})

Q3: Ctrl+矢印キーなどの組み合わせが効かない場合は？

A: ターミナルエミュレータがキーシーケンスを正しく送信しているか確認する。:set termguicolors を設定し、ターミナル側の設定も見直す。cat -v コマンドでキー入力を確認できる。

関連するトラブル

準備中

解決しない場合

  • Neovim公式ドキュメント: :help key-mapping
  • 確認すべきファイル:
    • ~/.config/nvim/init.lua
    • ~/.config/nvim/lua/ 配下のファイル
    • :scriptnames で読み込まれた全ファイル
  • 次に調べるキーワード: 「Neovim keymap debug」「nvim verbose map」「lua keymap not working」