Ir para o conteúdo
Promovaweb

Cloudflare Pages: o site estático ligado ao repositório

O Cloudflare Pages é o serviço de hospedagem de sites estáticos da Cloudflare, ligado a um repositório no GitHub ou no GitLab. A cada push, ele roda o comando de build do seu projeto, envia a pasta gerada para a rede global da Cloudflare e publica o resultado no endereço do projeto, com uma prévia separada para cada branch que não é a de produção.

Ficha e sumário da página

Referência técnica
Wrangler 4.162.0
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. Um projeto do Pages é um repositório com endereço
  2. O que vai dentro da pasta publicada
  3. Produção, prévias e aliases
  4. Pages ou Workers para um site novo

Um projeto do Pages é um repositório com endereço

Um projeto do Pages junta três coisas: o repositório de origem, as configurações de build e um subdomínio em pages.dev. O subdomínio sai do nome do projeto, então um projeto chamado meu-site responde em meu-site.pages.dev e aceita domínios próprios por cima, com até 100 domínios personalizados por projeto no plano Free.

As configurações de build dizem ao Pages como transformar o código em arquivos. Para um site do Astro, o guia oficial usa npm run build como comando de build e dist como pasta de saída. O Pages roda esse comando num ambiente de build da Cloudflare, pega o conteúdo da pasta e envia cada arquivo para a rede, de modo que nenhum servidor seu participa das requisições ao site depois do deploy.

O Git é um dos três caminhos de publicação que a documentação oferece. O Direct Upload recebe uma pasta já construída, enviada pelo painel ou pelo Wrangler. O C3, a ferramenta de linha de comando create-cloudflare, cria o projeto a partir de um modelo. A documentação avisa que um projeto criado com a integração do Git não muda para Direct Upload depois. O caminho alternativo é desligar os deploys automáticos e publicar pelo Wrangler.

O que vai dentro da pasta publicada

O Pages publica a pasta de saída como ela está e reconhece dois arquivos de configuração opcionais dentro dela. A árvore abaixo mostra a pasta de um site do Astro depois do build, com os nomes que o Pages reconhece:

  • dist/Pasta de saída do build, publicada inteira em cada deploy.
  • index.htmlPágina inicial, servida em meu-site.pages.dev/.
  • blog/primeiro-post/index.htmlCada rota do Astro vira uma pasta com o próprio index.html.
  • _astro/CSS e JavaScript com hash no nome, que o navegador guarda em cache.
  • _headersCabeçalhos HTTP por caminho, com até 100 entradas.
  • _redirectsRedirecionamentos por caminho, até 2.000 estáticos e 100 dinâmicos.
  • 404.htmlPágina de erro devolvida quando o caminho não existe.
A pasta de saída de um site do Astro publicada no Pages. Os arquivos _headers e _redirects ficam na raiz da pasta. A pasta functions fica fora dela, na raiz do repositório.

Cada arquivo pode ter até 25 MiB, num total de 20.000 arquivos por site no plano Free ou 100.000 nos planos pagos. Para arquivos maiores, como vídeos e downloads pesados, a própria documentação do Pages indica um bucket do R2 com acesso público num subdomínio, como mostra a página R2: armazenamento de objetos.

Quando o site precisa de código no servidor, o Pages Functions executa arquivos da pasta functions do repositório. Cada função roda na mesma plataforma dos Workers, por isso as requisições a ela entram na cota do plano dos Workers.

Produção, prévias e aliases

O Pages trata a branch de produção de um jeito diferente das demais. Os commits na branch de produção, normalmente a main, atualizam o endereço meu-site.pages.dev e os domínios próprios. Os commits em qualquer outra branch geram um deploy de prévia, que não altera o site em produção.

Cada deploy de prévia recebe um endereço fixo com um hash na frente, como 373f31e2.meu-site.pages.dev, que continua acessível depois. O Pages também cria um alias com o nome da branch e o move para o deploy mais recente dela, como development.meu-site.pages.dev para a branch development. O nome entra no alias em minúsculas e com hífen no lugar dos caracteres que não são letras nem números, então a branch fix/api responde em fix-api.meu-site.pages.dev.

No GitHub, a integração também publica o status do build no repositório e mostra a URL de prévia nos pull requests abertos a partir do próprio repositório. Um commit com a marcação de pular build não dispara deploy. A página Builds e deploy pelo GitHub compara esse fluxo com o dos Workers.

  • 500 builds por mêsUm build por vez, com tempo máximo de 20 minutos cada.
  • 20.000 arquivos por siteCada arquivo com até 25 MiB.
  • 100 domínios por projetoOs planos pagos aceitam 250 ou 500 domínios.
  • Prévias sem limiteTodas as branches podem ter um deploy de prévia ativo.

Pages ou Workers para um site novo

A página principal do Pages traz um aviso no topo: os Workers cobrem a maior parte dos usos do Pages com mais recursos. A Cloudflare orienta começar projetos novos pelos Workers e mantém um guia de migração do Pages para Workers com assets estáticos. O Pages continua disponível em todos os planos, inclusive para os projetos que já rodam nele.

Para um site estático, a troca muda pouco no dia a dia. Os assets estáticos de um Worker também servem a pasta dist sem executar código, com as requisições a arquivos gratuitas e ilimitadas. O build a cada push também continua, agora pelo Workers Builds. Quando o site ganha código, o Worker declara num único arquivo de configuração a pasta de arquivos, o código de cada requisição e os bindings com o R2.

O website da Promovaweb usa o segundo modelo e roda como um Worker com assets estáticos. A página Cloudflare Workers mostra o arquivo de configuração dele e o que cada chave declara.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.