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

# はじめに

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 公式サイト](https://neovide.dev/)
> * [AstroNvim GitHub リポジトリ](https://github.com/AstroNvim/AstroNvim)

# 気分がアガる開発環境

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

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

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

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

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

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

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

4. Neovide で起動してインストールプロセスを実行
5. \~/.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（プラグイン）で再構成

---

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

* **問題**: スペースキーを押すと勝手に何かが起こるように感じた
* **問題の詳細**: ノーマルモードと挿入モードの切り替えによる誤解
* **原因**: 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
* **解決策**:

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

---

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

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

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

---

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

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

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

---

## API呼び出し：opts 内で vim.api.nvim\_create\_user\_command を実行しエラー

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

```lua
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
```

---

## トグル挙動：<leader>e がトグル動作で煩わしい

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

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

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

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

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

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

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

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

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

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

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

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

```lua
["<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：バッファ番号指定で開く（手動）

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

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

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

---

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

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

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

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

```lua
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 クライアントで有効

```lua
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 以降の推奨スタイルでは、以下に記述するのがベストです：

```lua
-- ~/.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 でインストール可能：

```sh
brew install im-select
```

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

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

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

```lua
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 クライアントで、カーソルアニメーションやフォント描画、ウィンドウ透過などの視覚効果が特徴です。

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

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

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

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

## フォント設定（Nerd Font）

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

## 透明化（好みに応じて）

```lua
vim.g.neovide_transparency = 0.9
```

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

# まとめ

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

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