Funciona local mas falha no deploy — como resolver (Vercel e Netlify)

O sintoma

Funciona perfeitamente com npm run dev na sua máquina, mas assim que você sobe para o Vercel ou Netlify aparece uma tela branca, um erro de build "Module not found" ou dados que nunca carregam. Esse é o problema mais comum na primeira vez que você faz deploy de um app feito com vibe coding — e a causa quase sempre é uma destas cinco coisas.

A razão de fundo é simples: o seu PC e o servidor de deploy são dois "ambientes" diferentes. As configurações, arquivos e URLs que só existiam no seu computador não estão no servidor. Percorra em ordem as cinco verificações abaixo e você resolve a maioria dos casos.

1. Você não cadastrou as variáveis de ambiente na plataforma de deploy — a mais comum

O arquivo .env do seu PC vive só no seu PC. Normalmente ele não vai para o git, então o Vercel e o Netlify nem sabem que ele existe. Isso significa que valores como chaves de API e URLs de banco de dados ficam vazios em produção, e o app quebra.

Correção — Vercel:

1. Painel do Vercel → abra o seu projeto
2. Menu superior Settings → barra lateral esquerda Environment Variables
3. Digite a Key (ex.: VITE_SUPABASE_URL) e o Value → marque Production, Preview e Development → Save
4. Vá até a aba Deployments → ⋯ ao lado do deploy mais recente → Redeploy

> Importante: o Vercel aplica as mudanças de variáveis de ambiente apenas aos deploys *novos*, nunca aos existentes. Depois de adicionar um valor, você precisa refazer o deploy para ele valer.

Correção — Netlify:

1. Painel do Netlify → abra o seu site
2. Site configuration → Environment variables → Add a variable
3. Digite Key/Value → Save
4. Aba Deploys → Trigger deploy → Clear cache and deploy site

Atenção: valores usados no navegador precisam de um prefixo específico

As variáveis de ambiente lidas pelo código do frontend (o navegador) só chegam à página se tiverem o prefixo certo. Sem ele, o valor volta como undefined.

Tudo que tiver esses prefixos fica exposto no bundle do navegador, então nunca coloque um segredo de verdade (como a senha de um banco de dados) atrás de um deles.

2. Você mudou uma variável de ambiente mas não refez o deploy

Os valores das variáveis de ambiente são embutidos no código na hora do build e congelam ali. Next.js, Vite e Create React App inserem os valores durante o build. Por isso, mesmo depois de editar um valor no painel, o valor antigo continua até você reconstruir.

Correção: Depois de mudar um valor, clique em Redeploy (Vercel) / Trigger deploy (Netlify) mais uma vez para forçar um build novo.

3. As maiúsculas e minúsculas de um nome de arquivo não batem — "Module not found"

macOS e Windows tratam Button.tsx e button.tsx como o mesmo arquivo (não diferenciam maiúsculas). Mas o Vercel e o Netlify fazem o build no Linux, que diferencia maiúsculas de minúsculas de forma rígida. Então, se o arquivo real é Button.tsx mas o seu import usa minúscula, passa no local e falha no deploy com "Module not found".

Correção: Faça o caminho do import bater exatamente com o nome real do arquivo, letra por letra — os nomes de pasta também.

// Real file: src/components/Header.tsx

import Header from './components/Header'  // OK
import Header from './components/header'  // FAILS on deploy: Module not found

4. Você deixou uma URL de API com localhost fixa no código

Se você escreve uma URL como http://localhost:3000 direto no código, funciona no local porque esse é o seu próprio servidor. Mas no site publicado esse endereço aponta para "o próprio computador do visitante", então nada volta.

Correção: Mova a URL para uma variável de ambiente e cadastre o endereço real do deploy usando o método 1.

// Wrong — a local address baked into the code
fetch('http://localhost:3000/api/users')

// Fixed — pull the address from an env var (Vite example)
fetch(`${import.meta.env.VITE_API_URL}/api/users`)

5. No local roda dev, no deploy roda build — erros que só aparecem no build

npm run dev é um servidor de desenvolvimento e releva muitos problemas. No deploy roda npm run build (um build de produção), que é bem mais rígido com erros de tipo e de import.

Correção: Antes de subir, rode exatamente o mesmo build no local para pegar os problemas com antecedência.

npm run build

Qualquer erro que aparecer aqui é o motivo do seu deploy falhar. Resolva esses erros no local e só então suba o código.

Checklist final

• Você adicionou todos os valores do .env também no Vercel/Netlify?
• As variáveis usadas no navegador têm o prefixo NEXT_PUBLIC_ / VITE_ / REACT_APP_?
• Você refez o deploy depois de adicionar ou mudar um valor?
• Os caminhos dos imports batem com os nomes reais dos arquivos, incluindo maiúsculas/minúsculas?
• Não há nenhuma URL localhost fixa no código?
• O npm run build termina sem erros na sua máquina?

Acertando os seis, o problema de "funciona local, quebra no deploy" quase sempre desaparece.