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
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.
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.