Debugging e Resolução de Problemas Comuns do Electron

Quando sua aplicação Electron trava, congela ou consome memória excessiva, encontrar a causa raiz rapidamente é fundamental. Este guia fornece técnicas práticas de debugging para os problemas mais comuns do Electron, focando no que verificar primeiro e quais ferramentas usar.

Diagnosticando Crashes e Travamentos do Processo Renderer

Verificações Rápidas para Problemas do Renderer

Quando um processo renderer trava ou fica sem resposta, comece com estas verificações imediatas:

1. Abra o DevTools programaticamente antes que o crash ocorra:

win.webContents.openDevTools({ mode: 'detach' });

2. Verifique o console para exceções não capturadas - A maioria dos crashes do renderer se origina de erros JavaScript não tratados.

3. Monitore o uso de memória através da aba Performance do Chrome DevTools - Procure por picos de memória antes dos crashes.

Debugging do Processo Renderer com DevTools

Para problemas persistentes no renderer:

• Habilite relatórios de crash: Adicione win.webContents.on('crashed', (event) => {}) para capturar eventos de crash
• Use snapshots de memória: Tire heap snapshots no DevTools (aba Memory) para identificar objetos com vazamento
• Desabilite a aceleração de hardware para testes: app.disableHardwareAcceleration() - elimina crashes relacionados à GPU

Verificação rápida: Se o problema desaparecer com a aceleração de hardware desabilitada, você isolou um problema de GPU.

Debugging de Problemas do Processo Principal

Configuração de Debugging do Electron no VS Code

Configure o VS Code para debugging do processo principal com este launch.json mínimo:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Main Process",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
  "program": "${workspaceFolder}/main.js",
  "outputCapture": "std"
}

Resolução de Problemas do Processo Principal

Primeiros passos para problemas do processo principal:

1. Verifique stdout/stderr: Adicione "outputCapture": "std" para ver erros de módulos nativos
2. Defina breakpoints em eventos de ciclo de vida (app.on('ready'), app.on('before-quit'))
3. Monitore a memória do processo: Use process.memoryUsage() para registrar valores RSS

Abordagens de correção:

• Para RSS alto: Verifique referências retidas de BrowserWindow - garanta win = null após fechar
• Para crashes: Habilite core dumps com app.setPath('crashDumps', path)
• Para travamentos: Faça profile do uso de CPU com a flag --inspect e Chrome DevTools

Vazamentos de Memória e RSS Alto

Técnicas de Profiling de Memória no Electron

Identifique vazamentos de memória sistematicamente:

1. Compare heap snapshots: Tire snapshots antes e depois de operações suspeitas de vazamento
2. Monitore RSS vs heap: RSS inclui memória nativa - se RSS crescer mas heap não, verifique módulos nativos
3. Rastreie listeners IPC: Listeners não registrados são fontes comuns de vazamento

Prevenção de Vazamento de Listeners IPC

Padrão comum de vazamento de memória IPC:

// RUIM: Cria novo listener a cada render
ipcRenderer.on('data-update', handler);

// BOM: Remove ao desmontar
const handler = (event, data) => { /* ... */ };
ipcRenderer.on('data-update', handler);
// Na limpeza:
ipcRenderer.removeListener('data-update', handler);

Verificação: Verifique a contagem de listeners com ipcRenderer.listenerCount('event-name')

Problemas de Configuração e Segurança

Prevenção de Exposição do Modo Debug

Verificações críticas de produção:

1. Desabilite o DevTools em produção:

if (app.isPackaged) {
  win.webContents.on('devtools-opened', () => {
    win.webContents.closeDevTools();
  });
}

2. Remova itens de menu de debug: Remova opções de debug dos menus de produção
3. Desabilite o módulo remote: Defina enableRemoteModule: false em webPreferences

Quando Escalar

Crie uma reprodução mínima antes de registrar problemas:

1. Isole o problema: Remova todo código não essencial
2. Teste com Electron vanilla: Use minimal-repro como baseline
3. Documente precisamente: Inclua números exatos de RSS/heap, versão do Electron e plataforma

Ao registrar problemas no Electron/Chromium, forneça:

• Código mínimo reproduzível
• Medições de memória (RSS e heap)
• Tipo de processo afetado (main/renderer)
• Crash dumps se disponíveis

Melhores Práticas

Três Práticas Essenciais de Debugging

1. Proteja builds de produção: Sempre verifique app.isPackaged antes de habilitar recursos de debug. Nunca distribua com DevTools acessível.

2. Limpe listeners IPC: Implemente um padrão de limpeza para todos os listeners IPC. Use removeListener() ou removeAllListeners() ao desmontar componentes.

3. Monitore RSS junto com heap: Heap snapshots JavaScript não mostram memória nativa. Sempre rastreie process.memoryUsage().rss para investigação completa de memória.

Dica final: Para cenários complexos de debugging, use electron-debug para adicionar atalhos do DevTools e outros recursos de debugging com configuração mínima.

Conclusão

Depurar aplicações Electron requer uma abordagem sistemática para identificar se os problemas se originam no processo principal ou renderer. Ao usar as ferramentas certas—desde DevTools para problemas do renderer até debugging no VS Code para problemas do processo principal—você pode rapidamente isolar e corrigir crashes, vazamentos de memória e problemas de performance. Lembre-se de sempre proteger seus builds de produção e manter padrões limpos de comunicação IPC para prevenir que problemas comuns ocorram em primeiro lugar.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.