> For the complete documentation index, see [llms.txt](https://weekly-essay.mikey.wang/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://weekly-essay.mikey.wang/pt-br/2026/w03-lessons-from-advanced-troubleshooting.md).

# W03-Lições de investigações técnicas difíceis

Na semana passada, tivemos um avanço importante em um problema fantasma do Webpack que nos incomodava havia quase três anos. Aproveito para organizar as características dos problemas estranhos e difíceis no frontend e algumas lições sobre como lidar com eles.

***

#### Os problemas estranhos e difíceis se dividem em dois tipos, conforme haja ou não um defeito no código

* No primeiro tipo, o código tem uma falha de projeto muito discreta. São defeitos lógicos latentes que só aparecem em condições específicas. Por exemplo, hipóteses erradas sobre assincronia, concorrência ou estado podem se revelar apenas em dispositivos lentos ou sob determinada ordem de execução. O caso que mais encontramos são condições de corrida relacionadas ao tempo de execução; adiante, trago exemplos concretos.
* No segundo tipo, a causa costuma estar fora do próprio código: é preciso procurar a verdade em um sistema cheio de incertezas. É justamente aí que está a dificuldade avançada do diagnóstico no frontend. Além de escrever código correto, é preciso entender o mundo em que ele vai rodar. Podemos chamar esse mundo de “ambiente de execução incerto”. Seu grau de incerteza frequentemente torna tanto a observação quanto a reprodução difíceis.

***

#### O ambiente de execução incerto

É uma hipótese técnica: considerar tudo pouco confiável, exceto o código. O objetivo é preparar as defesas.

Esse ambiente de execução incerto começa já no build do código.

> Build (escolhas humanas) → Container (forte personalização) → OS & Hardware (alta fragmentação) → User & Physical Context (fora de controle).

**1. Build: diferenças na infraestrutura e nos artefatos gerados**

Versões diferentes de polyfills, bibliotecas de runtime e configurações de build podem fazer uma sintaxe nova falhar diretamente em ambientes antigos ou gerar erros por injeção duplicada ou incorreta.

> Há algum tempo, o Yuefu apresentou uma ordem anormal de execução de Promise/thenable em dispositivos de entrada depois da troca do Webpack pelo Rspack. A ferramenta de build em si talvez não tivesse um bug; diferenças no comportamento do runtime gerado podem disparar o problema. O Webpack tem um runtime complexo que usa Promise/thenable para coordenar a ordem de carregamento dos módulos.
>
> No checkout para comerciantes, encontramos uma falha de set cookie no aplicativo Kuailü, causada pela ordem de execução entre diferentes threads do cliente.

**2. Container: diferenças no aplicativo hospedeiro e no mecanismo do WebView**

Os WebViews não se comportam da mesma forma na execução de JS, na renderização de CSS, na segurança ou nas interfaces. A camada que os envolve também pode injetar ou restringir APIs, fazendo a mesma página H5 se comportar de maneiras diferentes conforme o contêiner.

> Um exemplo típico são os interceptadores no iOS. O contêiner pode interceptar requisições de rede e mudanças de rota; uma implementação incorreta ou duplicada dessa interceptação cria problemas. No Huixiao, por exemplo, uma falha de set cookie invalidou o token. Também tivemos problemas com o funcionamento offline no aplicativo de comerciantes de delivery.
>
> Nesse aplicativo, encontramos ainda a injeção de um hook que carregava automaticamente a versão 1.9.1 de knb.js quando o arquivo não estava presente. No Android, isso ocasionalmente fazia a inscrição em appear ser bem-sucedida sem que o callback fosse executado.

**3. OS & Hardware: fragmentação de sistemas e dispositivos**

Diferenças entre ROMs de fabricantes, modelos, resoluções e versões do sistema podem provocar falhas, layouts incorretos ou problemas de desempenho em aparelhos específicos.

> No aplicativo iOS para comerciantes de delivery, um único usuário chegou a disparar muitas chamadas repetidas a yoda. No ano seguinte, ao resolver outro problema, percebemos que os dois casos podiam ser tratados juntos. A causa final era a falta de memória disponível em aparelhos de entrada. Após o alerta de memória, o mecanismo de manutenção da atividade fazia o WebView chamar reload repetidas vezes, levando o mesmo usuário a entrar na página com grande frequência em um intervalo curto.

**4. User & Physical Context: diferenças no ambiente real dos usuários**

Os usuários usam o produto de inúmeras maneiras e em condições distintas: rede instável, pouca bateria, armazenamento insuficiente, entre outras. São variáveis fora de controle que podem gerar anomalias nos casos extremos. Como muitas vezes não se repetem, esses problemas são especialmente difíceis de investigar. É necessário cruzar logs de instrumentação e registros das ações dos usuários para encontrar pistas.

> Em um cenário de pagamento de terceiros, encontramos falhas causadas pelo uso de duas instâncias do WeChat. Alguns usuários usam recursos do sistema ou de terceiros para executar duas instâncias do mesmo aplicativo no mesmo celular. Esse mecanismo pode quebrar a hipótese de instância única do aplicativo ou o canal de IPC, causando problemas inesperados.

***

#### Já caí em muitas armadilhas. Algumas lições e dois casos

Primeiro, abandonar o apego à própria explicação. Nem todo problema difícil precisa receber de imediato uma “explicação perfeita”. Se já houve um incidente, a prioridade é aliviar a pressão à sua volta. Encontre primeiro uma solução de contorno controlável que contenha o risco e permita que a atenção das pessoas se volte rapidamente a outras coisas. A grande maioria não se importa com a “causa definitiva”. Só depois de estabilizar a situação é possível buscar a verdade com calma.

Segundo, ter persistência e coragem para enfrentar desafios é o que constrói profundidade técnica. Muitos problemas se resolvem de repente após uma longa espera. Quando chegar a um beco sem saída, deixe o problema em aberto, espere uma oportunidade ou uma ideia, preencha o que estiver faltando, mas não desista.

***

#### Caso 1: instabilidade nos artefatos gerados pelo Webpack

O problema mencionado no início foi um processo de quase três anos, no qual nos aproximamos da verdade pouco a pouco, da superfície às camadas mais profundas.

1. Sintoma. Às vezes, os artefatos gerados pelo Webpack não funcionavam, causando telas em branco ocasionais em produção. No primeiro contato, não conseguimos achar a causa, mas corrigimos um problema no mecanismo de publicação da esteira. Assim, garantimos que a validação com a lista de usuários autorizados e a liberação geral usassem o mesmo pacote.
2. Análise da configuração. Mais tarde, Hongze fez uma análise específica da configuração do Webpack e identificou builds anormais causados pela mistura de ESM e CJS em dependências de terceiros. A configuração foi melhorada, mas ainda surgiam artefatos defeituosos.
3. Experimento coletivo e compromisso. No ano passado, Jianzhuan apresentou o problema em uma sessão de compartilhamento de fundamentos. Reproduziu a instabilidade dos artefatos ao vivo com a equipe. O experimento aprofundou a compreensão coletiva do build e revelou uma opção de configuração mais eficaz: desativar o empacotamento assíncrono eliminava os artefatos defeituosos, ao custo da velocidade de build.
4. Solução final. Na semana passada, Jianzhuan apresentou uma nova solução. Identificou uma característica importante nos artefatos, o wrapper n.n(). Ao verificar se os padrões de minificação de CJS nos artefatos correspondem ao esperado, é possível garantir a correção dos pacotes publicados e fechar por completo essa brecha de qualidade.

Acho que, com isso, podemos encerrar o problema. Se houver capacidade sobrando, o próximo passo será ajudar o Webpack a resolver de vez o problema da construção assíncrona de módulos CJS e enviar um PR.

***

#### Caso 2: refatoração de marketing do projeto Alpha

Um problema pode ser resolvido sem receber uma explicação técnica completa. O processo de enfrentá-lo importa mais.

Uma refatoração de marketing do projeto Alpha fez cair a conversão de abertura de contas. Foram mais de dois meses até resolver a situação, que expôs uma série de problemas. No fim, não encontramos a causa técnica e já não havia condições de reproduzi-la. Nunca teremos uma explicação técnica completa.

Mas o processo aprofundou nossa compreensão da qualidade. Naquele período, construímos observação em tempo real dos indicadores de negócio, capacidade de experimentos A/B e uma rotina de gestão da qualidade antes da produção. Também refletimos a fundo sobre estratégias e decisões de rollback. O episódio levou diretamente à refatoração integral do projeto Alpha no ano seguinte, estabelecendo para a equipe uma boa referência de manutenibilidade.