--- title: "ZLS (Zig Language Server): Instalação e Config | Zig Brasil" url: "https://ziglang.com.br/ecossistema/zls-zig-language-server-instala%C3%A7%C3%A3o-e-config-zig-brasil/" markdown_url: "https://ziglang.com.br/ecossistema/zls-zig-language-server-instala%C3%A7%C3%A3o-e-config-zig-brasil.MD" description: "Configure o ZLS no VS Code, Neovim e Emacs. Guia completo de instalação, autocompletar, go-to-definition e dicas de produtividade para Zig." date: "2026-02-21" author: "Zig Brasil" --- # ZLS (Zig Language Server): Instalação e Config | Zig Brasil Configure o ZLS no VS Code, Neovim e Emacs. Guia completo de instalação, autocompletar, go-to-definition e dicas de produtividade para Zig. # ZLS — Zig Language Server: Configuração e Uso Completo O ZLS (Zig Language Server) é a ferramenta essencial para qualquer desenvolvedor Zig que deseja produtividade no dia a dia. Implementando o protocolo LSP (Language Server Protocol), o ZLS traz funcionalidades avançadas de IDE para praticamente qualquer editor de texto moderno: autocompletar inteligente, diagnósticos em tempo real, navegação de código, informações de hover, formatação automática e muito mais. ## O Que É o ZLS O ZLS é um servidor de linguagem escrito inteiramente em Zig que analisa seu código em tempo real enquanto você digita. Ele se comunica com seu editor através do protocolo LSP, o mesmo padrão utilizado por ferramentas como rust-analyzer (Rust), gopls (Go) e typescript-language-server (TypeScript). Isso significa que qualquer editor com suporte a LSP pode se beneficiar do ZLS. O projeto é mantido pela comunidade com contribuições frequentes e possui forte alinhamento com as atualizações do compilador Zig. Cada nova versão do compilador geralmente é acompanhada por uma atualização correspondente do ZLS. ## Recursos Principais ### Autocompletar Inteligente O ZLS oferece autocompletar contextual que entende os tipos, funções, campos de structs e módulos do seu projeto. Ele analisa não apenas o arquivo atual, mas toda a árvore de dependências, incluindo pacotes importados via `build.zig.zon`. ```zig const std = @import("std"); pub fn main() void { var list = std.ArrayList(u8).init(std.heap.page_allocator); list. // ZLS mostra: append, appendSlice, items, deinit, etc. } ``` ### Diagnósticos em Tempo Real Sem precisar compilar manualmente, o ZLS destaca erros de sintaxe, tipos incompatíveis, variáveis não utilizadas e outros problemas diretamente no editor. Isso acelera enormemente o ciclo de desenvolvimento. ### Go to Definition e Find References Navegue instantaneamente para a definição de qualquer símbolo com um clique ou atalho de teclado. Encontre todas as referências a uma função, tipo ou variável em todo o projeto. ### Hover Information Passe o cursor sobre qualquer identificador para ver sua assinatura de tipo, documentação inline e informações de módulo. Essa funcionalidade é especialmente útil quando se trabalha com APIs complexas da biblioteca padrão. ### Inlay Hints O ZLS pode exibir hints inline que mostram os tipos inferidos de variáveis, nomes de parâmetros em chamadas de função e tipos de retorno, tudo sem poluir o código fonte. ### Formatação Automática Integra o `zig fmt` diretamente no editor, permitindo formatação automática ao salvar ou sob demanda. Isso garante que todo o código do projeto siga o estilo oficial do Zig. ## Instalação ### Via Gerenciador de Pacotes do Sistema No Linux, você pode instalar o ZLS através de gerenciadores de pacotes: ```bash # Arch Linux sudo pacman -S zls # Nix nix-env -iA nixpkgs.zls # Homebrew (macOS e Linux) brew install zls ``` ### Compilação a Partir do Fonte Para a versão mais recente ou para corresponder exatamente à versão do seu compilador: ```bash git clone https://github.com/zigtools/zls cd zls zig build -Doptimize=ReleaseSafe ``` O binário será gerado em `zig-out/bin/zls`. Adicione-o ao seu PATH ou copie para `/usr/local/bin/`. ### Via zigup Se você usa o [zigup](/ecossistema/zigup-version-manager/) como gerenciador de versões, ele pode gerenciar o ZLS automaticamente: ```bash zigup fetch-zls 0.13.0 ``` ## Configuração por Editor ### VS Code Instale a extensão oficial "Zig Language" do marketplace do VS Code. A extensão detecta automaticamente o ZLS se estiver no PATH. Para configurar manualmente: ```json { "zig.path": "/caminho/para/zig", "zig.zls.path": "/caminho/para/zls", "zig.zls.enableAutofix": true, "zig.formattingProvider": "zls" } ``` A extensão também oferece suporte a snippets, syntax highlighting avançado e integração com o [sistema de build](/ecossistema/zig-build-system-overview/). ### Neovim Com o nvim-lspconfig, a configuração é direta: ```lua -- init.lua require('lspconfig').zls.setup{ cmd = { "zls" }, settings = { zls = { enable_snippets = true, enable_ast_check_diagnostics = true, enable_autofix = true, enable_import_detection = true, skip_std_references = false, enable_inlay_hints = true, inlay_hints_exclude_single_argument = true, operator_completions = true, } } } ``` Para uma experiência ainda mais completa no Neovim, considere usar plugins como telescope.nvim para navegação de símbolos e trouble.nvim para uma lista de diagnósticos organizada. ### Emacs Com o lsp-mode ou eglot: ```elisp ;; Com lsp-mode (use-package zig-mode :hook (zig-mode . lsp-deferred)) ;; Com eglot (Emacs 29+) (add-to-list 'eglot-server-programs '(zig-mode . ("zls"))) (add-hook 'zig-mode-hook 'eglot-ensure) ``` ### Sublime Text Instale o pacote "LSP" e "LSP-zig" via Package Control. A configuração é automática se o ZLS estiver no PATH. ### Helix O Helix já inclui configuração padrão para ZLS. Basta ter o binário no PATH e abrir um arquivo `.zig`. ## Configuração Avançada do ZLS O ZLS pode ser configurado globalmente através de um arquivo `zls.json` no diretório de configuração do usuário: ```json { "zig_exe_path": "/usr/local/bin/zig", "warn_style": true, "enable_snippets": true, "enable_ast_check_diagnostics": true, "enable_autofix": true, "enable_import_detection": true, "enable_inlay_hints": true, "inlay_hints_show_builtin": true, "operator_completions": true, "include_at_in_builtins": false, "skip_std_references": false, "builtin_path": null, "highlight_global_var_declarations": true } ``` ### Opções Importantes - **`enable_ast_check_diagnostics`**: Ativa análise AST para diagnósticos mais profundos. Recomendado manter ativado. - **`skip_std_references`**: Pule referências na biblioteca padrão ao buscar referências. Útil em projetos grandes para melhorar performance. - **`enable_import_detection`**: Detecta automaticamente imports não utilizados e sugere remoção. - **`enable_autofix`**: Aplica correções automáticas quando possível (como remover imports não utilizados). ## Dicas de Produtividade ### Workspace Symbols Use a busca de símbolos do workspace (geralmente `Ctrl+T` ou `:Telescope lsp_workspace_symbols` no Neovim) para navegar rapidamente entre funções, structs e constantes de todo o projeto. ### Code Actions O ZLS oferece code actions contextuais como: - Remover imports não utilizados - Adicionar `try` faltante - Converter entre notações de ponteiro - Organizar imports ### Integração com Build System O ZLS analisa automaticamente seu `build.zig` e `build.zig.zon` para entender as dependências do projeto. Isso significa que pacotes baixados pelo [gerenciador de pacotes](/ecossistema/zig-pkg-manager/) são automaticamente reconhecidos pelo autocompletar. ## Resolução de Problemas ### ZLS Não Encontra o Compilador Verifique se o `zig` está no PATH ou configure `zig_exe_path` no `zls.json`. A versão do ZLS deve corresponder à versão do compilador. ### Performance Lenta em Projetos Grandes Ative `skip_std_references` e considere fechar arquivos não utilizados. O ZLS mantém em memória a análise de todos os arquivos abertos. ### Diagnósticos Não Aparecem Verifique se `enable_ast_check_diagnostics` está ativado. Alguns editores podem desativar diagnósticos por padrão para servidores LSP desconhecidos. ## Relação com Outras Ferramentas O ZLS complementa outras ferramentas do ecossistema. Use-o em conjunto com as [ferramentas de debug](/ecossistema/zig-debug-tools/) para depuração, [ferramentas de profiling](/ecossistema/zig-profiling-tools/) para otimização e os [frameworks de teste](/ecossistema/zig-testing-frameworks/) para garantir qualidade do código. Para conhecer todos os plugins disponíveis para editores, consulte nosso guia de [plugins para IDEs](/ecossistema/zig-ide-plugins/). ## Contribuindo para o ZLS O ZLS é um projeto open source e aceita contribuições. Se você encontrou um bug ou quer implementar uma feature, visite o repositório no GitHub. A comunidade é acolhedora e há issues marcadas como "good first issue" para iniciantes. Para mais informações sobre como começar com Zig, consulte nossos [tutoriais](/tutoriais/) e [receitas práticas](/receitas/).