Build do Cloudflare Pages falhou? 8 problemas comuns e como resolver

Log de build do Cloudflare Pages, com a palavra vermelha “Failed”. É a quinta falha da noite e amanhã de manhã há uma demonstração para o cliente. O log tem 500 linhas apertadas, está cheio de npm ERR! e não deixa claro por onde começar. Você tenta soluções encontradas na internet: algumas não mudam nada, outras pioram a situação.

A maioria das falhas de build no CF Pages se resume a três categorias: diferenças de ambiente, configuração de dependências e compatibilidade de versões. Quando você reconhece esses padrões, 90% dos problemas podem ser resolvidos em 10 minutos. Este artigo explica o ambiente de build do Cloudflare Pages e reúne os 8 cenários de falha mais comuns, cada um com mensagens de erro reais e etapas completas de correção, além de medidas preventivas. No fim, você terá uma linha de investigação clara.

Parte 1: entenda o ambiente de build do Cloudflare Pages

O que torna o ambiente de build do Pages diferente

Antes de investigar um problema específico, é preciso entender algo: o ambiente de build do Cloudflare Pages é essencialmente diferente do seu ambiente local. Muitas vezes a implantação no Pages falha não porque o código está errado, mas porque o ambiente mudou.

A configuração padrão é esta:

• Sistema operacional: Ubuntu (o Build System V2 usa Ubuntu 22)
• Versão do Node: 18.17.1 (sim, é antiga)
• Gerenciador de pacotes: usa npm clean-install por padrão, não npm install
• Timeout do build: limite rígido de 20 minutos
• Tamanho do Worker: limite de 10 MB

Você pode se perguntar por que a versão do Node é tão antiga. O Cloudflare prioriza estabilidade. O problema é que muitos pacotes novos já exigem Node >= 18.18.0 ou >= 20.0.0, o que provoca conflitos de versão.

Três diferenças importantes em relação ao ambiente local:

1. O sistema de arquivos diferencia maiúsculas de minúsculas: no Windows ou Mac, import Header from './header' pode funcionar mesmo que o arquivo se chame Header.js. No Linux, não: a capitalização precisa ser idêntica. Essa é uma das armadilhas mais fáceis de ignorar.
2. O ambiente de rede é diferente: localmente, você pode ter configurado um espelho do npm, como o espelho do Taobao. O ambiente de build do Pages se conecta diretamente ao registro oficial do npm e às vezes sofre timeout.
3. O comando de build padrão é diferente: antes do seu build command, o Cloudflare executa automaticamente npm clean-install --progress=false. Esse comando é muito mais rígido que npm install e falha se package-lock.json e package.json não estiverem sincronizados.

Como localizar o problema rapidamente

Agora que você sabe que os ambientes diferem, como encontrar depressa a causa real de uma falha na implantação do Pages?

Primeiro passo: entenda o log de build

O log pode ter centenas de linhas, mas você só precisa prestar atenção a alguns pontos:

# Encontre o último ERR! ou ERROR
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
# Ou procure erros do Vite/Webpack
[vite]: Rollup failed to resolve import
# E erros relacionados ao Git
fatal: unable to access repository

Na minha experiência, basta pesquisar por “ERR!”, incluindo a exclamação, e ler de 3 a 5 linhas acima. Normalmente a causa está ali. Não se deixe distrair por toda a saída anterior da instalação.

Segundo passo: salve o Deployment ID

Após cada falha de build, o Cloudflare gera um Deployment ID exclusivo. Ele aparece na barra de endereços assim:

https://dash.cloudflare.com/xxx/pages/view/your-project/a398d794-7322-4c97-96d9-40b5140a8d9b
                                                          ↑ Este é o Deployment ID

Salvar esse ID é muito importante. Se você precisar falar com o suporte do Cloudflare ou pedir ajuda na comunidade, ele permite localizar diretamente o registro do seu build.

Terceiro passo: reproduza o problema localmente

Muita gente ignora esta etapa. Tente reproduzir o problema localmente em um ambiente Linux:

# Método 1: simule o Ubuntu 22 com Docker
docker run -it ubuntu:22.04 bash
# Método 2: use rigorosamente npm ci, como no Pages
npm ci
# Método 3: selecione a versão do Node com nvm
nvm use 18.17.1

Se npm ci falhar localmente, o problema está na configuração das dependências. Se a falha aparecer ao mudar para Node 18.17.1, é uma incompatibilidade de versão.

Parte 2: 8 falhas de build comuns e como resolvê-las

Problema 1: falha na instalação de dependências

Mensagens de erro típicas:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! Fix the upstream dependency conflict, or retry this command
npm ERR! with --force or --legacy-peer-deps
ou
npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network Socket timeout

Esse é o problema que mais encontro. npm install funciona localmente, mas o Pages retorna ERESOLVE. O motivo é simples: o Cloudflare usa npm ci por padrão, e esse comando é muito rígido.

Causas:

1. O npm clean-install usado pelo Cloudflare não resolve conflitos de peer dependency automaticamente
2. package-lock.json e package.json estão fora de sincronia
3. O acesso ao registro oficial do npm sofre timeout

Soluções, em ordem de recomendação:

Solução 1: ignore a instalação padrão e use um comando personalizado

# Adicione esta variável de ambiente nas configurações do Pages
SKIP_DEPENDENCY_INSTALL=true
# Depois, altere o Build command para
npm install --legacy-peer-deps && npm run build

Essa é a opção mais direta. Você impede o Cloudflare de usar o comando padrão e assume o controle da instalação das dependências.

Solução 2: corrija package-lock.json

# Gere novamente o lockfile localmente
rm package-lock.json
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"
git push

Às vezes o lockfile ficou inconsistente e basta recriá-lo.

Solução 3: transfira o build para o GitHub Actions

Se as duas opções anteriores não funcionarem, o problema pode ser mais complexo. Use GitHub Actions com cloudflare/pages-action para controlar completamente o ambiente de build.

# .github/workflows/deploy.yml
- name: Install dependencies
  run: npm install --force
- name: Build
  run: npm run build
- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1

Prevenção: execute npm ci localmente com regularidade para confirmar que o lockfile está sincronizado.

Problema 2: versão incompatível do Node

Mensagens de erro típicas:

ERR_PNPM_UNSUPPORTED_ENGINE Unsupported environment
This package requires Node.js version ^18.18.0 or >=20.0.0
ou
The engine "node" is incompatible with this module.
Expected version ">=18.18.0". Got "18.17.1"

Esses erros quase sempre indicam que a versão do Node é antiga demais. Muitos pacotes novos, especialmente TypeScript ESLint e Next.js 14+, exigem Node >= 18.18.0, enquanto o Pages usa 18.17.1 por padrão.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Soluções — escolha uma:

Solução 1: defina uma variável de ambiente (recomendado)

Em Settings > Environment variables no Cloudflare Pages, adicione:

Nome da variável: NODE_VERSION
Valor: 20.11.0

Esse é o método oficial recomendado e é simples.

Solução 2: adicione o arquivo .node-version

Crie .node-version na raiz do projeto:

echo "20.11.0" > .node-version
git add .node-version
git commit -m "chore: specify Node version for Cloudflare Pages"

Solução 3: use o arquivo .nvmrc

É equivalente à opção anterior; apenas o nome do arquivo muda:

echo "20.11.0" > .nvmrc

Boa prática: recomendo usar a variável de ambiente e o arquivo .node-version ao mesmo tempo para manter os ambientes local e remoto consistentes. Ao escolher a versão, prefira uma versão LTS estável, como 20.11.0, em vez da mais recente.

Problema 3: timeout do build após 20 minutos

Sintoma típico:

O log mostra o build em execução por exatamente 20 minutos e, de repente, ele é encerrado sem um erro claro. Há apenas esta linha:

Build exceeded maximum time of 20 minutes

Isso é especialmente frustrante porque quase não há informação. Em geral, acontece em projetos grandes ou com dependências demais.

Causas:

• Há dependências demais e npm install sozinho leva 15 minutos
• O script de build repete muito trabalho, como gerar o site inteiro novamente a cada execução
• O cache de build não está sendo aproveitado

Soluções:

Solução 1: limpe o cache de build

Às vezes o cache vira parte do problema. Nas configurações do Pages, acesse:

Settings > Builds & deployments > Clear build cache

Depois da limpeza, execute o build novamente. Já encontrei vários casos resolvidos apenas assim.

Solução 2: analise e otimize as dependências

Use um bundle analyzer para encontrar dependências grandes:

# Projeto Next.js
npm install --save-dev @next/bundle-analyzer
# Depois, habilite em next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer({
  // Sua configuração
})

Execute ANALYZE=true npm run build e veja quais pacotes são especialmente grandes. Em um projeto, percebi que o moment.js inteiro tinha sido importado. A troca por day.js reduziu o tempo de build em 3 minutos.

Solução 3: mova parte das tarefas para a CI

Coloque operações demoradas, como typecheck e lint, no GitHub Actions e deixe o Pages responsável apenas pelo build:

// package.json
{
  "scripts": {
    "build": "next build",  // Apenas o build, sem verificações
    "build:full": "npm run typecheck && npm run lint && npm run build"  // Processo completo para a CI
  }
}

Solução 4: use pnpm

A instalação de dependências com pnpm é muito mais rápida que com npm. Altere o comando nas configurações do Pages:

Build command: pnpm install && pnpm run build

Problema 4: erro de resolução de módulos

Mensagens de erro típicas:

Module not found: Error: Can't resolve './App' in '/opt/buildhome/repo/src'
Did you mean 'App.js'?
ou
[vite]: Rollup failed to resolve import '/src/components/Snackbar'
from '/opt/buildhome/repo/src/pages/Login.jsx'

Esse erro é difícil de perceber. O projeto funciona localmente, mas no Pages o módulo não é encontrado. Em 99% dos casos, a causa é a diferença entre maiúsculas e minúsculas.

Causa:

O sistema de arquivos do Linux diferencia maiúsculas de minúsculas, enquanto Windows e macOS não fazem isso por padrão. Se você usa import App from './app' e o arquivo se chama App.js, o Windows aceita, mas o Linux falha.

Soluções:

Solução 1: corrija todos os caminhos de importação

Essa é a correção fundamental. Verifique todas as importações e confirme que a capitalização corresponde exatamente ao nome do arquivo:

// ❌ Incorreto
import Header from './header';  // O arquivo se chama Header.jsx
// ✅ Correto
import Header from './Header';

Como a verificação manual é cansativa, use uma regra do ESLint para detectar o problema:

// .eslintrc.js
module.exports = {
  rules: {
    'import/no-unresolved': 'error',  // Detecta importações que não podem ser resolvidas
  }
}

Solução 2: use aliases de caminho

Caminhos absolutos ou aliases evitam muitos problemas:

// vite.config.js
export default {
  resolve: {
    alias: {
      '@': '/src',
      '@components': '/src/components'
    }
  }
}
// Importe usando o alias
import Header from '@components/Header';  // Claro e direto

Solução 3: uma solução estranha relatada pela comunidade

Um usuário relatou uma solução absurda, mas aparentemente eficaz: renomear a pasta, fazer um commit e depois restaurar o nome. Não sei exatamente por que funciona, mas pode ser um problema de cache. Se as opções anteriores falharem, vale tentar.

Problema 5: configuração incorreta de variáveis de ambiente

Sintoma típico:

console.log(process.env.API_KEY); // undefined

Ou o build informa que uma variável de ambiente não foi encontrada.

Causa:

Muita gente confunde variáveis de ambiente de build com variáveis de runtime. Além disso, cada framework tem sua própria convenção de nomes.

O ponto essencial:

O Cloudflare Pages tem duas classes de variáveis de ambiente:

1. Variáveis de build: disponíveis durante npm run build e incorporadas ao código
2. Variáveis de runtime: disponíveis apenas nas Functions, as funções de edge

Em um site estático, feito apenas de HTML/JS, não é possível acessar variáveis de runtime; você precisa usar variáveis de build.

Soluções:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Solução 1: configure o tipo correto

Ao adicionar uma variável nas configurações do Cloudflare Pages:

• Selecione os ambientes “Production” e “Preview”
• Marque a opção “Build” se a variável for necessária durante o build

Solução 2: siga a convenção do framework

Cada framework tem seus próprios requisitos:

# Projeto Vite: o nome precisa começar com VITE_
VITE_API_KEY=xxx
# Projeto Next.js: variáveis públicas precisam começar com NEXT_PUBLIC_
NEXT_PUBLIC_API_KEY=xxx
# Projeto Nuxt: use runtimeConfig em nuxt.config.js

Solução 3: use o tipo Secret para informações sensíveis

Nas configurações do Pages, há dois tipos de variável:

• Text: o valor fica visível
• Secret: o valor fica oculto e é armazenado com criptografia

Chaves de API e senhas de banco de dados devem sempre usar o tipo Secret.

Boa prática:

1. Use um arquivo .env.local no desenvolvimento local e adicione-o a .gitignore
2. Em produção, use as configurações de variáveis de ambiente do Cloudflare Pages
3. Defina valores diferentes por ambiente: API de teste em Preview e API de produção em Production

Problema 6: integração com o Git

Sintomas típicos:

• Não é possível autorizar o acesso ao repositório
• Aparece o erro “This repository is already in use by another Pages project”
• Um push não aciona o build automático no Pages

Causa:

Normalmente há um problema na autorização do GitHub/GitLab ou uma restrição do Cloudflare foi violada, como usar o mesmo repositório em mais de uma conta.

Soluções:

Solução 1: autorize novamente o GitHub App

Nas configurações do GitHub, acesse:

Settings > Applications > Cloudflare Pages > Configure > Uninstall

Depois de desinstalar, volte ao Cloudflare Dashboard e conecte o repositório novamente para refazer a autorização.

Solução 2: verifique onde o repositório está sendo usado

Se o erro disser que o repositório já está em uso, confira se ele foi conectado a várias contas do Cloudflare. Isso não é permitido. Remova o projeto do Pages das outras contas.

Solução 3: verifique as permissões do usuário do GitHub

Você precisa ter pelo menos a permissão Maintainer no repositório para fazer a integração. Contributor não é suficiente.

Solução 4: evite caracteres especiais

Esta é uma armadilha inesperada: evite emojis e caracteres especiais na commit message. Eles podem impedir o acionamento do build. O GitHub aceita esses caracteres, mas o Cloudflare pode não interpretá-los corretamente.

Limitação conhecida: PRs de repositórios fork não acionam implantações de Preview. O Cloudflare diz que oferecerá suporte no futuro, mas atualmente não funciona.

Problema 7: falha na implantação de Functions

Sintoma típico:

O build aparece como concluído, mas a etapa final de implantação falha e o log não traz informação útil. Também pode aparecer:

Build failed: Functions bundle size exceeding limit

Causas:

• O bundle da função Worker ultrapassa o limite de 10 MB
• Os Bindings de Functions, como KV, D1 ou R2, estão configurados incorretamente
• O código usa APIs exclusivas do Node.js, incompatíveis com o ambiente de edge

Soluções:

Solução 1: analise o tamanho do bundle de Functions

Use um bundle analyzer para descobrir o que ocupa tanto espaço:

npm install --save-dev @next/bundle-analyzer

Muitas vezes uma dependência sem tree-shaking inclui a biblioteca inteira no bundle.

Solução 2: otimize a configuração do adapter do Astro/SvelteKit

Se você usa Astro ou SvelteKit, confira se o adapter do Cloudflare está configurado corretamente:

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'hybrid',  // Ou 'server'
  adapter: cloudflare({
    mode: 'directory',  // Importante: remove dados desnecessários de páginas pré-renderizadas
  }),
};

O Astro pode incluir páginas pré-renderizadas nas Functions por padrão e aumentar muito o tamanho do bundle. Definir mode: 'directory' resolve o problema.

Solução 3: verifique os Bindings

Nas configurações do Pages, acesse:

Settings > Functions > Bindings

Confirme que todos os recursos KV, D1 e R2 usados no código estão configurados corretamente.

Solução 4: evite APIs exclusivas do Node.js

Cloudflare Workers usa o ambiente V8, não o Node.js completo. Estas APIs não são compatíveis:

• fs, o sistema de arquivos
• path, com suporte apenas parcial
• child_process
• net / http; use fetch

Se forem indispensáveis, considere mover essa lógica para a etapa de build.

Problema 8: cache e domínio personalizado

Sintomas típicos:

• A implantação foi concluída, mas o site ainda mostra o conteúdo antigo
• O domínio personalizado retorna 404, enquanto o domínio .pages.dev funciona
• A página inicial mostra 404 Not Found

Causas:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

• As Page Rules do Cloudflare interferem no mecanismo de cache do Pages
• O DNS do domínio personalizado está configurado incorretamente
• O arquivo index.html não existe

Soluções:

Solução 1: remova a Page Rule Cache Everything

Se o domínio personalizado está como Proxied, com a nuvem laranja, as configurações da Zone afetam o Pages. Verifique:

Rules > Page Rules

Se houver uma regra “Cache Everything”, remova-a. O Pages tem seu próprio mecanismo de cache e não precisa dessa Page Rule.

Solução 2: altere o domínio personalizado para DNS Only

Se a opção anterior não funcionar, mude o registro DNS para a nuvem cinza, ou DNS Only:

DNS > Records > Clique no seu registro > Altere para DNS Only

Assim a solicitação deixa de passar pelo proxy do Cloudflare e se conecta diretamente ao Pages.

Solução 3: confirme que index.html existe

Se a raiz, como yourdomain.com/, retorna 404, confira se o diretório de saída do build contém index.html. Muitos frameworks geram dist/index.html por padrão; confirme que “Build output directory” aponta para o local correto.

Solução 4: limpe o cache manualmente

Se o conteúdo novo não aparece por causa do cache:

Caching > Configuration > Purge Everything

Isso limpa todo o cache da Zone, então use com cuidado.

Parte 3: boas práticas preventivas

Boas práticas de configuração do build

É melhor preparar a configuração desde o início do que esperar um problema aparecer. Estas são as práticas que recomendo:

1. Defina explicitamente a versão do Node

Não dependa da versão padrão:

# Arquivo .node-version
20.11.0
# Defina também nas variáveis de ambiente do Cloudflare Pages
NODE_VERSION=20.11.0

2. Use comandos de build diferentes para cada branch

Use a variável de ambiente CF_PAGES_BRANCH:

// package.json
{
  "scripts": {
    "build": "node scripts/build.js",
    "build:production": "next build",
    "build:preview": "next build && next export"
  }
}

// scripts/build.js
const branch = process.env.CF_PAGES_BRANCH || 'main';
const command = branch === 'main' ? 'build:production' : 'build:preview';
// Execute o comando correspondente

3. Em um monorepo, defina o diretório raiz correto

Se você usa pnpm workspace ou Turborepo, não se esqueça de configurar Root directory no Pages:

Root directory: apps/web
Build command: pnpm run build

Monitoramento contínuo e técnicas de depuração

1. Prepare um ambiente local de depuração

Use Docker para simular o ambiente do Pages:

# Dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y nodejs npm
RUN node -v  # Deve estar próximo de 18.17.1
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

2. Consulte o Cloudflare Status

Às vezes a falha de build está no próprio serviço do Cloudflare. Ao encontrar um erro estranho, consulte:

https://www.cloudflarestatus.com/

Se o serviço do Pages estiver com problemas, espere a correção em vez de alterar o projeto ao acaso.

3. Quando entrar em contato com o Cloudflare Support

Procure o suporte se você:

• Tentou todas as soluções sem sucesso
• Suspeita de um bug na plataforma do Cloudflare
• Precisa aumentar os limites de build, algo que usuários pagos podem solicitar

Inclua o Deployment ID e o log de erro completo.

Conclusão

Apesar da quantidade de detalhes, as falhas de build no CF Pages se resumem a poucas categorias. Em 90% dos casos, trata-se de uma diferença de ambiente, como versão do Node ou capitalização do sistema de arquivos; uma configuração de dependências, como package-lock.json ou peer dependency; ou uma interpretação incorreta do funcionamento do Pages, como variáveis de ambiente e cache.

Uma investigação sistemática faz toda a diferença:

1. Leia o log de build e encontre a mensagem de erro real
2. Classifique o problema: dependências, versão, caminho ou configuração
3. Reproduza a falha no ambiente local
4. Aplique a solução correspondente
5. Configure medidas preventivas para não repetir o problema

Salve este artigo como manual de diagnóstico. Na próxima falha de build, siga essa sequência e há uma boa chance de resolvê-la em 10 minutos. Quando o “✓ Deployed” verde aparecer, o alívio será enorme.

Encontrou outro problema no Cloudflare Pages? Compartilhe nos comentários; sua experiência pode ajudar mais pessoas.