Solução de problemas

    Definição curta: A maior parte dos problemas de configuração do Neovim é diagnosticada por :checkhealth e por bissecção da própria configuração.

    O que você vai aprender

    • Explicar A primeira parada com suas palavras
    • Explicar A configuração não carrega com suas palavras
    • Explicar LSP com suas palavras
    • Localizar o assunto desta página no :help do seu próprio Neovim

    A primeira parada

    :checkhealth

    Roda os diagnósticos de todos os módulos e plugins que os fornecem. Leia da primeira falha para baixo — erros posteriores costumam ser consequência.

    :checkhealth lsp
:checkhealth nvim-treesitter
:messages          " histórico de mensagens que passaram rápido demais

    A configuração não carrega

    Nada do que eu escrevi tem efeito. Confirme qual arquivo está sendo lido:

    :echo stdpath('config')
:scriptnames        " lista tudo que foi carregado, na ordem

    O caminho esperado é ~/.config/nvim/init.lua. Se existir também um init.vim no mesmo diretório, o Neovim recusa carregar os dois e usa apenas um — remova o que não usa.

    Erro na inicialização passando rápido demais.

    nvim --headless -c 'quit' 2>&1 | head -40

    A configuração quebrou depois de uma mudança. Bissecção: comente metade do init.lua, reinicie, repita. Cinco iterações localizam o problema em uma configuração de mil linhas.

    LSP

    O servidor não anexa ao buffer.

    :LspInfo           " o que está anexado a este buffer
:LspLog            " o log do servidor
:checkhealth lsp

    Causas em ordem de frequência: o executável do servidor não está no PATH; o filetype do buffer não corresponde ao esperado (:set filetype?); a raiz do projeto não foi detectada — o root_dir procura marcadores como .git, package.json, Cargo.toml.

    Autocompletar não aparece. O LSP e o motor de completar são componentes distintos. :LspInfo mostrando o servidor anexado apenas garante a primeira metade; o resto é configuração do motor de completar.

    Diagnósticos aparecem mas não somem depois de corrigidos. Alguns servidores só republicam ao salvar. Confirme com :LspLog se a mensagem de publicação chega.

    Treesitter

    Sem realce de sintaxe.

    :TSInstallInfo               " o parser está instalado?
:TSInstall <linguagem>
:InspectTree                 " a árvore está sendo construída?

    Se o parser está instalado e ainda assim não há realce, verifique se highlight = { enable = true } está na configuração e se não há um syntax off global posterior.

    Erro de compilação ao instalar parser. Falta compilador C. Instale gcc ou clang — :checkhealth nvim-treesitter diz exatamente o que falta.

    Atalhos

    Meu mapeamento não funciona.

    :verbose map <leader>ff

    Mostra o mapeamento efetivo e o arquivo onde foi definido — resolve a maioria dos conflitos, que são plugins sobrescrevendo mapeamentos.

    Se aparecer vazio, o mapeamento não chegou a ser criado: verifique se a mapleader foi definida antes do plugin carregar (ver gerenciador de plugins).

    A tecla não chega ao Neovim. Alguns atalhos são interceptados pelo terminal ou pelo multiplexador antes. <C-;> e variantes com Shift em teclas não alfabéticas são casos clássicos. Teste com : seguido de <C-v> e a tecla: se nada aparecer, o terminal engoliu.

    Aparência

    Cores erradas ou desbotadas.

    vim.opt.termguicolors = true

    Confirme também que a variável TERM do ambiente indica suporte a cor verdadeira (xterm-256color ou superior) e que o tema é carregado com prioridade alta.

    Ícones aparecem como quadrados. Falta uma Nerd Font instalada e selecionada no terminal.

    Desempenho

    Ver desempenho e tempo de inicialização. O resumo:

    nvim --startuptime /tmp/s.log +q && tail -20 /tmp/s.log
nvim --clean       # o problema é da config?

    Quando pedir ajuda

    Um relato útil contém: versão (:version), saída relevante de :checkhealth, e — o mais importante — uma configuração mínima reproduzível:

    -- repro.lua ; rodar com: nvim -u repro.lua
vim.opt.rtp:prepend('/caminho/para/o/plugin')
require('plugin').setup({})

    Metade dos problemas se resolve durante a construção desse arquivo, quando fica claro que o culpado era outro plugin.

    Você aprendeu

    • A primeira parada
    • A configuração não carrega
    • LSP
    • Treesitter
    • Atalhos

    Perguntas para reflexão

    1. O que A primeira parada resolve, e o que se perde sem isso?
    2. O que A configuração não carrega resolve, e o que se perde sem isso?
    3. O que LSP resolve, e o que se perde sem isso?
    4. Qual parte desta página você conseguiria reproduzir sem consultar, direto no editor?

    Artigos relacionados

    Veja também

    Referências

    • :help health
    • :help :checkhealth
    • :help troubleshooting