Alternar tema

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

Easton editorial illustration: before-after repair bench

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

FrameworkComando de buildDiretório de saídaObservação importante
Astronpm run builddistO padrão é suficiente; SSR exige configuração adicional
HugohugopublicÉ obrigatório definir a variável de ambiente HUGO_VERSION
Hexohexo generatepublicAlguns temas exigem a definição de NODE_VERSION
Gatsbygatsby buildpublicÉ o mais simples e raramente apresenta problemas
Eleventynpx @11ty/eleventy_siteRepare no sublinhado no início
Next.jsnpx opennextjs-cloudflare.worker-nextEsta é a nova solução de 2025; ignore tutoriais antigos
90%+
Taxa de sucesso da implantação
Após configurar corretamente o comando de build e o diretório de saída
10 minutos
Tempo de implantação
Do repositório Git ao site no ar
90%
Taxa dos erros comuns
Página em branco causada por um diretório de saída incorreto

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 build ou diretamente astro 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: hugo ou hugo -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, como 0.143.1, e não apenas 0.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 abreviada hexo g també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.3 ou 18.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 é:

  1. Instale a dependência: npm install @opennextjs/cloudflare
  2. Informe o comando de build: npx opennextjs-cloudflare
  3. 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:

  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 e não deixe pacotes instalados apenas localmente
  3. Verifique o .gitignore — confirme que diretórios como node_modules, dist e public estã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ê 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 anterior:

  • 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

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
  • 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á “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:

  1. Abra seu projeto no Cloudflare Pages
  2. Clique na aba Settings na parte superior
  3. No menu lateral, selecione Environment variables
  4. Clique em Add variable
  5. 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, 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:

  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
    • Talvez ele tenha sido instalado localmente, mas não adicionado ao package.json; npm install --save faz isso automaticamente
  4. 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

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:

  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
    • 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 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, 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 arquivo astro.config.mjs
    • Projetos Vue/React: talvez seja necessário definir publicPath: './', usando um caminho relativo
  4. 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 _redirects com este conteúdo:
        /* /index.html 200

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:

  1. 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
  2. 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 .RelPermalink ou absURL
      • Hexo: use a função auxiliar url_for()
  3. 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:

  1. ✓ Consulte o log de build e encontre a mensagem de erro
  2. ✓ Confirme se o comando de build está correto, comparando-o com a tabela
  3. ✓ Confirme se o diretório de saída está correto, comparando-o com a tabela
  4. ✓ Confira se as variáveis de ambiente foram definidas; projetos Hugo exigem HUGO_VERSION
  5. ✓ Abra o F12 do navegador e consulte o console e as solicitações de rede
  6. ✓ Confira o .gitignore e confirme que os artefatos de build não foram enviados ao Git
  7. ✓ Execute localmente npm run build, hugo ou 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:

  1. Compre um domínio em um registrador, como GoDaddy, Alibaba Cloud ou Tencent Cloud
  2. Abra seu projeto no Cloudflare Pages e clique na aba Custom domains
  3. Clique em Set up a custom domain e informe seu domínio, como blog.example.com
  4. O Cloudflare fornecerá alguns registros DNS; volte à página de gerenciamento de DNS do registrador e adicione esses registros
  5. Aguarde a propagação do DNS, que normalmente leva de alguns minutos a algumas horas
  6. 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:

  1. Ative o cache
    • Por padrão, o Cloudflare Pages armazena node_modules em cache
    • Se o build estiver lento, verifique se as dependências estão sendo baixadas novamente em todas as execuções
  2. 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
  3. Use build paralelo
    • O Hugo oferece o parâmetro --gc para limpar o cache, o que às vezes acelera o build
    • O Astro permite ativar o cache experimental.contentCollectionCache
  4. Adote uma estratégia de branches
    • Durante o desenvolvimento, você pode trabalhar na branch dev e integrar as mudanças a main apenas na publicação
    • Assim, nem todo commit dispara um build no ambiente de produção

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:

  1. Abra o projeto no Cloudflare Pages
  2. Clique na aba Analytics
  3. 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:

FrameworkComando de buildDiretório de saídaVariável de ambiente obrigatória
Astronpm run builddist-
HugohugopublicHUGO_VERSION = 0.143.1
Hexohexo generatepublic-
Gatsbygatsby buildpublic-
Eleventynpx @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. 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. 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. 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. 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. 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?
Todo o processo de implantação leva cerca de 10 minutos.

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?
Cada framework tem configurações padrão diferentes:
• 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?
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á.

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?
Em 90% dos casos, a página em branco é causada por um diretório de saída 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

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?
Astro:
• 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?
Como configurar:
• 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?
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 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

Comentários

Entre com GitHub para comentar

Easton BlogEaston Blog