Meu jogo rodava no meu PC, mas quebrava no celular de outras pessoas — a armadilha do deploy

Eu publiquei um jogo para web.

No meu computador, funcionava. O código corrigido já estava no GitHub. O deploy tinha terminado com sucesso.

Mesmo assim, em alguns celulares, o jogo continuava quebrando.

No Analytics, aparecia este erro:

SyntaxError: Unexpected token '<'

Eu estava mexendo com JavaScript. Então por que, de repente, um sinal de “<” era o problema?

Isso aconteceu enquanto eu desenvolvia o ORA Quest. A parte mais útil da experiência não foi descobrir uma linha mágica de código, e sim entender o que esse erro costuma estar tentando dizer.

Talvez o “<” nem seja o verdadeiro problema

Minha primeira reação foi procurar um erro de sintaxe. Um caractere estranho? JSON quebrado? Uma vírgula faltando?

Mas quando aparece Unexpected token '<', uma das primeiras coisas que vale checar é se o navegador pediu JavaScript ou JSON e o servidor devolveu HTML.

Imagine que o navegador solicite game.js. Ele espera JavaScript. Só que o servidor responde com uma página de erro começando em <!DOCTYPE html>.

O navegador tenta interpretar aquilo como JavaScript, encontra o primeiro < e falha.

Ou seja: o símbolo pode não ser o culpado. O navegador pode simplesmente ter recebido o tipo errado de conteúdo.

Os bugs mais chatos não quebram para todo mundo

Foi exatamente isso que tornou o problema tão enganoso.

No PC funcionava. Em alguns celulares também. Mas em outros aparelhos ou dentro do navegador de um app social, falhava.

Aí é muito fácil cair neste ciclo:

corrige → faz deploy → abre no próprio PC → funciona → considera resolvido.

Eu também fazia isso.

Se o problema depende de cache, navegador, arquivo antigo ou de um caminho específico da requisição, a sua própria máquina pode passar uma falsa sensação de segurança.

As 5 coisas que eu verificaria primeiro hoje

1. Abrir diretamente a URL do JavaScript ou JSON que está falhando.
2. Checar se a resposta é realmente JavaScript ou JSON.
3. Ver se, no lugar disso, veio uma página 404, login, página do WordPress ou outro HTML.
4. Confirmar se o servidor em produção está servindo o arquivo que você espera encontrar no GitHub.
5. Testar em outro aparelho ou navegador, evitando depender do mesmo cache.

A primeira checagem é especialmente valiosa.

Em vez de sair alterando código porque “parece um erro de JavaScript”, faça antes uma pergunta simples:

O que essa URL está devolvendo de verdade?

Isso pode poupar bastante tempo corrigindo a coisa errada.

GitHub correto não significa produção correta

Também aprendi isso do jeito difícil.

Você pode ter o código certo no GitHub e, ainda assim, o usuário receber outra coisa.

No caminho existem automação de deploy, servidor, WordPress, cache de servidor ou CDN, cache do navegador e navegadores dentro de aplicativos.

Basta uma camada entregar uma versão antiga ou inesperada para surgir o “mas eu já corrigi isso”.

Por isso mudei minha definição de “corrigido”.

Um conserto não termina quando o commit está certo. Termina quando a URL real de produção funciona em condições parecidas com as do usuário real.

Não tente apenas apagar o erro — facilite a investigação da próxima vez

Antes eu queria apenas fazer o erro desaparecer.

Hoje também tento deixar informações suficientes para entendê-lo se ele voltar.

Qual arquivo falhou? Qual URL foi pedida? Em qual ambiente? Qual build estava rodando?

Assim, na próxima vez, a pergunta deixa de ser “o mesmo bug misterioso voltou” e vira “é a mesma causa de antes ou uma nova?”.

Não é um trabalho chamativo, mas para quem mantém um serviço sozinho pode valer mais do que adicionar mais uma funcionalidade.

Desenvolvimento solo é muitas vezes mais sobre entender a realidade do que escrever código

Antes de começar a fazer jogos web, eu imaginava desenvolvimento como criar personagens, escrever histórias e programar sistemas.

Na prática, muito tempo vai para perguntas como: por que só este aparelho falha? Por que o JavaScript de ontem ainda aparece? Por que uma URL de JSON está devolvendo HTML?

Cada problema que eu consigo entender aumenta um pouco o que consigo construir depois.

A maior lição de Unexpected token '<' foi simples:

o código que você escreveu e o arquivo que o usuário realmente recebe nem sempre são a mesma coisa.

Se você está vendo esse erro agora, antes de reescrever seu JavaScript, abra diretamente a URL do JS ou JSON que falhou. Se aparecer HTML, você já encontrou uma pista importante.

Estou aprendendo tudo isso enquanto construo o ORA Quest. Se quiser ver para que serve todo esse debugging no fim das contas, dá para jogar gratuitamente a demo de ORA Quest.