Neovide + AstroNvim を Mac に導入してハマったことまとめ（2025年版）

Posted at 2025-05-19

はじめに

VSCode に慣れた開発者が「ちょっと気分を変えたい」と Neovim に手を出すとき、GUI 版の Neovide + 高機能な AstroNvim は魅力的な選択肢になります。

本記事では、筆者が Mac 上で Neovide + AstroNvim を導入した際に直面したトラブルや、その解決策を中心に共有します。

想定読者

Mac で開発作業をしている人
Vim の基本操作はわかるが、日常的には使っていない人
VSCode ユーザーで Neovim に興味を持ち始めた人

環境構成

項目	バージョン
macOS	15.4.1
Neovim	v0.11.0
Neovide	v0.15.0
AstroNvim	main ブランチ（Commit: 870c63b）

参考リンク：

Neovide 公式サイト

AstroNvim GitHub リポジトリ

気分がアガる開発環境

筆者が目指したのは「気分がアガる開発環境」。

フォントが綺麗でアニメーションも滑らか
GUI でも軽量でキーボード中心の操作が可能
高速な補完や LSP サポート

Neovide はその見た目と体験の良さから VSCode の GUI に近い感覚を与えてくれます。AstroNvim は多機能プリセットを備え、すぐに開発環境を整えたい人に最適です。

Aqua Voice による音声入力や Groq の LLM3 API との連携といった拡張性も含め、まさに「Vibe Coding」な環境が整いました。

セットアップ手順（ざっくり編）

Neovim, Neovide のインストール（Homebrew 推奨）
Nerd Font をインストールし、Neovide 側でフォント指定
AstroNvim テンプレートから構成を生成：

git clone https://github.com/AstroNvim/template ~/.config/nvim

Neovide で起動してインストールプロセスを実行
~/.config/nvim 配下の設定ファイル群をカスタマイズ

はまりどころと解決ポイント一覧（詳細編）

以下は、Neovide + AstroNvim を導入する過程で遭遇した問題とその解決策をカテゴリ別に整理した一覧です。

カテゴリ	問題	解決策
インストール	AstroNvim を公式リポジトリから直接 clone してエラー	`template` リポジトリを使用し、正しく構成する必要あり
設定構成	plugins.lua など従来構成との違いに戸惑う	`lua/user/` 以下に設定ファイルを配置するのが AstroNvim 流
キーマップ	`<leader>`（スペースキー）の挙動が混乱	ノーマルモードでのみ有効。デフォルトで `<Space>` に割り当てられている
ファイラー	`nvim-tree` が表示されない	`neo-tree` との競合が原因。必要に応じて無効化または移行する
Git連携	LazyGit 終了後 Neovim に戻れない	`q` で閉じる、もしくは `:tabnew	LazyGit` を使う
ファイル表示	`.env` や `.gitignore` が neo-tree に表示されない	`filtered_items` 設定で `hide_dotfiles` や `hide_gitignored` を false に設定
キーマップ	`.` キーで隠しファイル切り替えができない	`opts.window.mappings` に `["."] = "toggle_hidden"` を追加
プラグイン読込	user/plugins/*.lua が読み込まれない	`lazy.setup({ import = "user.plugins" })` を設定ファイルに明示的に書く
API呼び出し	`opts` 内で `vim.api.nvim_create_user_command` を実行しエラー	`init = function() ... end` の中で呼び出すのが正しい
トグル挙動	`<leader>e` がトグル動作で煩わしい	`Neotree focus` を割り当てることで望ましい動作に変更可

インストール：AstroNvim を公式リポジトリから直接 clone してエラー

問題: AstroNvim をそのまま ~/.config/nvim に clone したら起動エラーになった
問題の詳細: This repository is not meant to be used as a direct Neovim configuration と表示された
原因: 本体リポジトリは直接使う前提になっていない
解決策: AstroNvim/template を使って初期構成を作る

設定構成：plugins.lua など従来構成との違いに戸惑う

問題: init.lua, core/, plugins/ という従来構成が活かせない
問題の詳細: どこに何を書けばいいのかわからなかった
原因: AstroNvim では lua/user/ 以下に設定を集約する設計
解決策: init.lua（エントリ）、core.lua（基本設定）、plugins.lua（プラグイン）で再構成

キーマップ：（スペースキー）の挙動が混乱

問題: スペースキーを押すと勝手に何かが起こるように感じた
問題の詳細: ノーマルモードと挿入モードの切り替えによる誤解
原因: AstroNvim の <leader> が <Space> に設定されている
解決策: ノーマルモードでのみ反応し、挿入モードでは普通のスペースとして動作

ファイラー：nvim-tree が表示されない

問題: 設定しても nvim-tree が起動しない
問題の詳細: 起動しても何も表示されず壊れているように見えた
原因: デフォルトで neo-tree が有効で nvim-tree は除外されている
解決策: neo-tree を無効にするか、代わりに neo-tree を活用する

Git連携：LazyGit 終了後 Neovim に戻れない

問題: LazyGit の画面から抜け出せなかった
問題の詳細: ESC や Ctrl+C では戻れず戸惑った
原因: LazyGit は q で終了する TUI アプリ
解決策: q で終了、もしくは :tabnew | LazyGit で新タブとして開く

ファイル表示：.env や .gitignore が neo-tree に表示されない

問題: 隠しファイルがファイラーに表示されない
問題の詳細: LSP や補完が効いてもファイル自体が見えない
原因: neo-tree の初期設定で hide_dotfiles などが true
解決策:

opts = {
  filesystem = {
    filtered_items = {
      visible = true,
      hide_dotfiles = false,
      hide_gitignored = false,
    },
  },
}

キーマップ：`.` キーで隠しファイル切り替えができない

問題: . を押してもファイル表示が切り替わらない
問題の詳細: toggle_hidden がマップされていない
原因: キーマッピングの追加が必要
解決策:

opts.window = {
  mappings = {
    ["."] = "toggle_hidden",
  },
}

プラグイン読込：user/plugins/*.lua が読み込まれない

問題: カスタムプラグイン設定が反映されなかった
問題の詳細: ファイルが存在しているのに設定が効かない
原因: lazy.setup に import = "user.plugins" が指定されていなかった
解決策:

require("lazy").setup({
  import = "user.plugins"
})

API呼び出し：opts 内で vim.api.nvim_create_user_command を実行しエラー

問題: attempt to call a nil value エラーが出た
問題の詳細: コマンド登録処理を opts の中で書いていた
原因: 副作用コードは init の中で書くべき
解決策:

init = function()
  vim.api.nvim_create_user_command("Vfx", function(opts)
    vim.g.neovide_cursor_vfx_mode = opts.args
  end, {
    nargs = 1,
    complete = function()
      return { "railgun", "torpedo", "pixiedust", "sonicboom", "wireframe", "" }
    end,
  })
end

トグル挙動：e がトグル動作で煩わしい

問題: <leader>e で Neo-tree が一瞬閉じて開き直す動作が気になる
問題の詳細: toggle 動作のため、開いているときも再実行で閉じてしまう
原因: デフォルトのキーマップが :Neotree toggle
解決策:

["<leader>E"] = { "<cmd>Neotree focus<cr>", desc = "Focus Neo-tree" },

Neo-tree 編：UIと設定まわりの罠と対策

Neo-tree は AstroNvim に標準で組み込まれているファイラーで、見た目や操作性に優れていますが、初期設定では隠しファイルが表示されなかったり、キーマッピングが直感と異なっていたりするなど、初心者がつまずきやすい要素がいくつかあります。

隠しファイルが表示されない

問題: .env や .gitignore などが見えない
原因: filtered_items の設定で hide_dotfiles = true になっている
解決策:

opts = {
  filesystem = {
    filtered_items = {
      visible = true,
      hide_dotfiles = false,
      hide_gitignored = false,
    },
  },
}

`.` キーでの切り替えができない

問題: . を押しても隠しファイルの表示が切り替わらない
原因: toggle_hidden に対応したマッピングが設定されていない
解決策:

opts.window = {
  mappings = {
    ["."] = "toggle_hidden",
  },
}

`<leader>e` で Neo-tree が閉じて再表示されてしまう

問題: :Neotree toggle によるトグル動作が煩わしい
解決策:

["<leader>E"] = { "<cmd>Neotree focus<cr>", desc = "Focus Neo-tree" },

これらの設定を加えることで、Neo-tree をより直感的に、ストレスなく使えるようになりました。

補足Tips：Neo-tree 操作とカスタムマッピング

Neo-tree でより快適な操作を実現するために、以下のようなテクニックやカスタマイズが有効です。

既に開いているバッファを画面分割で表示する

方法1：s / S キーを使って再度開く

s：水平分割で開く（:split 相当）
S：垂直分割で開く（:vsplit 相当）
⚠ 同じファイルがすでに開いていても、新しいウィンドウで再表示されます

方法2：`:Neotree buffers` を使う

:Neotree buffers と入力すると、現在開いているバッファ一覧が表示されます
そこから s, S, t などで分割表示が可能

方法3：バッファ番号指定で開く（手動）

:vsplit | b N  " N はバッファ番号

方法4：Lua によるカスタムマッピング

vim.cmd("vsplit")
vim.cmd("b <buffer-name-or-number>")

カーソル移動：3行ずつスクロールしたい

方法1：3j / 3k を連打（標準機能）

3j   " 3行下へ移動
3k   " 3行上へ移動

方法2：J / K にマッピング

vim.keymap.set("n", "J", "3j", { noremap = true, silent = true, desc = "Move down 3 lines" })
vim.keymap.set("n", "K", "3k", { noremap = true, silent = true, desc = "Move up 3 lines" })

方法3：⌘キー（Mac）との組み合わせ

※ Neovide など GUI クライアントで有効

vim.keymap.set("n", "<D-j>", "3j", { noremap = true, desc = "Move down 3 lines" })
vim.keymap.set("n", "<D-k>", "3k", { noremap = true, desc = "Move up 3 lines" })

マッピングの定義場所

AstroNvim v4 以降の推奨スタイルでは、以下に記述するのがベストです：

-- ~/.config/nvim/lua/plugins/mappings.lua
---@type LazySpec
return {
  "AstroNvim/astrocore",
  ---@type AstroCoreOpts
  opts = {
    mappings = {
      n = {
        ["<D-j>"] = { "3j", desc = "Move down 3 lines" },
        ["<D-k>"] = { "3k", desc = "Move up 3 lines" },
        ["<D-s>"] = { ":w<CR>", desc = "Save file" },
      },
      i = {
        ["<D-s>"] = { "<Esc>:w<CR>a", desc = "Save file (insert mode)" },
      },
    },
  },
}

上記の設定を使えば、GUI環境で ⌘ + j/k などを快適に使えるようになります。

補足Tips：IMEの自動切り替え（macOS + im-select）

Neovim を使っていると、他のアプリ（ブラウザなど）に切り替えたあと Neovim に戻ってきた際に、IME（日本語入力）の状態が意図せずオンになっていることがあります。これを防ぐために、Neovim のオートコマンドと外部ツール im-select を活用して、IME の自動切り替えを行う設定を紹介します。

使用ツール：im-select

macOS における入力ソース制御用CLIツール。Homebrew でインストール可能：

brew install im-select

実行すると現在の入力ソース ID を表示します。

im-select
# 例: com.apple.keylayout.ABC

プラグイン設定：im-select.nvim（AstroNvim環境）

return {
  "keaising/im-select.nvim",
  event = { "InsertEnter", "CmdlineEnter" },
  config = function()
    require("im_select").setup({
      default_command     = "im-select",
      default_im_select   = "com.apple.keylayout.ABC", -- 英字IME
      set_default_events  = { "InsertLeave", "CmdlineEnter", "FocusLost" },
      set_previous_events = { "InsertEnter", "FocusGained" },
    })
  end,
}

動作イメージ

状況	動作
Insert を抜ける、コマンド開始	IME → 英字に切替
外部アプリへフォーカス移動	IME → 英字に切替
Neovim にフォーカスが戻る	IME → 直前の状態に復元（日本語など）

この設定により、「Neovim で Insert を抜けた時」や「Neovim に戻ってきた時」に IME が自動で切り替わるようになります。

有効化と確認

:Lazy sync 実行後、Neovim を再起動
im-select をターミナルで実行し、IME 状態の確認が可能

補足Tips：Neovide チューニング

Neovide は Neovim の GUI クライアントで、カーソルアニメーションやフォント描画、ウィンドウ透過などの視覚効果が特徴です。

カーソルアニメーションのカスタマイズ

vim.g.neovide_cursor_vfx_mode = "railgun"
vim.g.neovide_cursor_vfx_particle_density = 20.0
vim.g.neovide_cursor_vfx_opacity = 200.0

リフレッシュレートやレスポンス調整

vim.g.neovide_refresh_rate = 60
vim.g.neovide_no_idle = true
vim.g.neovide_cursor_animation_length = 0.05

フォント設定（Nerd Font）

vim.o.guifont = "JetBrainsMono Nerd Font:h14"

透明化（好みに応じて）

vim.g.neovide_transparency = 0.9

Neovide の設定はすべて vim.g.neovide_～ で始まるグローバル変数で制御でき、気分や作業スタイルに合わせた「Vibe Coding」環境を演出できます。

まとめ

VSCode より起動が早く、ヌルヌルサクサクなカーソル移動にハマる
Neovim の設定に触れることで Vim の理解も深まる
定期的な更新（AstroNvim v4以降）には注意

Neovim 未経験の人にもぜひ試してみてほしい環境です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up