Tutoriais de VPS
Next.js build Killed no VPS: heap, OOM e limites Docker (2026)
Identifique o limite real do build, diferencie V8 de OOM do host ou contêiner, reduza trabalho e valide os artefatos de produção.

Se npm run build, pnpm build ou a construção de uma imagem Docker termina mostrando apenas Killed, ou apresenta JavaScript heap out of memory, não coloque imediatamente NODE_OPTIONS em 8192 nem repita sem investigar. Heap do V8, memória do host e limite do contêiner de build são problemas diferentes. Alterar o limite errado também pode afetar o site ou o banco em produção.
Este guia para Linux preserva evidências, identifica o limite efetivo, distingue causas, ajusta o build e valida a implantação. next dev funcionando não substitui um next build concluído.
| Falha | Primeira verificação |
|---|---|
FATAL ERROR, Reached heap limit, JavaScript heap out of memory | Heap do V8, opções Node existentes e carga do projeto |
Apenas Killed ou saída 137 | Evidência OOM do kernel/contêiner; também cancelamento, encerramento manual e supervisor |
Docker indica OOM ou aumenta oom_kill do cgroup | Limite real do contêiner de build, BuildKit ou job CI |
ENOSPC, No space left on device | Disco/inodes, não heap do Node |
| TypeScript, módulo ausente ou erro de prerender | O erro específico, que pode não envolver memória |
137 costuma indicar SIGKILL, mas não é exclusivo de OOM. Sozinho, não identifica o limite ou mecanismo que encerrou o processo.
No projeto, identifique a versão instalada do Next.js:
node --version
./node_modules/.bin/next --version
./node_modules/.bin/next build --help
node -p "require('./package.json').scripts.build"
Confira se o script apenas executa next build ou inclui tipos, geração, migrações e outras tarefas. Falha na instalação de dependências não implica falha do compilador. Preserve gerenciador e lockfile; evite atualizar dependências durante o diagnóstico.
Em uma reprodução controlada, preserve log e retorno real. Este exemplo usa npm; com pnpm, use o comando original:
build_exit=0
npm run build > build-memory.log 2>&1 || build_exit=$?
tail -n 80 build-memory.log
printf 'build exit code: %s\n' "$build_exit"
Registre horário e última etapa: compilação, tipos ou geração estática. Uma pipeline de logs como tee não deve esconder o erro com seu próprio retorno bem-sucedido. Evite sobrescrever repetidamente .next no diretório da aplicação em serviço.
Consulte memória, swap, disco e processos maiores:
free -h
swapon --show
df -h
ps -eo pid,ppid,rss,comm --sort=-rss | head -n 20
Observe memória disponível, não apenas total ou usada. Um VPS de 4 GB com banco, aplicações, monitoramento e outros builds pode ter muito menos para a compilação. Uma amostra RSS também não captura todos os picos de processos paralelos.
Colete amostras durante um build controlado:
vmstat 1 10
Observe swap-in/out, CPU e espera nas amostras posteriores junto dos logs. Picos breves podem escapar; um free -h normal isolado não descarta pressão durante o build.
Leia os logs do kernel do host próximos ao horário:
sudo journalctl -k --since "20 minutes ago" --no-pager \
| grep -Ei 'out of memory|oom-kill|killed process'
Associe PID, nome e horário ao build. Ausência de saída não exclui OOM: permissões, retenção e visibilidade em contêineres influenciam. Contêineres normalmente não leem diretamente o kernel do host.
Com OOM do host confirmado, reduza builds simultâneos e evite picos do banco. Preserve serviços críticos. Builds grandes recorrentes podem exigir um ambiente maior ou CI.
RAM livre no host não garante capacidade no contêiner ou job. Para um contêiner de build identificado:
docker inspect build-container --format '{{json .State}}'
docker inspect build-container --format 'Memory={{.HostConfig.Memory}} MemorySwap={{.HostConfig.MemorySwap}}'
docker stats --no-stream build-container
Substitua build-container pelo nome/ID real. OOMKilled, saída e limites ajudam, mas um subprocesso encerrado ou contêiner removido pode não deixar um campo conclusivo.
Memória e swap no Docker têm regras próprias. free dentro do contêiner não substitui a quota real. Veja limites Docker. Desativar OOM killer ou remover todos os limites pode transferir a pressão aos serviços do host.
Se estes arquivos pertencem ao trabalho e são legíveis, registre valores antes e depois:
cat /proc/self/cgroup
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.current
cat /sys/fs/cgroup/memory.events
memory.max é o limite rígido desse cgroup. max significa ausência de limite nesse nível; ancestrais ainda podem restringir. oom_kill em memory.events conta encerramentos OOM. Compare incrementos, horários e trabalhos simultâneos; um total histórico não prova este incidente. Confirme montagem e caminho: ler o cgroup raiz do host não identifica automaticamente um builder. Consulte cgroup v2.
A aplicação iniciada por docker compose up não é o builder. Alterar seu mem_limit pode não afetar RUN npm run build durante docker build.
Identifique o builder ativo:
docker buildx ls
docker buildx inspect
Com o driver docker-container, BuildKit roda em contêiner próprio e admite opções como memory e memory-swap. Outros drivers, builders remotos e runners têm restrições diferentes. Consulte o driver Docker container. A aplicação saudável não comprova que construir a imagem evitou OOM.
--max-old-space-size controla a geração antiga do V8 em MiB. Não representa toda a memória do Node, seus filhos ou o contêiner: módulos nativos, buffers, compiladores e outros processos também consomem. Veja Node.js CLI.
Se o log confirma esgotamento do heap JavaScript e há capacidade, revise opções relacionadas em NODE_OPTIONS e teste uma mudança temporária:
NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--max-old-space-size=2048" npm run build
2048 é exemplo de sintaxe, não recomendação para VPS de 2 GB. Calcule usando quota real, limite atual, memória nativa e outros processos; o exemplo pode até ser inferior ao padrão. Resolva duplicações e conflitos primeiro. Essa forma afeta apenas um comando e preserva as outras opções da string original.
Vários filhos Node podem receber um heap próprio cada um. Limites grandes por processo podem exceder o total. Aumentar V8 não cria RAM e pode antecipar OOM do host/contêiner.
Confirme versão e bundler. A documentação atual apresenta Turbopack como padrão e --webpack como alternativa Webpack; versões antigas diferem. Use a ajuda do projeto e a documentação Turbopack.
experimental.webpackMemoryOptimizations, workers e caches Webpack pertencem ao caminho Webpack. Não resolvem automaticamente o Turbopack. Ele inclui Rust; aumentar o heap não expande a quota de memória fora do V8.
- Revise dependências grandes/duplicadas e imports desnecessários com ferramentas do bundler.
- Na geração estática, evite carregar conjuntos enormes de dados e revise volume e páginas necessárias.
- Confira plugins que acrescentem source maps, análise, geração ou compilações repetidas; remova só trabalho desnecessário.
- Pause outros builds do runner e meça a carga real, sem reintentos simultâneos.
Veja ferramentas e condições de versão no guia de memória Next.js. Diagnósticos experimentais e workers podem ter incompatibilidades; teste individualmente no builder em vez de combinar ajustes de várias versões.
Para problema de heap confirmado, o guia inclui profiling:
node --heap-prof node_modules/next/dist/bin/next build
O profile diagnostica, não reduz consumo. Chamar Next CLI diretamente pode ignorar etapas anteriores do script: preserve as necessárias e o ambiente. Examine o arquivo após conclusão correta; SIGKILL pode impedir um profile completo. Profiles e snapshots também consomem memória/disco e não são uma primeira medida adequada em host saturado.
Não publique ignoreBuildErrors, artefatos sem verificações necessárias ou saída de modo diagnóstico como correção. Se separar a checagem de tipos em CI, exija aprovação antes de implantar.
Confira swap existente com swapon --show e as restrições do VPS, sistema de arquivos e contêiner. Pode amortecer um pico ou gerar paginação prolongada que atrasa outros serviços. Swap no host não resolve a quota de um contêiner sem permissão de utilizá-la.
Não sobrescreva swap existente nem reserve gigabytes sem conferir o disco. Consulte memória/OOM no VPS. Se todo build depende de paginação intensa, amplie ou transfira o builder.
Com runtime pequeno e picos altos no build, use CI ou máquina separada. Confira:
- Commit, lockfile, versões Node/gerenciador e plataforma de destino coerentes.
- Variáveis corretas de build: valores como
NEXT_PUBLIC_não são simplesmente substituídos em runtime. - Dependências nativas compatíveis com sistema/arquitetura; artefato macOS não é automaticamente executável no Linux.
- Artefatos e estáticos completos, versão anterior preservada e rollback validado.
Veja standalone/Docker no Next.js. Copiar só .next/standalone deixa de fora public e .next/static. Build malsucedido não deve sobrescrever a versão ativa. Para outro runner, consulte GitHub Actions auto-hospedado.
Compile o mesmo commit e lockfile no ambiente real. Exija saída 0, conclusão da etapa que falhava, ausência de novos eventos OOM relacionados e margem de memória no pico para serviços compartilhados.
Teste páginas, APIs, estáticos, funções importantes e rollback. Diferencie build frio e com cache; um acerto de cache não comprova confiabilidade. Preserve erro, limites efetivos, mudanças e medições. Altere uma variável principal por vez para identificar o que ajudou.