Guia completo para implantar blogs estáticos no Cloudflare Pages: configure 5 frameworks sem dor de cabeça

Você terminou o primeiro artigo do blog e clicou no botão de implantação. Três minutos depois, o Cloudflare Pages informou que a implantação havia sido concluída. Você copiou o link, abriu no navegador e encontrou uma página em branco, enquanto o console do F12 mostrava vários erros 404.
Na minha primeira implantação de um blog Astro, foi exatamente assim: encontrei respostas de todo tipo no Google, tentei resolver por três ou quatro horas e, no fim, descobri que tinha informado public como diretório de saída, embora o padrão do Astro seja dist.
90% das falhas de implantação acontecem porque duas configurações não foram entendidas: o comando de build e o diretório de saída. Este artigo mostra os valores corretos para cinco frameworks populares — Astro, Hugo, Hexo, Gatsby e Eleventy — no Cloudflare Pages e explica como investigar rapidamente uma “página em branco” ou uma “falha no build”. Seguindo o processo, você pode sair do repositório Git e colocar o site no ar em 10 minutos.
Por que escolher o Cloudflare Pages? E o que mudou na plataforma em 2025
Primeiro, vale explicar por que recomendo o Cloudflare Pages para implantar blogs estáticos.
É gratuito e realmente rápido. O Cloudflare tem mais de 300 data centers espalhados pelo mundo, e seu blog é distribuído automaticamente entre esses pontos. Assim, o carregamento é rápido independentemente da localização do leitor. Já usei GitHub Pages e Vercel, mas a velocidade do Cloudflare Pages foi mais estável, principalmente para acessos a partir da China. Além disso, ele é totalmente gratuito, sem limite de tráfego nem de quantidade de builds.
A implantação automática pelo Git economiza muito trabalho. Basta conectar um repositório do GitHub ou GitLab. Depois disso, a cada git push, o Cloudflare compila e implanta o projeto automaticamente. Ele também pode gerar um link de visualização para cada Pull Request, facilitando a conferência antes do merge. Isso é especialmente útil para equipes.
SSL gratuito e domínio personalizado já vêm incluídos. Você não precisa lidar com a configuração de certificados, e associar seu próprio domínio também é simples. A propagação do DNS costuma levar apenas alguns minutos.
Mas há algo que preciso avisar desde o início: em abril de 2025, o Cloudflare ajustou sua estratégia de plataforma e passou a priorizar oficialmente o Cloudflare Workers. O Pages praticamente entrou em “modo de manutenção” e não deve receber grandes novidades.
Para a implantação de um blog estático, porém, essa mudança tem pouco impacto. O Pages continua estável e oferece tudo o que esse tipo de projeto precisa. Se você quer apenas criar um blog ou site de documentação, sem renderização complexa no servidor nem computação de borda, o Pages continua sendo uma excelente opção. O Workers é mais adequado a projetos que precisam de recursos dinâmicos, rotas de API ou computação de borda avançada.
Em resumo, você pode usar o Pages com tranquilidade para implantar um blog totalmente estático. Se precisar adicionar recursos de servidor no futuro, poderá considerar uma migração para o Workers.
Configurações padrão de 5 frameworks populares
Agora chegamos à parte principal. Reuni as configurações corretas de cinco frameworks populares para blogs estáticos. Basta preencher os campos conforme a tabela.
Tabela de configuração rápida
| Framework | Comando de build | Diretório de saída | Observação importante |
|---|---|---|---|
| Astro | npm run build | dist | O padrão é suficiente; SSR exige configuração adicional |
| Hugo | hugo | public | É obrigatório definir a variável de ambiente HUGO_VERSION |
| Hexo | hexo generate | public | Alguns temas exigem a definição de NODE_VERSION |
| Gatsby | gatsby build | public | É o mais simples e raramente apresenta problemas |
| Eleventy | npx @11ty/eleventy | _site | Repare no sublinhado no início |
| Next.js | npx opennextjs-cloudflare | .worker-next | Esta é a nova solução de 2025; ignore tutoriais antigos |
Uma recomendação: salve esta tabela. Testei pessoalmente cada uma dessas configurações. A seguir, explico os cuidados específicos de cada framework.
Configuração do Astro
O Astro é atualmente meu framework favorito para blogs estáticos. Ele tem bom desempenho e oferece uma experiência agradável de desenvolvimento.
Configuração padrão:
- Comando de build:
npm run buildou diretamenteastro build - Diretório de saída:
dist
Se você usa um site totalmente estático, com SSG, a configuração padrão é suficiente. Mas há uma armadilha: para usar renderização no servidor, ou SSR, primeiro é necessário instalar o adaptador @astrojs/cloudflare e adicionar o seguinte ao arquivo astro.config.mjs:
import cloudflare from '@astrojs/cloudflare';
export default {
output: 'server',
adapter: cloudflare()
};
Se quiser personalizar o diretório de saída, mudando-o para build, por exemplo, você pode fazer isso no arquivo de configuração:
export default {
outDir: 'build'
};
Ainda assim, recomendo não alterar o valor e manter o padrão dist. Isso evita confusão para outras pessoas que colaborarem no projeto no futuro.
Configuração do Hugo, onde mais ocorrem erros
O Hugo é o que mais tem armadilhas. Na primeira vez em que implantei um blog Hugo, passei uma noite inteira tentando entender o problema.
Configuração padrão:
- Comando de build:
hugoouhugo -b $CF_PAGES_URL - Diretório de saída:
public - Variável de ambiente obrigatória:
HUGO_VERSION = 0.143.1, ou a versão necessária
Este é o ponto principal: por padrão, o Cloudflare Pages usa o Hugo 0.54, uma versão antiga de 2019. Hoje, a maioria dos temas Hugo exige a versão 0.80 ou superior, e alguns pedem 0.120 ou mais. Sem definir HUGO_VERSION manualmente, a implantação falhará.
Como definir a variável de ambiente? A seção sobre o processo prático explica em detalhes. Por enquanto, lembre-se de abrir as configurações do projeto no Cloudflare Pages, acessar Settings > Environment variables e adicionar esta variável:
- Nome da variável:
HUGO_VERSION - Valor:
0.143.1; use o número exato da versão, como0.143.1, e não apenas0.143
Há ainda um pequeno detalhe na configuração de baseURL do Hugo. Se você usa o domínio .pages.dev fornecido pelo Cloudflare, e não seu próprio domínio, o comando de build deve ser:
hugo -b $CF_PAGES_URL
$CF_PAGES_URL é uma variável de ambiente fornecida automaticamente pelo Cloudflare. Ela recebe o domínio correto de acordo com o ambiente de implantação. Assim, links internos, RSS e sitemap funcionarão corretamente.
Configuração do Hexo
O Hexo é um framework tradicional para blogs estáticos, e sua configuração é relativamente simples.
Configuração padrão:
- Comando de build:
hexo generate; a forma abreviadahexo gtambém funciona - Diretório de saída:
public
Em geral, o Hexo não apresenta grandes problemas, mas alguns temas ou plugins exigem versões específicas do Node.js. Se o build falhar, tente definir a variável de ambiente NODE_VERSION:
- Nome da variável:
NODE_VERSION - Valor:
14.3ou18.17.0, conforme a versão usada pelo projeto
Você pode executar node -v localmente para conferir sua versão e definir o mesmo valor no Cloudflare Pages.
Configuração do Gatsby
O Gatsby é o mais tranquilo e raramente apresenta problemas.
Configuração padrão:
- Comando de build:
gatsby build - Diretório de saída:
public
É só isso. Não há nenhuma configuração adicional: basta preencher esses valores. Já ajudei amigos a implantar vários blogs Gatsby e nunca tivemos problemas.
Configuração do Eleventy
O Eleventy, ou 11ty, é um gerador leve de sites estáticos e também tem configuração simples.
Configuração padrão:
- Comando de build:
npx @11ty/eleventy - Diretório de saída:
_site; repare no sublinhado no início
Preste atenção ao diretório de saída _site, que começa com um sublinhado. Não informe site por engano, pois o Cloudflare não encontrará os arquivos.
Se quiser personalizar o diretório de saída, crie um arquivo .eleventy.js na raiz do projeto e adicione:
module.exports = function(eleventyConfig) {
return {
dir: {
output: "public"
}
};
};
Configuração do Next.js e a mudança de 2025
Se você usa Next.js para criar seu blog, precisa conhecer uma mudança importante de 2025.
Configuração padrão, segundo a nova solução de 2025:
- Comando de build:
npx opennextjs-cloudflare - Diretório de saída:
.worker-next
Importante: o pacote @cloudflare/next-on-pages, usado em muitos tutoriais antigos, foi descontinuado. Não o utilize. Agora, o Cloudflare recomenda o novo adaptador @opennextjs/cloudflare.
Se um tutorial antigo ainda falar sobre next-on-pages, ignore essa parte, pois ela está desatualizada. A configuração da nova solução é:
- Instale a dependência:
npm install @opennextjs/cloudflare - Informe o comando de build:
npx opennextjs-cloudflare - Informe o diretório de saída:
.worker-next
Sinceramente, se você só quer criar um blog estático, não recomendo muito o Next.js. Ele é mais adequado para aplicações que precisam de recursos dinâmicos. Para conteúdo totalmente estático, Astro ou Hugo são opções mais leves e rápidas.
Na prática: processo completo do repositório Git ao site no ar
Agora que você conhece as configurações, vamos implantar o projeto do zero. Todo o processo leva cerca de 10 minutos.
Preparação
Antes de começar, confirme estes três pontos:
- O código já foi enviado ao GitHub ou GitLab — abra a página do repositório e confirme que o código mais recente está lá
- O projeto tem um package.json, caso seja um projeto Node.js — confira se todas as dependências estão declaradas nele e não deixe pacotes instalados apenas localmente
- Verifique o .gitignore — confirme que diretórios como
node_modules,distepublicestão no .gitignore e não envie os artefatos de build ao repositório
Já vi um amigo enviar até node_modules ao Git, o que causou vários conflitos durante a implantação. Vale a pena conferir o .gitignore para evitar esse tipo de problema.
Etapas detalhadas da implantação
Etapa 1: entre no Cloudflare e acesse Pages
Abra dash.cloudflare.com e faça login na sua conta. Se ainda não tiver uma, você pode criá-la gratuitamente.
No menu lateral, encontre Workers & Pages, abra essa opção e clique no botão Create application no canto superior direito.
Etapa 2: escolha Connect to Git
Você verá duas opções:
- Connect to Git — implantação automática a partir do GitHub/GitLab; esta é a opção que usaremos
- Direct Upload — upload manual de arquivos; não é recomendado porque exige um novo envio a cada alteração
Selecione Connect to Git e depois GitHub ou GitLab.
Etapa 3: autorize o acesso
Na primeira conexão, será preciso autorizar o Cloudflare a acessar seu repositório Git. Clique em Sign in para ir à página de autorização do GitHub/GitLab.
Sobre as permissões: se não quiser dar ao Cloudflare acesso a todos os repositórios, selecione Only select repositories e autorize apenas os repositórios necessários.
Após a autorização, você voltará à página do Cloudflare.
Etapa 4: escolha o repositório que será implantado
Encontre o projeto do seu blog na lista de repositórios e clique nele.
Se o repositório não aparecer, clique no botão de atualização no canto superior direito ou volte à etapa anterior e refaça a autorização.
Etapa 5: configure o build, a parte mais importante
Este é o momento mais importante da configuração, portanto não preencha os campos incorretamente.
- Project name: o nome do projeto, que fará parte do seu domínio
.pages.dev. Por exemplo, se você informarmy-blog, o domínio serámy-blog.pages.dev. - Production branch: a branch de produção, normalmente
mainoumaster. - Framework preset: a predefinição do framework. Você pode escolher o framework usado, como Astro ou Hugo, ou selecionar None.
Agora vem o ponto principal: Build settings
Preencha os valores corretos de acordo com o framework, seguindo a tabela anterior:
- Build command, o comando de build
- Astro:
npm run build - Hugo:
hugoouhugo -b $CF_PAGES_URL - Hexo:
hexo generate - Gatsby:
gatsby build - Eleventy:
npx @11ty/eleventy - Next.js:
npx opennextjs-cloudflare
- Astro:
- Build output directory, o diretório de saída
- Astro:
dist - Hugo:
public - Hexo:
public - Gatsby:
public - Eleventy:
_site - Next.js:
.worker-next
- Astro:
Ao escolher um Framework preset, o Cloudflare preencherá alguns valores padrão automaticamente. Esses valores nem sempre estão corretos, então vale a pena conferi-los manualmente.
Etapa 6: defina as variáveis de ambiente, se necessário
Role a página até Environment variables (advanced) e clique em Add variable.
Adicione as variáveis necessárias para o seu framework:
- Projetos Hugo precisam desta variável:
- Variable name:
HUGO_VERSION - Value:
0.143.1, ou a versão necessária, sempre com os três componentes da versão
- Variable name:
- Projetos Hexo, se necessário:
- Variable name:
NODE_VERSION - Value:
14.3ou18.17.0, conforme a versão usada localmente
- Variable name:
Depois de preencher as variáveis de ambiente, a configuração estará concluída.
Etapa 7: salve e implante
Revise toda a configuração e, quando confirmar que está correta, clique em Save and Deploy no fim da página.
O Cloudflare começará a compilar o projeto. Você verá uma página com o log de build e o progresso em tempo real. Em geral, o build termina em 1 a 3 minutos.
Etapa 8: veja o resultado da implantação
Após o build terminar com sucesso, a página exibirá “Success! Your site is live!”. Logo abaixo haverá um link no formato nome-do-projeto.pages.dev.
Abra o link e, se tudo estiver correto, você verá seu blog.
Como configurar variáveis de ambiente em detalhes
Você pode definir as variáveis de ambiente durante a implantação. Se não fizer isso nesse momento ou precisar alterá-las depois, siga estas etapas:
- Abra seu projeto no Cloudflare Pages
- Clique na aba Settings na parte superior
- No menu lateral, selecione Environment variables
- Clique em Add variable
- Informe o nome e o valor da variável e clique em Save
Variáveis de ambiente comuns:
HUGO_VERSION: número da versão do Hugo, como0.143.1NODE_VERSION: número da versão do Node.js, como18.17.0CF_PAGES_URL: fornecida automaticamente pelo Cloudflare; não precisa ser definida manualmente e é usada como baseURL
Aviso importante: depois de alterar variáveis de ambiente, é necessário implantar novamente para que a mudança tenha efeito. Abra a aba Deployments, encontre a implantação mais recente, clique nos três pontos à direita e escolha Retry deployment.
Implantações de visualização, ou Preview Deployments
Há um recurso particularmente útil: sempre que você cria um Pull Request, o Cloudflare gera automaticamente um link de visualização.
Por exemplo, se você criar um PR no GitHub antes de integrar um novo artigo, o Cloudflare compilará automaticamente o código desse PR e gerará um endereço de visualização independente. Assim, você pode conferir o resultado antes de fazer o merge na branch principal.
Isso é especialmente útil para equipes, pois permite que várias pessoas escrevam e revisem o conteúdo umas das outras.
O que fazer quando algo dá errado
É normal encontrar problemas durante a implantação. Não se preocupe. Reuni aqui os três erros mais comuns e as formas de investigá-los, cobrindo cerca de 95% dos casos.
Problema 1: falha no build, ou Building Failed
Sintomas: a implantação fica presa no estado “Building” e, depois de algum tempo, mostra “Build failed”. A página exibe um ícone vermelho de erro.
Este é o problema que mais encontro. Antes de tentar implantar novamente, consulte o log de erro.
Como investigar:
- Consulte o log de build
- Na página da implantação que falhou, clique em View build log ou Deployment details
- Role até o final e procure a mensagem de erro em vermelho
- Observe principalmente as últimas linhas, que normalmente indicam a causa do problema
- Confira se o comando de build está correto
- Volte a Settings > Build & deployments
- Verifique se Build command foi preenchido conforme a tabela de configurações
- Erro comum: escrever
npm buildem vez denpm run build, omitindorun
- Confira se todas as dependências estão presentes
- Se o log mostrar “Cannot find module” ou “Command not found”
- Isso indica uma dependência ausente; verifique se o pacote está no package.json
- Talvez ele tenha sido instalado localmente, mas não adicionado ao package.json;
npm install --savefaz isso automaticamente
- Confirme a versão do framework
- Projetos Hugo: 99% das falhas de build acontecem porque HUGO_VERSION não foi definida
- O log pode mostrar “Theme requires Hugo Extended version”
- Acesse Settings > Environment variables e adicione
HUGO_VERSION = 0.143.1
- Projetos Hexo: a versão do Node.js pode ser incompatível
- Defina
NODE_VERSION = 18.17.0, ou a versão usada localmente
- Defina
- Projetos Hugo: 99% das falhas de build acontecem porque HUGO_VERSION não foi definida
Caso real: ao ajudar um amigo a implantar um blog Hugo, o log mostrou “Hugo version 0.54.0 does not support this theme”. Ao verificar a configuração, descobrimos que a versão realmente era antiga demais. Adicionamos a variável de ambiente HUGO_VERSION = 0.120.0, implantamos novamente e o build passou imediatamente.
Problema 2: página em branco, o caso mais comum
Sintomas: a implantação termina com sucesso, mas o site abre apenas uma página em branco. Ao abrir o console com F12, podem aparecer vários erros 404.
Já encontrei esse problema muitas vezes, e em 90% dos casos o diretório de saída estava incorreto.
Como investigar:
- Abra as ferramentas de desenvolvedor do navegador com F12
- Consulte a aba Console para ver se há erros
- Abra a aba Network, recarregue a página e veja quais recursos retornam 404
- Consulte a aba Sources para verificar se a estrutura de arquivos está correta
- Confira a configuração do diretório de saída
- Esta é a causa mais comum, presente em 90% dos casos
- Volte a Settings > Build & deployments no Cloudflare Pages
- Verifique se Build output directory está correto
- Erros comuns:
- Informar
publicem vez dedistem projetos Astro - Informar
distem vez depublicem projetos Hugo - Informar
siteem vez de_siteem projetos Eleventy, esquecendo o sublinhado
- Informar
- Confira a configuração de baseURL ou publicPath
- Ao implantar em um subcaminho, como
example.com/blog, talvez seja necessário configurar baseURL - Projetos Hugo: mude o comando de build para
hugo -b $CF_PAGES_URL - Projetos Astro: defina
base: '/blog'no arquivoastro.config.mjs - Projetos Vue/React: talvez seja necessário definir
publicPath: './', usando um caminho relativo
- Ao implantar em um subcaminho, como
- Confira o modo de roteamento em aplicações SPA
- Se você usa o modo history do Vue Router ou React Router
- A página pode retornar 404 ao ser recarregada, pois o servidor não encontra o arquivo correspondente
- Soluções:
- Use o modo hash, que adiciona
#à URL - Ou adicione à raiz do projeto um arquivo
_redirectscom este conteúdo:/* /index.html 200
- Use o modo hash, que adiciona
Caso real: na última vez em que implantei meu próprio blog Astro, a página ficou em branco. Depois de procurar por bastante tempo, percebi que tinha informado public como diretório de saída. Bastou mudar para dist. Às vezes, o problema é realmente simples assim.
Problema 3: falha ao carregar estilos ou recursos
Sintomas: a página aparece, mas o layout está completamente desorganizado e as imagens não carregam, como se não houvesse CSS.
Como investigar:
- Abra as ferramentas de desenvolvedor e consulte a aba Network
- Veja se arquivos CSS, JavaScript e imagens estão retornando 404
- Confira se os caminhos solicitados para esses recursos estão corretos
- Confira os caminhos usados para os recursos
- Problemas com caminhos relativos e absolutos
- Se o HTML usa
/assets/style.css, um caminho absoluto, mas o site foi implantado em um subcaminho, o arquivo não será encontrado - Solução: use o mecanismo de recursos oferecido pelo framework
- Astro: importe os recursos com
import - Hugo: use
.RelPermalinkouabsURL - Hexo: use a função auxiliar
url_for()
- Astro: importe os recursos com
- Confira a configuração da CDN
- Se você usa uma CDN externa, como jsDelivr ou cdnjs
- Confirme que o link da CDN não está bloqueado
- Você pode substituí-la por uma CDN chinesa, como BootCDN
Caso real: ajudei um amigo a implantar um blog Hexo. A página aparecia, mas estava sem estilos. Ao inspecionar o código, vimos que o caminho do CSS era /css/style.css, enquanto o arquivo real estava em /blog/css/style.css. O problema era que o blog tinha sido implantado em um subcaminho, mas os valores de url e root no arquivo de configuração do Hexo não tinham sido ajustados. Depois de alterar _config.yml, adicionar root: /blog/ e gerar o site novamente, tudo funcionou.
Checklist de diagnóstico rápido
Quando algo der errado, confira estes itens na ordem indicada. Isso costuma resolver o problema:
- ✓ Consulte o log de build e encontre a mensagem de erro
- ✓ Confirme se o comando de build está correto, comparando-o com a tabela
- ✓ Confirme se o diretório de saída está correto, comparando-o com a tabela
- ✓ Confira se as variáveis de ambiente foram definidas; projetos Hugo exigem HUGO_VERSION
- ✓ Abra o F12 do navegador e consulte o console e as solicitações de rede
- ✓ Confira o .gitignore e confirme que os artefatos de build não foram enviados ao Git
- ✓ Execute localmente
npm run build,hugoou o comando correspondente e confirme que o build local funciona
Se você já verificou tudo isso e o problema continua, pode pedir ajuda no fórum da comunidade Cloudflare ou consultar a seção Troubleshooting da documentação oficial.
Técnicas avançadas para deixar seu blog mais profissional
Colocar o blog no ar é apenas o começo. A seguir, compartilho algumas melhorias simples que podem elevar bastante a qualidade da experiência.
Associe um domínio personalizado
Você pode usar o domínio .pages.dev, mas um domínio próprio passa uma imagem mais profissional. A configuração é simples, e o Cloudflare também fornece um certificado SSL gratuito.
Etapas:
- Compre um domínio em um registrador, como GoDaddy, Alibaba Cloud ou Tencent Cloud
- Abra seu projeto no Cloudflare Pages e clique na aba Custom domains
- Clique em Set up a custom domain e informe seu domínio, como
blog.example.com - O Cloudflare fornecerá alguns registros DNS; volte à página de gerenciamento de DNS do registrador e adicione esses registros
- Aguarde a propagação do DNS, que normalmente leva de alguns minutos a algumas horas
- Depois da propagação, o Cloudflare configurará automaticamente o certificado HTTPS
Dica: se seu domínio também for gerenciado pelo Cloudflare, a propagação do DNS será mais rápida e a configuração poderá ser feita automaticamente, sem adicionar os registros à mão.
Otimize o build para ganhar velocidade
Quando o blog tem muitos artigos, o build pode demorar bastante. Estas sugestões ajudam a reduzir o tempo:
- Ative o cache
- Por padrão, o Cloudflare Pages armazena
node_modulesem cache - Se o build estiver lento, verifique se as dependências estão sendo baixadas novamente em todas as execuções
- Por padrão, o Cloudflare Pages armazena
- Reduza dependências desnecessárias
- Confira o package.json e remova os pacotes que não são usados
- Quando uma biblioteca puder ser carregada por CDN, como jQuery, evite instalá-la no projeto
- Use build paralelo
- O Hugo oferece o parâmetro
--gcpara limpar o cache, o que às vezes acelera o build - O Astro permite ativar o cache
experimental.contentCollectionCache
- O Hugo oferece o parâmetro
- Adote uma estratégia de branches
- Durante o desenvolvimento, você pode trabalhar na branch
deve integrar as mudanças amainapenas na publicação - Assim, nem todo commit dispara um build no ambiente de produção
- Durante o desenvolvimento, você pode trabalhar na branch
Monitore e analise o desempenho
Quer saber como as pessoas acessam seu blog? O Cloudflare oferece ferramentas gratuitas de análise.
Como consultar os dados de acesso:
- Abra o projeto no Cloudflare Pages
- Clique na aba Analytics
- Você poderá ver:
- Total de acessos, ou Requests
- Uso de largura de banda, ou Bandwidth
- Países de origem dos acessos, ou Requests by country
- Gráfico de tendências de tráfego
Monitoramento de desempenho com Web Vitals:
- O Cloudflare também oferece monitoramento de Web Vitals, com métricas de velocidade de carregamento, atraso de interação e outros indicadores
- Esses dados ajudam bastante a melhorar a experiência do usuário
- Se alguma métrica estiver ruim, você pode fazer otimizações direcionadas, como comprimir imagens ou adotar carregamento adiado
Automatize o fluxo de trabalho
Se quiser avançar na automação, combine o projeto com GitHub Actions para implementar recursos adicionais:
Exemplo 1: publicação programada de artigos
- Escreva o artigo e defina uma data futura de publicação
- Use o GitHub Actions para verificar o horário periodicamente e publicar automaticamente quando chegar o momento
Exemplo 2: geração automática do sitemap
- Envie o sitemap aos mecanismos de busca automaticamente após cada implantação
Exemplo 3: compressão de imagens
- Comprima as imagens automaticamente antes do envio para reduzir o tempo de carregamento
Esses recursos não são obrigatórios, mas podem simplificar a operação do blog. Se tiver interesse, vale estudar o GitHub Actions; a comunidade oferece muitos modelos prontos.
Conclusão
Depois de tudo isso, fica claro que implantar um blog estático não é tão complicado. O essencial é entender duas configurações: o comando de build e o diretório de saída. Ao preencher os valores corretamente conforme a tabela, você evita 90% dos problemas.
Aqui está novamente o resumo das configurações principais. Vale a pena salvar esta tabela:
| Framework | Comando de build | Diretório de saída | Variável de ambiente obrigatória |
|---|---|---|---|
| Astro | npm run build | dist | - |
| Hugo | hugo | public | HUGO_VERSION = 0.143.1 |
| Hexo | hexo generate | public | - |
| Gatsby | gatsby build | public | - |
| Eleventy | npx @11ty/eleventy | _site | - |
Se encontrar algum problema, não se preocupe: na maioria dos casos, algum valor foi preenchido incorretamente. Consulte primeiro o log de build e depois siga o checklist deste artigo. Isso costuma ser suficiente para encontrar a causa.
Agora é hora de testar. Abra o Cloudflare Pages, conecte seu repositório Git, informe os valores corretos e, em 10 minutos, seu blog poderá estar no ar.
Se este artigo ajudou você, compartilhe-o com outras pessoas que também estão tentando implantar seus blogs. Se encontrar algum problema que não foi abordado aqui, deixe um comentário; sua experiência pode ajudar outros leitores.
Boa implantação e boa escrita!
Processo completo para implantar um blog estático no Cloudflare Pages
Processo completo do repositório Git ao site no ar, com as configurações corretas de cinco frameworks populares e métodos para solucionar os problemas mais comuns.
⏱️ Estimated time: 10 min
- 1
Step 1: Preparação: confirme o envio do código e a configuração do projeto
Antes de começar, confirme estes três pontos:
1. O código já foi enviado ao GitHub ou GitLab
• Abra a página do repositório e confirme que o código mais recente está lá
2. O projeto tem um package.json, caso seja um projeto Node.js
• Confira se todas as dependências estão declaradas nele
• Não deixe pacotes instalados apenas localmente e ausentes do package.json
3. Verifique o .gitignore
• Confirme que diretórios como node_modules, dist e public estão no .gitignore
• Não envie os artefatos de build ao repositório
• Já vi um amigo enviar até node_modules ao Git, o que causou vários conflitos durante a implantação - 2
Step 2: Entre no Cloudflare e conecte o repositório Git
Etapa 1: entre no Cloudflare e acesse Pages
• Abra dash.cloudflare.com e faça login na sua conta; se ainda não tiver uma, crie gratuitamente
• No menu lateral, encontre Workers & Pages e abra essa opção
• Em seguida, clique no botão Create application no canto superior direito
Etapa 2: escolha Connect to Git
• Você verá duas opções:
- Connect to Git: implantação automática a partir do GitHub/GitLab; esta é a opção que usaremos
- Direct Upload: upload manual de arquivos; não é recomendado porque exige um novo envio a cada alteração
• Selecione Connect to Git e depois GitHub ou GitLab
Etapa 3: autorize o acesso
• Na primeira conexão, será preciso autorizar o Cloudflare a acessar seu repositório Git
• Clique em Sign in para ir à página de autorização do GitHub/GitLab
• Sobre as permissões: se não quiser dar ao Cloudflare acesso a todos os repositórios, selecione Only select repositories e autorize apenas os repositórios necessários
• Após a autorização, você voltará à página do Cloudflare
Etapa 4: escolha o repositório que será implantado
• Encontre o projeto do seu blog na lista de repositórios e clique nele
• Se o repositório não aparecer, clique no botão de atualização no canto superior direito ou volte à etapa anterior e refaça a autorização - 3
Step 3: Configure o build: informe o comando e o diretório de saída
Etapa 5: configure o build, a parte mais importante
Este é o momento mais importante da configuração, portanto não preencha os campos incorretamente.
Informações básicas:
• Project name, o nome do projeto: fará parte do seu domínio .pages.dev
- Por exemplo, se você informar my-blog, o domínio será my-blog.pages.dev
• Production branch, a branch de produção: normalmente main ou master
• Framework preset, a predefinição do framework: você pode escolher o framework usado, como Astro ou Hugo, ou selecionar None
Agora vem o ponto principal: Build settings
Preencha os valores corretos de acordo com o framework, seguindo a tabela de configurações apresentada anteriormente.
Build command, o comando de build:
• Astro: npm run build
• Hugo: hugo ou hugo -b $CF_PAGES_URL
• Hexo: hexo generate
• Gatsby: gatsby build
• Eleventy: npx @11ty/eleventy
• Next.js: npx opennextjs-cloudflare
Build output directory, o diretório de saída:
• Astro: dist
• Hugo: public
• Hexo: public
• Gatsby: public
• Eleventy: _site
• Next.js: .worker-next
Atenção:
• Ao escolher um Framework preset, o Cloudflare preencherá alguns valores padrão automaticamente
• Esses valores nem sempre estão corretos, então vale a pena conferi-los manualmente - 4
Step 4: Defina as variáveis de ambiente, salve e implante
Etapa 6: defina as variáveis de ambiente, se necessário
Role a página até Environment variables (advanced) e clique em Add variable.
Adicione as variáveis necessárias para o seu framework:
Projetos Hugo precisam desta variável:
• Variable name: HUGO_VERSION
• Value: 0.143.1, ou a versão necessária, sempre com os três componentes da versão
Projetos Hexo, se necessário:
• Variable name: NODE_VERSION
• Value: 14.3 ou 18.17.0, conforme a versão usada localmente
Depois de preencher as variáveis de ambiente, a configuração estará concluída.
Etapa 7: salve e implante
• Revise toda a configuração e, quando confirmar que está correta, clique em Save and Deploy no fim da página
• O Cloudflare começará a compilar o projeto
• Você verá uma página com o log de build e o progresso em tempo real
• Em geral, o build termina em 1 a 3 minutos
Etapa 8: veja o resultado da implantação
• Após o build terminar com sucesso, a página exibirá a mensagem Sucesso! Seu site está no ar!
• Logo abaixo haverá um link no formato nome-do-projeto.pages.dev
• Abra o link e, se tudo estiver correto, você verá seu blog - 5
Step 5: Resolva problemas comuns: falha no build e página em branco
Problema 1: falha no build, ou Building Failed
Sintomas:
• A implantação fica presa no estado Building e, depois de algum tempo, mostra Build failed
• A página exibe um ícone vermelho de erro
Como investigar:
1. Consulte o log de build
• Na página da implantação que falhou, clique em View build log ou Deployment details
• Role até o final e procure a mensagem de erro em vermelho
• Observe principalmente as últimas linhas, que normalmente indicam a causa do problema
2. Confira se o comando de build está correto
• Volte a Settings > Build & deployments
• Verifique se Build command foi preenchido conforme a tabela de configurações
• Erro comum: escrever npm build em vez de npm run build, omitindo run
3. Confira se todas as dependências estão presentes
• Se o log mostrar Cannot find module ou Command not found
• Isso indica uma dependência ausente; verifique se o pacote está no package.json
4. Confirme a versão do framework
• Em projetos Hugo, 99% das falhas de build acontecem porque HUGO_VERSION não foi definida
• O log pode mostrar Theme requires Hugo Extended version
• Acesse Settings > Environment variables e adicione HUGO_VERSION = 0.143.1
Problema 2: página em branco, o caso mais comum
Sintomas:
• A implantação termina com sucesso, mas o site abre apenas uma página em branco
• Ao abrir o console com F12, podem aparecer vários erros 404
• Já encontrei esse problema muitas vezes, e em 90% dos casos o diretório de saída estava incorreto
Como investigar:
1. Abra as ferramentas de desenvolvedor do navegador com F12
• Consulte a aba Console para ver se há erros
• Abra a aba Network, recarregue a página e veja quais recursos retornam 404
• Consulte a aba Sources para verificar se a estrutura de arquivos está correta
2. Confira a configuração do diretório de saída, a causa mais comum em 90% dos casos
• Volte a Settings > Build & deployments no Cloudflare Pages
• Verifique se Build output directory está correto
• Erros comuns:
- Informar public em vez de dist em projetos Astro
- Informar dist em vez de public em projetos Hugo
- Informar site em vez de _site em projetos Eleventy, esquecendo o sublinhado
FAQ
Quanto tempo leva para implantar um blog estático no Cloudflare Pages?
Entre fazer login no Cloudflare, conectar o repositório Git, configurar o build, definir as variáveis de ambiente e salvar a implantação, o build em si costuma terminar em 1 a 3 minutos.
Com tudo configurado corretamente, é perfeitamente possível sair do repositório Git e colocar o site no ar em 10 minutos.
Por que 90% das falhas de implantação estão ligadas ao comando de build e ao diretório de saída?
• O diretório de saída padrão do Astro é dist
• No Hugo, é public
• No Eleventy, é _site; repare no sublinhado
Copiar cegamente outro tutorial pode levar você direto a esse problema. Por exemplo, informar public em vez de dist em um projeto Astro, ou dist em vez de public em um projeto Hugo, pode deixar a página em branco.
O mesmo vale para o comando de build: cada framework usa seu próprio comando, e um valor incorreto faz o build falhar.
Por que projetos Hugo apresentam tantos erros e qual variável de ambiente é obrigatória?
Variável de ambiente obrigatória:
• Em Variable name, informe HUGO_VERSION
• Em Value, informe 0.143.1, ou a versão necessária, sempre com os três componentes; não use apenas 0.143
Como configurar:
1. Abra o projeto no Cloudflare Pages e clique na aba Settings
2. No menu lateral, selecione Environment variables
3. Clique em Add variable
4. Informe o nome e o valor da variável e clique em Save
O que fazer quando a implantação termina com sucesso, mas a página fica em branco?
Como investigar:
1. Abra as ferramentas de desenvolvedor do navegador com F12
• Consulte a aba Console para ver se há erros
• Abra a aba Network, recarregue a página e veja quais recursos retornam 404
2. Confira a configuração do diretório de saída
• Volte a Settings > Build & deployments no Cloudflare Pages
• Verifique se Build output directory está correto
• Erros comuns:
- Informar public em vez de dist em projetos Astro
- Informar dist em vez de public em projetos Hugo
- Informar site em vez de _site em projetos Eleventy, esquecendo o sublinhado
3. Confira a configuração de baseURL ou publicPath
• Ao implantar em um subcaminho, talvez seja necessário configurar baseURL
4. Confira o modo de roteamento
• Se você usa o modo history do Vue Router ou React Router
• A página pode retornar 404 ao ser recarregada
• Use o modo hash ou adicione um arquivo _redirects à raiz do projeto
Quais são as configurações padrão dos cinco frameworks mais populares?
• Comando de build: npm run build
• Diretório de saída: dist
• A configuração padrão é suficiente; SSR exige configuração adicional
Hugo:
• Comando de build: hugo ou hugo -b $CF_PAGES_URL
• Diretório de saída: public
• É obrigatório definir HUGO_VERSION como 0.143.1 ou uma versão superior
Hexo:
• Comando de build: hexo generate
• Diretório de saída: public
• Alguns temas exigem a definição de NODE_VERSION
Gatsby:
• Comando de build: gatsby build
• Diretório de saída: public
• É o mais simples e raramente apresenta problemas
Eleventy:
• Comando de build: npx @11ty/eleventy
• Diretório de saída: _site, começando com sublinhado
Next.js:
• Comando de build: npx opennextjs-cloudflare
• Diretório de saída: .worker-next
• Esta é a nova solução de 2025; ignore tutoriais antigos
Como definir variáveis de ambiente e é preciso implantar novamente após uma alteração?
• Abra seu projeto no Cloudflare Pages
• Clique na aba Settings na parte superior
• No menu lateral, selecione Environment variables
• Clique em Add variable
• Informe o nome e o valor da variável e clique em Save
Variáveis de ambiente comuns:
• HUGO_VERSION: número da versão do Hugo, como 0.143.1
• NODE_VERSION: número da versão do Node.js, como 18.17.0
• CF_PAGES_URL: fornecida automaticamente pelo Cloudflare; não precisa ser definida manualmente e é usada como baseURL
Aviso importante:
• Depois de alterar variáveis de ambiente, é necessário implantar novamente para que a mudança tenha efeito
• Abra a aba Deployments e encontre a implantação mais recente
• Clique nos três pontos à direita e escolha Retry deployment
O que mudou no Cloudflare Pages em 2025 e ainda vale a pena usá-lo?
Para implantar um blog estático, porém, essa mudança tem pouco impacto:
• O Pages continua estável e plenamente funcional
• Para um blog ou site de documentação sem renderização complexa no servidor ou computação de borda, ele continua sendo uma ótima opção
• O Workers é mais adequado para projetos que precisam de recursos dinâmicos, rotas de API ou computação de borda avançada
Em resumo, você pode usar o Pages com tranquilidade para implantar um blog totalmente estático. Se precisar adicionar recursos de servidor no futuro, poderá considerar uma migração para o Workers.
20 min de leitura · Publicado em: 1 dez 2025 · Atualizado em: 4 set 2026
Cloudflare Full Stack
Se você chegou pela busca, o caminho mais rápido é ir para o post anterior ou próximo desta série.
Anterior
Limites do plano gratuito da Cloudflare em 2026: Free, Pro ou Business?
Entenda os limites do plano gratuito da Cloudflare e compare preços, Workers, tamanho do corpo da requisição, WAF, Page Rules e proteção contra bots nos planos Free, Pro e Business em 2026.
Parte 1 de 13
Próximo
Guia completo para implantar aplicações frontend no Cloudflare Pages: configuração de React/Vue/Next.js e solução de erros
Aprenda passo a passo a implantar React, Vue e Next.js no Cloudflare Pages, com checklist completo de configuração, variáveis de ambiente e soluções para cinco erros comuns. Inclui uma explicação detalhada sobre nodejs_compat no Next.js.
Parte 3 de 13



Comentários
Entre com GitHub para comentar