Corrigir Assets do Laravel Vite Carregando do Servidor de Desenvolvimento em Produção – Guia Completo
Fazer deploy de uma aplicação Laravel com Vite pode às vezes gerar problemas inesperados. Uma das dores de cabeça mais comuns é quando seu site em produção tenta carregar assets de localhost:5173, em vez dos arquivos compilados de /public/build.
Se seu site está quebrando em produção por causa disso, não se preocupe — este guia fornece uma correção real testada em múltiplos deployments. No final, você não apenas resolverá o problema, mas também configurará um fluxo de trabalho confiável que garante que isso nunca aconteça novamente.
Entendendo o Problema
Ao trabalhar localmente, o Laravel com Vite usa um servidor de substituição de módulos a quente (HMR) rodando em http://localhost:5173. Isso torna o desenvolvimento rápido e eficiente, com atualizações instantâneas no navegador.
Mas aqui está o problema:
- Em produção, seu servidor não roda este servidor de desenvolvimento.
- Em vez disso, ele deveria servir os assets pré-compilados dentro de
/public/build. - Se você vê referências como esta em produção:
<link rel="stylesheet" href="http://localhost:5173/resources/css/app.css">
em vez de:
<link rel="stylesheet" href="https://yourdomain.com/build/assets/app-xxxx.css">
…significa que o Laravel ainda está tentando usar o servidor de desenvolvimento hot reload.
O culpado?
Um arquivo public/hot residual que diz ao Laravel para continuar usando localhost:5173.
Correção Rápida para Produção
Execute estes comandos no seu servidor de produção:
cd /home/username/public_html
rm -f public/hot
php artisan config:clear
php artisan cache:clear
php artisan view:clear
✅ Isso remove o arquivo hot e limpa os caches do Laravel.
✅ Feito isso, recarregue seu site — ele deve usar imediatamente os assets compilados.
Correção Permanente com Fluxo de Trabalho de Deploy
Corrigir manualmente serve para uma vez. Mas se você faz deploy frequentemente, vai querer automação.
Passo 1 – Atualizar .gitignore
Certifique-se de que public/build não esteja ignorado, pois você precisa dos assets compilados em produção:
# Manter pasta build no repo
!public/build
Passo 2 – Sempre Compilar Localmente
Como seu servidor de produção não tem npm, compile assets antes de fazer push:
npm run build
git add .
git commit -m "Build assets for production"
git push origin main
Passo 3 – GitHub Actions para Deploy
Atualize seu workflow do GitHub Actions para:
- Fazer deploy do código
- Remover
public/hot - Limpar caches
Exemplo de trecho do workflow:
- name: Remove hot file
run: rm -f public/hot
- name: Clear Laravel caches
run: |
php artisan config:clear
php artisan cache:clear
php artisan view:clear
Melhores Práticas – Fazer e Não Fazer
✅ Fazer:
- Executar
npm run buildantes de fazer deploy - Commitar
/public/buildno seu repositório - Automatizar a limpeza de cache
❌ Não fazer:
- Executar
npm run devem produção - Commitar
public/hot - Esquecer de compilar antes de fazer push
Fluxo de Trabalho de Deploy Típico
Assim deve ser seu ciclo desenvolvimento → produção:
# Desenvolvimento local
npm run dev
# Antes do deploy
npm run build
git add .
git commit -m "Production build"
git push origin main
Seu pipeline CI/CD (GitHub Actions, Forge, etc.) cuida do resto.
Resultados para os Clientes
Ao corrigir este problema, os clientes obtêm:
- Um site de produção totalmente funcional sem CSS/JS quebrados.
- Confiança de que os deploys não vão quebrar novamente.
- Fluxo de trabalho otimizado para projetos Laravel + Vite.
- Menos tempo de inatividade, que impacta diretamente a experiência do usuário e conversões.
Isso constrói confiança na sua expertise e garante clientes recorrentes.
Perguntas Frequentes
P1: Por que o Laravel carrega assets de localhost:5173 em produção?
Porque o arquivo public/hot ainda existe, fazendo o Laravel pensar que deve usar o servidor de desenvolvimento.
P2: Posso corrigir isso sem GitHub Actions?
Sim. Delete manualmente public/hot e recompile assets localmente antes de fazer deploy.
P3: Preciso commitar /public/build?
Sim, pois seu servidor de produção pode não ter Node/NPM.
P4: E se eu usar Laravel Forge ou Vapor?
O mesmo processo se aplica — sempre compile assets localmente e commite /public/build.
P5: Devo alguma vez executar npm run dev em produção?
Não, é apenas para desenvolvimento local. Use npm run build para produção.
P6: Como sei se está corrigido?
Verifique o código-fonte HTML de produção. Se as URLs de assets carregam de /build/assets/… em vez de localhost:5173, está resolvido!
Conclusão
Corrigir os assets do Laravel Vite carregando do servidor de desenvolvimento em produção é simples uma vez que você conhece a causa raiz — o arquivo public/hot. Com a correção rápida e um fluxo de trabalho de deploy robusto, você garantirá que os deploys de produção sempre carreguem os assets compilados corretos.
Isso não apenas resolve o problema imediato, mas também dá a você um processo à prova de futuro que constrói confiança com clientes e mantém os ambientes de produção estáveis.
