VS Code e ZLS — Resolver Problemas com Editor e Language Server
O ZLS (Zig Language Server) é essencial para uma boa experiência de desenvolvimento em Zig. Quando ele não funciona corretamente, prejudica a produtividade. Este guia resolve os problemas mais comuns.
ZLS Não Inicia
Sintomas: Sem autocompletar, sem diagnósticos, sem go-to-definition.
Verificações:
# 1. Verificar se o ZLS está instalado
which zls
zls --version
# 2. Verificar se o Zig está no PATH
which zig
zig version
# 3. Verificar se as versões são compatíveis
zig version # Ex: 0.13.0
zls --version # Deve ser compatível com a versão do Zig
Solução: ZLS e Zig devem ter versões compatíveis. A regra geral é que a versão do ZLS deve corresponder a versão do Zig.
# Instalar a versão correta do ZLS
# macOS
brew install zls
# Ou baixar manualmente do GitHub
# https://github.com/zigtools/zls/releases
Configurar VS Code para Zig
- Instale a extensão “Zig Language” (de ziglang) no VS Code
- Configure o caminho do Zig e ZLS:
// settings.json do VS Code
{
"zig.path": "/caminho/para/zig",
"zig.zls.path": "/caminho/para/zls",
"zig.zls.enabled": true,
"zig.formattingProvider": "zls"
}
Para encontrar os caminhos:
which zig # /usr/local/bin/zig
which zls # /usr/local/bin/zls
Autocompletar Não Funciona
Causa 1: ZLS não está rodando.
- Verifique na barra de status do VS Code se o ZLS está ativo
- Abra Output > Zig Language Server para ver logs
Causa 2: Projeto sem build.zig.
# ZLS precisa do build.zig para entender a estrutura do projeto
# Crie um se não existir
zig init
Causa 3: Erros no build.zig impedem o ZLS de analisar o projeto.
# Verifique se o build compila
zig build 2>&1 | head -20
Causa 4: ZLS travou.
- VS Code: Ctrl+Shift+P > “Zig: Restart Language Server”
Diagnósticos Falsos (Erros que Não Existem)
Sintomas: O editor mostra erros vermelhos, mas zig build funciona normalmente.
Soluções:
# 1. Limpar cache do Zig
rm -rf zig-cache .zig-cache
# 2. Reiniciar o ZLS
# VS Code: Ctrl+Shift+P > "Zig: Restart Language Server"
# 3. Verificar se o ZLS usa a mesma versão do Zig que você
zig version
zls --version
Se o problema persistir, pode ser um bug do ZLS. Verifique nas issues do ZLS.
ZLS Consume Muita Memória ou CPU
Causa: Projetos grandes ou com muitos @cImport podem sobrecarregar o ZLS.
Soluções:
// settings.json — limitar recursos do ZLS
{
"zig.zls.semanticTokens": "partial",
"zig.zls.enableAutofix": false
}
Para projetos muito grandes, considere fechar arquivos que não está editando e reiniciar o ZLS periodicamente.
Formatação Automática Não Funciona
// settings.json — configurar formatação
{
"editor.formatOnSave": true,
"zig.formattingProvider": "zls",
"[zig]": {
"editor.defaultFormatter": "ziglang.vscode-zig",
"editor.formatOnSave": true
}
}
Teste a formatação manualmente:
# Deve funcionar na linha de comando
zig fmt src/main.zig
Configurar Neovim com ZLS
-- Usando nvim-lspconfig
require('lspconfig').zls.setup({
cmd = { '/caminho/para/zls' },
settings = {
zls = {
enable_snippets = true,
enable_ast_check_diagnostics = true,
enable_autofix = false,
enable_import_detection = true,
},
},
})
Configurar Outros Editores
Emacs
;; Com eglot (built-in no Emacs 29+)
(add-to-list 'eglot-server-programs '(zig-mode "zls"))
(add-hook 'zig-mode-hook 'eglot-ensure)
Helix
# ~/.config/helix/languages.toml
[[language]]
name = "zig"
language-servers = ["zls"]
[language-server.zls]
command = "zls"
Sublime Text
// LSP-zig.sublime-settings
{
"command": ["zls"],
"selector": "source.zig"
}
Diagnóstico Geral
# Ver logs detalhados do ZLS
# VS Code: Output > Zig Language Server
# Testar ZLS na linha de comando
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | zls
# Verificar se o build.zig é válido
zig build 2>&1
# Verificar permissões dos executáveis
ls -la $(which zig) $(which zls)
Checklist de Resolução
- Zig está instalado e no PATH
- ZLS está instalado e no PATH
- Versões de Zig e ZLS são compatíveis
- Extensão do VS Code está instalada e habilitada
- Projeto tem
build.zigválido - Cache limpo (
rm -rf zig-cache .zig-cache) - ZLS reiniciado após mudanças de configuração
Veja Também
- FAQ Ecossistema — Ferramentas e editores
- Erros no build.zig — Problemas que afetam o ZLS
- Zig Não Compila — Erros de compilação
- Instalação — Instalar Zig e ferramentas
- FAQ Iniciantes — Primeiros passos com Zig