---
title: "VS Code e ZLS — Resolver Problemas com Editor e Language Server"
url: "https://ziglang.com.br/troubleshooting/vs-code-e-zls-resolver-problemas-com-editor-e-language-server/"
markdown_url: "https://ziglang.com.br/troubleshooting/vs-code-e-zls-resolver-problemas-com-editor-e-language-server.MD"
description: "Guia para resolver problemas com VS Code e ZLS (Zig Language Server). Autocompletar não funciona, erros falsos, ZLS não inicia, configuração e diagnóstico."
date: "2026-02-21"
author: "Zig Brasil"
---

# VS Code e ZLS — Resolver Problemas com Editor e Language Server

Guia para resolver problemas com VS Code e ZLS (Zig Language Server). Autocompletar não funciona, erros falsos, ZLS não inicia, configuração e diagnóstico.


# 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:**

```bash
# 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.

```bash
# 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

1. Instale a extensão **"Zig Language"** (de ziglang) no VS Code
2. Configure o caminho do Zig e ZLS:

```json
// 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:
```bash
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`.
```bash
# 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.
```bash
# 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:**

```bash
# 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](https://github.com/zigtools/zls/issues).

## ZLS Consume Muita Memória ou CPU

**Causa:** Projetos grandes ou com muitos `@cImport` podem sobrecarregar o ZLS.

**Soluções:**

```json
// 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

```json
// 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:
```bash
# Deve funcionar na linha de comando
zig fmt src/main.zig
```

## Configurar Neovim com ZLS

```lua
-- 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
```elisp
;; Com eglot (built-in no Emacs 29+)
(add-to-list 'eglot-server-programs '(zig-mode "zls"))
(add-hook 'zig-mode-hook 'eglot-ensure)
```

### Helix
```toml
# ~/.config/helix/languages.toml
[[language]]
name = "zig"
language-servers = ["zls"]

[language-server.zls]
command = "zls"
```

### Sublime Text
```json
// LSP-zig.sublime-settings
{
    "command": ["zls"],
    "selector": "source.zig"
}
```

## Diagnóstico Geral

```bash
# 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

1. Zig está instalado e no PATH
2. ZLS está instalado e no PATH
3. Versões de Zig e ZLS são compatíveis
4. Extensão do VS Code está instalada e habilitada
5. Projeto tem `build.zig` válido
6. Cache limpo (`rm -rf zig-cache .zig-cache`)
7. ZLS reiniciado após mudanças de configuração

## Veja Também

- [FAQ Ecossistema](/faq/faq-ecossistema/) — Ferramentas e editores
- [Erros no build.zig](/troubleshooting/zig-build-zig-erros/) — Problemas que afetam o ZLS
- [Zig Não Compila](/troubleshooting/zig-nao-compila/) — Erros de compilação
- [Instalação](/instalacao/) — Instalar Zig e ferramentas
- [FAQ Iniciantes](/faq/faq-iniciantes/) — Primeiros passos com Zig