No cenário atual do desenvolvimento front-end e full-stack, a capacidade de depurar código de forma eficiente é crucial para a produtividade e a rápida resolução de problemas. O Visual Studio Code (VS Code) se destaca como uma ferramenta essencial, não apenas por sua leveza e ecossistema de extensões, mas principalmente por suas robustas funcionalidades de depuração. Ele oferece suporte flexível para depurar uma ampla gama de ambientes, desde aplicações Node.js no backend e código JavaScript em navegadores, até sistemas de microsserviços complexos e contêineres.
A verdadeira força do VS Code na depuração vai além de simples pontos de interrupção ou inspeção de variáveis. Ela reside na sua compatibilidade com múltiplas linguagens e runtimes, e na sua capacidade de personalização através de configurações de depuração. Ao dominar esses recursos, desenvolvedores podem otimizar o processo de identificação e correção de bugs, e desenvolver uma abordagem mais sistemática para a depuração, resultando em software de maior qualidade.
Este artigo explorará os recursos de depuração do VS Code, cobrindo desde configurações básicas até cenários avançados, para ajudar você a maximizar seu potencial de desenvolvimento.
Interface de Depuração
A interface de depuração do VS Code é intuitiva e segue um padrão comum a muitas ferramentas de depuração. Ela inclui seções para controlar a execução (continuar, pausar, passar por cima, entrar na função, sair da função), inspecionar variáveis, visualizar a pilha de chamadas e interagir com um terminal de depuração. Familiarizar-se com esses painéis é o primeiro passo para uma depuração eficaz.
Categorias de Depuração
No VS Code, os métodos de depuração podem ser categorizados em duas vertentes principais, com base na complexidade de sua configuração: métodos simples e configurações personalizadas.
Os métodos simples permitem iniciar a depuração rapidamente, sendo ideais para projetos mais básicos que não exigem configurações adicionais ou ferramentas auxiliares, como scripts JavaScript puros ou aplicações Node.js diretas. Nesta categoria, abordaremos o Auto Attach e o Terminal de Depuração JavaScript.
Para projetos mais complexos ou cenários específicos, o VS Code oferece configurações personalizadas através do arquivo launch.json. Este arquivo permite ajustar o ambiente de depuração às necessidades específicas do seu projeto, oferecendo grande flexibilidade.
Depuração Rápida: Auto Attach
O recurso Auto Attach do VS Code automatiza a conexão do depurador a um processo em execução. Quando um programa inicia no modo de depuração, o VS Code pode se anexar automaticamente, permitindo o uso da interface de depuração.
Para ativar esta funcionalidade, abra a paleta de comandos (Cmd+Shift+P no macOS ou Ctrl+Shift+P no Windows/Linux) e digite >Debug: Toggle Auto Attach. Você terá as seguintes opções:
always: Sempre anexa automaticamente quando um processo é iniciado em modo de depuração.flag: Anexa apenas quando o processo é iniciado com as flags--inspectou--inspect-brk.disabled: Desabilita o Auto Attach.
Após alterar a configuração, pode ser necessário reiniciar o VS Code.
Se você escolher a opção flag, o status aparecerá na barra de status inferior do IDE. Ao executar um comando como node --inspect my-script.js no terminal, o VS Code detectará automaticamente e se conectará ao processo para depuração.
O funcionamento do Auto Attach e de outras ferramentas de depuração (como o Chrome DevTools) é baseado na comunicação via WebSocket. Quando um processo Node.js é iniciado com --inspect, ele expõe um serviço WebSocket que permite a comunicação entre o depurador (VS Code ou Chrome DevTools) e o runtime da aplicação. Isso permite a troca de informações e o controle da execução do programa.
Terminal de Depuração JavaScript
Para uma depuração ainda mais simplificada, o Terminal de Depuração JavaScript é uma excelente opção. Basta abrir este tipo de terminal e executar seu programa normalmente. O VS Code cuidará automaticamente da configuração e conexão do depurador.
- Abra um novo Terminal de Depuração JavaScript (encontrado no menu Terminal > Novo Terminal de Depuração ou através da paleta de comandos).
- Execute seu comando de inicialização de programa, por exemplo:
node app.js.
Este método é ideal para cenários que exigem uma depuração rápida e sem complicações.
Configurações de Depuração Personalizadas (launch.json)
Para projetos mais elaborados, as configurações de depuração do VS Code são definidas no arquivo .vscode/launch.json. Este arquivo, formatado em JSON, permite criar tarefas de depuração altamente personalizadas.
Você pode criar o arquivo launch.json manualmente ou através da interface de depuração do VS Code. No painel de Depuração e Execução, clique na engrenagem ou selecione "criar um arquivo launch.json". O VS Code oferecerá modelos para as linguagens e ambientes mais comuns.
Uma configuração típica em launch.json inclui:
{
"version": "0.2.0", // Versão do formato do arquivo
"configurations": [
{
"type": "node", // Tipo de depurador (ex: "node", "chrome", "python")
"request": "launch", // Tipo de requisição: "launch" (iniciar) ou "attach" (anexar)
"name": "Depurar App Node", // Nome exibido na interface de depuração
"program": "${workspaceFolder}/src/server.js", // Caminho para o arquivo principal
"cwd": "${workspaceFolder}", // Diretório de trabalho atual
"env": {
// Variáveis de ambiente
"APP_ENV": "development"
},
"args": ["--logLevel=verbose"], // Argumentos passados para o programa
"port": 9229 // Porta para depuração (necessário para alguns tipos)
}
]
}
As configurações são divididas principalmente em dois tipos de requisição: launch e attach.
Pré e Pós-Tarefas (Tasks)
Em alguns fluxos de trabalho, pode ser necessário executar uma tarefa antes ou depois da depuração, como compilar o código. O VS Code permite integrar Tasks (tarefas) às suas configurações de depuração usando preLaunchTask e postLaunchTask.
As Tasks são definidas em .vscode/tasks.json. Por exemplo, para compilar um projeto TypeScript antes de depurar:
{
"version": "2.0.0",
"tasks": [
{
"type": "typescript",
"tsconfig": "tsconfig.json",
"problemMatcher": ["$tsc"],
"group": "build",
"label": "tsc: build-project"
}
]
}
Então, você pode referenciar esta tarefa em launch.json:
{
"preLaunchTask": "tsc: build-project" // O valor 'label' da task
}
Modo 'attach'
O modo attach é usado para conectar o depurador a um processo já em execução que foi iniciado em modo de depuração. Este é o mesmo princípio por trás do Auto Attach, mas com controle explícito via configuração.
{
"name": "Anexar ao Processo Node",
"port": 9229,
"address": "localhost",
"request": "attach",
"skipFiles": ["<node_internals>/**"],
"type": "node"
}
Para usar esta configuração, inicie seu programa Node.js com node --inspect-brk=9229 my-app.js e, em seguida, selecione e inicie a configuração "Anexar ao Processo Node" no VS Code.
Algumas propriedades úteis no modo attach incluem:
outFiles: Especifica a localização dos arquivos compilados, permitindo que o depurador mapeie para o código-fonte original via Source Maps.resolveSourceMapLocations: Define quais URLs ou caminhos o depurador deve considerar ao carregar Source Maps.continueOnAttach: Controla se o depurador deve continuar a execução automaticamente após se anexar a um processo (útil com--inspect-brk).
Modo 'launch'
O modo launch permite que o VS Code inicie o programa em modo de depuração e se conecte automaticamente. Este é o modo mais versátil para iniciar novas sessões de depuração.
O launch suporta várias maneiras de iniciar um programa:
url: Abre uma URL específica no navegador para depuração.program: Executa um arquivo de programa diretamente.runtimeExecutable: Usa um executável específico (comonpm,yarn) para iniciar o programa.
Iniciando com 'url'
Esta conifguração abre uma URL no navegador e permite a depuração do código front-end. Certifique-se de que seu servidor web esteja em execução antes de iniciar a depuração.
{
"name": "Iniciar Chrome para Frontend",
"request": "launch",
"type": "chrome",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/frontend",
"sourceMaps": true
}
Para que esta configuração funcione, você deve ter um servidor web rodando na porta 3000 (por exemplo, npx http-server -p 3000 ou seu servidor de desenvolvimento).
Iniciando com 'program'
Utilizado para iniciar um arquivo de programa específico, como um script Node.js.
{
"type": "node",
"request": "launch",
"name": "Depurar Script Principal",
"args": ["--port=8080"],
"program": "${workspaceFolder}/backend/main.js",
"env": { "APP_SECRET": "my-secret-key" }
}
Neste exemplo, args e env são usados para passar parâmetros de linha de comando e variáveis de ambiente para o script.
Iniciando com 'runtimeExecutable'
Ideal para iniciar aplicações que dependem de um runtime ou gerenciador de pacotes, como npm ou yarn.
{
"type": "node",
"request": "launch",
"name": "Depurar com NPM Script",
"skipFiles": ["<node_internals>/**"],
"cwd": "${workspaceFolder}/backend",
"args": ["--featureFlag=true"],
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start-dev"],
"env": { "DB_HOST": "localhost" }
}
Aqui, runtimeExecutable aponta para npm, e runtimeArgs passa os argumentos run start-dev para o npm.
Propriedades Importantes
Além das propriedades mencionadas, outras são essenciais para configurar o comportamento do depurador:
args: Array de strings que são passadas como argumentos para o programa sendo depurado.cwd(Current Working Directory): Define o diretório de trabalho a partir do qual o programa será executado. Crucial em projetos com múltiplos subdiretórios ou monorepos.runtimeArgs: Argumentos passados para oruntimeExecutable(ex:["--inspect"]paranode, ou["run", "build"]paranpm).env/envFile: Define variáveis de ambiente diretamente ou carrega-as de um arquivo.env.console: Controla onde a saída do programa será exibida. Opções inclueminternalConsole(o terminal de depuração do VS Code),integratedTerminal(um terminal integrado normal do VS Code) eexternalTerminal(um terminal externo).
Configurando Source Maps
Em projetos moderons, o código-fonte geralmente é transpilado, bundlado e minificado, tornando a depuração direta do código gerado quase impossível. Source Maps (mapas de origem) são cruciais para mapear o código compilado de volta ao código-fonte original.
As configurações de depuração fornecem propriedades para gerenciar Source Maps:
sourceMaps: Um booleano (padrãotrue) para habilitar o uso de Source Maps.outFiles: Um array de glob patterns que especificam a localização dos arquivos JavaScript compilados. O depurador usa isso para encontrar os Source Maps associados.webRoot: O caminho base do diretório raiz do seu projeto web, usado para resolver caminhos de Source Maps.sourceMapPathOverrides: Um objeto que permite remapear caminhos de Source Maps quando eles não correspondem aos caminhos reais dos arquivos no sistema de arquivos. Útil para bundles gerados por ferramentas como Webpack.resolveSourceMapLocations: Controla o escopo dos caminhos que o depurador deve usar para carregar Source Maps.
Exemplo de sourceMapPathOverrides para um projeto Webpack:
{
"sourceMapPathOverrides": {
"webpack:///./*": "${webRoot}/src/*",
"webpack:///src/*": "${webRoot}/src/*"
}
}
Adapte essas configurações de Source Map conforme a estrutura e a ferramenta de build do seu projeto.
Depuração em Grupo (Compounds)
Para cenários que envolvem múltiplos processos (como um front-end e um back-end separados), o VS Code permite agrupar várias configurações de depuração em um compound, iniciando-as simultaneamente.
{
"version": "0.2.0",
"configurations": [
{
"name": "Iniciar Servidor Express",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/server/app.js"
},
{
"name": "Iniciar Cliente React",
"type": "chrome",
"request": "launch",
"url": "http://localhost:5173",
"webRoot": "${workspaceFolder}/client"
}
],
"compounds": [
{
"name": "Fullstack Debug",
"configurations": ["Iniciar Servidor Express", "Iniciar Cliente React"]
}
]
}
Ao selecionar e iniciar "Fullstack Debug", ambas as configurações serão ativadas, permitindo depurar o cliente e o servidor ao mesmo tempo.
Casos de Uso de Depuração
Depurando Código-Fonte Vue
Para depurar um projeto Vue, você geralmente precisará de uma configuração para o navegador, apontando para o servidor de desenvolvimento do Vue CLI ou Vite. Certifique-se de que seu servidor de desenvolvimento esteja em execução.
{
"name": "Vue App Frontend",
"request": "launch",
"type": "chrome",
"url": "http://localhost:8080",
"webRoot": "${workspaceFolder}/src",
"sourceMaps": true
}
Após iniciar, navegue para o código-fonte Vue no VS Code e defina seus pontos de interrupção.
Depurando Node.js
Uma configuração comum para Node.js, especialmente quando usando scripts npm:
{
"name": "Depurar API Node",
"request": "launch",
"runtimeArgs": ["run", "start:dev"],
"runtimeExecutable": "npm",
"skipFiles": ["<node_internals>/**"],
"type": "node",
"cwd": "${workspaceFolder}/server"
}
Depurando NestJS
Projetos NestJS frequentemente usam um script de desenvolvimento que compila e inicia o servidor. Uma configuração launch é ideal:
{
"name": "Depurar Servidor NestJS",
"request": "launch",
"runtimeArgs": ["run", "start:debug"],
"runtimeExecutable": "pnpm",
"skipFiles": ["<node_internals>/**"],
"type": "node",
"cwd": "${workspaceFolder}/api"
}
Depurando TypeScript
A depuração de TypeScript requer Source Maps. A configuração deve indicar onde os arquivos JavaScript compilados (outFiles) estão localizados para que o depurador possa mapeá-los de volta ao TypeScript original.
{
"name": "Depurar Aplicação TS",
"type": "node",
"request": "launch",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/ts-src/entry.ts",
"outFiles": ["${workspaceFolder}/ts-dist/**/*.js"],
"sourceMaps": true
}
Depurando Aplicações SSR (Server-Side Rendering)
Para aplicações SSR, que combinam lógica de front-end e back-end, um compound é a solução mais eficaz, permitindo depurar ambos os lados simultaneamente.
{
"version": "0.2.0",
"configurations": [
{
"name": "SSR: Cliente (Navegador)",
"request": "launch",
"type": "chrome",
"url": "http://localhost:4000",
"webRoot": "${workspaceFolder}/client",
"sourceMaps": true
},
{
"name": "SSR: Servidor (Node)",
"type": "node",
"request": "launch",
"skipFiles": ["<node_internals>/**"],
"runtimeExecutable": "pnpm",
"runtimeArgs": ["dev:ssr"],
"cwd": "${workspaceFolder}/server",
"sourceMaps": true,
"sourceMapPathOverrides": {
"webpack:///./*": "${webRoot}/src/*"
}
}
],
"compounds": [
{
"name": "Depurar SSR Completo",
"configurations": ["SSR: Cliente (Navegador)", "SSR: Servidor (Node)"]
}
]
}
Lembre-se de configurar Source Maps adequadamente para ambos os ambientes.
Depuração de Outras Linguagens
O VS Code não se limita a JavaScript e TypeScript. Graças ao seu sistema de extensões, ele suporta a depuração de uma vasta gama de linguagens, incluindo Python, Java, C#, Go e PHP. Para depurar uma linguagem específica, basta procurar e instalar a extensão de depuração correspondente no Marketplace do VS Code.
Princípios Fundamentais da Depuração
A funcionalidade de depuração do VS Code é construída sobre protocolos padronizados que facilitam a comunicação entre o IDE e o processo a ser depurado.
Chrome DevTools Protocol (CDP)
O CDP é um protocolo de comunicação fornecido pelo Google para interagir com o navegador Chrome e outros ambientes baseados em Chromium. Ele permite que ferramentas de depuração (como o VS Code e as próprias ferramentas de desenvolvedor do Chrome) controlem e inspecionem o navegador, depurem JavaScript, manipulem o DOM, analisem o desempenho de rede, entre outras funcionalidades. Quando o VS Code depura JavaScript no navegador ou em ambientes Node.js (que usam uma variação do protocolo), ele se comunica usando o CDP.
Debug Adapter Protocol (DAP)
O VS Code utiliza o Debug Adapter Protocol (DAP) como uma camada de abstração entre o editor e os depuradores de diferentes linguagens. Em vez de cada depurador precisar entender os detalhes de implementação do VS Code, ele se comunica com um Debug Adapter. Este adaptador, por sua vez, traduz os comandos e eventos do VS Code para o protocolo nativo do depurador da linguagem (como CDP para JavaScript, ou outros protocolos para Python, Java, etc.). Isso permite que o VS Code suporte a depuração de várias linguagens de forma consistente, sem precisar de lógica específica para cada uma dentro do seu núcleo.