症状

Neo-treeでファイル/フォルダのアイコンが表示されず、豆腐（□）や文字化けになる

結論：まずこれを確認

  1. Nerd Fonts対応フォントがインストールされているか
  2. ターミナルでそのフォントを使用しているか
  3. 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対応フォントがあるか確認する。

    # Linux
fc-list | grep -i "nerd"

# macOS
fc-list | grep -i "nerd"
# または
ls ~/Library/Fonts | grep -i "nerd"

🔍 チェックポイント: フォント名が1つ以上表示されれば、インストールはされている

インストールされていない場合：

    # macOS (Homebrew)
brew tap homebrew/cask-fonts
brew install --cask font-hack-nerd-font

# Ubuntu/Debian
sudo apt install fonts-hack-nerd

# 手動インストール（全OS共通）
# https://www.nerdfonts.com/font-downloads からダウンロード

ステップ2: ターミナルのフォント設定を確認する

各ターミナルの設定画面でフォントを確認する。

ターミナル 設定場所
iTerm2 Preferences → Profiles → Text → Font
Alacritty ~/.config/alacritty/alacritty.toml
WezTerm ~/.config/wezterm/wezterm.lua
Windows Terminal Settings → Profiles → Appearance → Font face
GNOME Terminal Preferences → Profiles → Custom font

Alacrittyの設定例：

    [font]
normal = { family = "Hack Nerd Font", style = "Regular" }
size = 12.0

WezTermの設定例：

    return {
  font = wezterm.font("Hack Nerd Font"),
  font_size = 12.0,
}

🔍 チェックポイント: フォント名に「Nerd」が含まれているか確認

ステップ3: nvim-web-deviconsのインストールを確認する

Neovimを起動し、以下を実行する。

    :lua print(vim.inspect(package.loaded["nvim-web-devicons"]))

🔍 チェックポイント: nil と表示された場合、プラグインが読み込まれていない

lazy.nvimでのインストール例（~/.config/nvim/lua/plugins/neo-tree.lua）：

    return {
  "nvim-neo-tree/neo-tree.nvim",
  branch = "v3.x",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-tree/nvim-web-devicons", -- ← これが必要
    "MunifTanjim/nui.nvim",
  },
}

ステップ4: checkhealthで診断する

    :checkhealth nvim-web-devicons

🔍 チェックポイント: すべてOKになっているか確認。WARNINGやERRORがあれば内容を確認

ステップ5: neo-treeのアイコン設定を確認する

neo-treeの設定でアイコンが無効になっていないか確認する。

    require("neo-tree").setup({
  default_component_configs = {
    icon = {
      folder_closed = "",
      folder_open = "",
      folder_empty = "",
      default = "*",  -- ← ここが "*" などになっていると表示されない
    },
  },
})

🔍 チェックポイント: icon 設定がデフォルトから変更されていないか

ステップ6: GUIのNeovimの場合はguifontを設定する

Neovide、VimR、nvim-qtなどを使用している場合：

    -- ~/.config/nvim/init.lua
if vim.g.neovide then
  vim.o.guifont = "Hack Nerd Font:h12"
end

🔍 チェックポイント: :set guifont? で設定されたフォントを確認

NG行動

  • 通常フォントとNerd Fontsを混同する - 「Hack」と「Hack Nerd Font」は別のフォント
  • フォントインストール後にターミナルを再起動しない - フォントキャッシュが更新されていない可能性
  • SSH接続時にリモート側だけフォント設定する - 表示はローカルのターミナル依存
  • Nerd Fonts v2用の設定をv3で使う - 一部アイコンのコードポイントが変更されている

よくある質問（FAQ）

Q1: 一部のアイコンだけ表示されない場合は？

A: Nerd Fontsのバージョン不一致の可能性がある。nvim-web-devicons とフォントのバージョンを確認し、両方を最新にする。

Q2: tmux経由だとアイコンが表示されない場合は？

A: tmuxの設定に以下を追加する。

    # ~/.tmux.conf
set -g default-terminal "tmux-256color"
set -as terminal-features ",*:RGB"

Q3: WSL2でアイコンが表示されない場合は？

A: Windows側のターミナル（Windows Terminal等）のフォント設定を確認する。WSL2内ではなくホストOS側のフォントが使用される。

関連するトラブル

準備中

解決しない場合