[Vibe Coder #4] Por que o deploy quebra meu app?

O app está pronto. Ele funciona perfeitamente no meu computador. Copio localhost:3000 da barra de endereços para mostrá-lo a um amigo, mas ele responde: “Não abre”. Finalmente faço o deploy e, desta vez, o app que funcionava localmente começa a gerar erros na internet.

No vibe coding, é aqui que a maioria das pessoas se frustra: no deploy. Neste episódio, explicamos o que o deploy realmente faz e as três principais causas de algo funcionar localmente, mas falhar depois do deploy.

localhost significa “meu computador”

localhost não é um endereço especial, mas um pronome que significa “este computador”. Quando a IA diz “Verifique localhost:3000”, ela quer dizer para abrir, no navegador do meu computador, o app que está rodando temporariamente nele.

Por isso, quando você envia localhost:3000 a um amigo, o navegador dele procura o app no computador do seu amigo. É claro que ele não está lá. Meu app ainda não saiu do meu computador. Além disso, ele desliga quando fecho o programa de desenvolvimento ou o notebook. Para virar um serviço que outras pessoas possam usar, são necessárias duas coisas: um computador ligado 24 horas por dia e um endereço que qualquer pessoa possa acessar.

Deploy é uma mudança

O deploy resolve esses dois problemas. Em poucas palavras, é mudar o app do meu computador para um servidor. “Servidor” parece algo grandioso, mas é apenas o computador de outra pessoa, conectado à internet e ligado 24 horas por dia.

Serviços como Vercel e Netlify, muito usados em vibe coding, fazem essa mudança por você. Eles realizam três tarefas.

1. Aluguel de servidor: emprestam computadores dos próprios data centers.
2. Build: convertem e comprimem o código de desenvolvimento para produção. É como empacotar a mudança.
3. Fornecimento de endereço: dão um endereço como 내앱.vercel.app, acessível por qualquer pessoa no mundo.

Vale lembrar a palavra build. O modo de desenvolvimento é tolerante e ignora muitos problemas, mas o build é um inspetor rigoroso que aponta, pouco antes do deploy, problemas silenciosos durante o desenvolvimento. Muitos casos de “funciona localmente, mas o deploy falha” são barrados nessa etapa.

Os 3 principais motivos para funcionar localmente, mas não após o deploy

Se o app se comporta de forma estranha após um deploy bem-sucedido, a causa quase certamente é uma destas três.

1º: As variáveis de ambiente não foram registradas. No episódio 2, colocamos a chave da API no arquivo .env e usamos .gitignore para que o Git ignorasse esse arquivo. Como resultado, .env não vai junto com a mudança. O app no servidor não tem a chave, então as chamadas de IA e as conexões com o banco de dados falham. Registre o conteúdo de .env no menu “Environment Variables” do dashboard do serviço de deploy e faça o deploy novamente. É o primeiro lugar a verificar quando funciona localmente, mas não após o deploy.

2º: O build falhou na verificação. O próprio deploy falha e gera logs vermelhos. Não precisa entrar em pânico: copie inteiro o log do build exibido pelo serviço de deploy e cole na IA: “Falhou com este log de build. Corrija.”

3º: O banco de dados não reconhece o novo visitante. Dependendo do serviço de banco de dados, é preciso configurar de onde as conexões são permitidas. Até agora, apenas meu computador se conectava; agora o servidor se conecta, então talvez seja necessário ajustar a lista de permissões ou as configurações de conexão. Se você fornecer os sintomas (logs) à IA, ela conseguirá restringir rapidamente a causa.

Domínio: colocar o endereço em meu nome

Após o deploy, surge um endereço como 내앱.vercel.app. Você pode usá-lo assim mesmo ou adicionar seu próprio domínio, como myapp.com. Os domínios são alugados por ano em um registrador. Conectá-lo significa registrar na lista telefônica (DNS) uma regra dizendo: “Quando procurarem este nome, encaminhe para aquele servidor”. O dashboard do serviço de deploy orienta o processo. A propagação pelas listas telefônicas do mundo pode levar de alguns minutos a um dia, então não se preocupe se não abrir imediatamente.

Rotina de verificação de 3 minutos após o deploy

Clicar no botão de deploy não é o fim. Verifique sempre estas três coisas para detectar a maioria dos problemas com antecedência.

1. Acesse diretamente o endereço publicado. Use o endereço real, não o localhost do desenvolvimento.
2. Clique uma vez em cada função principal. Priorize funções que envolvem o backend e as variáveis de ambiente, como cadastro, salvamento e chamadas de IA.
3. Se algo parecer errado, abra o menu de logs no dashboard do serviço de deploy e copie as linhas vermelhas para a IA. O “grito do servidor” mencionado no episódio 1 aparece justamente aqui.

Resumo

• localhost significa “meu computador”, então enviá-lo para outra pessoa não fará o app abrir para ela.
• O deploy muda o app para um servidor ligado 24 horas por dia e fornece um endereço público; serviços como a Vercel cuidam do processo.
• As três maiores diferenças entre o ambiente local e o publicado: variáveis de ambiente não registradas (1º), falha na verificação do build e configurações de conexão do banco. Lembrar que .env não vai junto com a mudança já resolve metade do problema.
• Conectar um domínio é registrá-lo na lista telefônica (DNS), então a propagação pode levar algum tempo.
• Após o deploy, siga a rotina de 3 minutos: abra o endereço real → clique nas funções principais → verifique os logs.

O próximo episódio aborda mensagens de erro: como ler o texto vermelho sem medo, como transmitir corretamente os erros à IA e como sair do ciclo quando a IA não consegue corrigir o mesmo bug.