Alternar tema

Guia completo para implantar Astro na Cloudflare: SSR e acesso 3 vezes mais rápido na China

Easton editorial illustration: modular system blueprint

Na semana passada, ajudei um amigo a implantar um blog em Astro e encontrei um problema curioso. Depois da implantação na Cloudflare Pages, testei o site fora da China e as páginas abriram imediatamente. Quando os amigos dele tentaram acessar da China, porém, o carregamento levou quase 5 segundos.

Se a Cloudflare anuncia mais de 300 data centers no mundo, plano grátis e largura de banda ilimitada, por que o acesso na China é tão lento? Esse problema afeta muitos desenvolvedores. Talvez você já tenha ouvido falar em “IP selecionado”, mas ainda tenha dúvidas sobre como fazer, o risco de punição e o resultado real.

Neste artigo, vou percorrer todo o processo de implantação de Astro na Cloudflare: de um site estático básico à configuração de SSR e à otimização do acesso na China. Eu mesmo encontrei vários obstáculos e reuni aqui o que aprendi para poupar seu tempo.

Você vai aprender a:

  • concluir a implantação do zero em 20 minutos;
  • entender os três modos do adaptador SSR;
  • aplicar três formas de otimizar o acesso na China e reduzir a latência em 3 vezes.

Vamos começar.

Por que escolher a Cloudflare Pages

Cloudflare vs. Vercel: comparação entre plataformas de hospedagem grátis

Uma pergunta frequente é: Vercel ou Cloudflare? A resposta depende do que você precisa.

A diferença mais evidente está no limite de largura de banda. O plano grátis da Vercel inclui 100 GB por mês; depois disso, cada 100 GB adicional custa US$ 40. Um projeto meu apareceu de repente numa lista popular, o tráfego disparou e a conta da Vercel chegou logo depois. Na Cloudflare Pages, a largura de banda é ilimitada e gratuita. Para desenvolvedores independentes, isso elimina o receio de uma cobrança inesperada por pico de tráfego.

Ilimitada
Limite de largura de banda
Grátis na Cloudflare Pages
300+
Nós globais
Cobertura mais ampla de data centers
3 vezes
Redução de latência
Após otimizar o acesso na China

Em desempenho global, a Cloudflare tem mais de 300 data centers e uma cobertura ampla. Testei alguns pontos na Europa, Ásia e América, todos com baixa latência. A rede de borda da Vercel também é boa, mas tem relativamente menos nós. Se os usuários estão espalhados pelo mundo, a vantagem da Cloudflare fica mais clara.

Outro benefício prático é a proteção contra DDoS. Ela já vem no plano grátis da Cloudflare, sem configuração adicional. Quando um dos meus sites foi atacado, a Cloudflare bloqueou o tráfego automaticamente. A Vercel também oferece proteção, mas no plano grátis ela se concentra mais em proteger a própria rede do que em uma defesa aprofundada para cada site.

E onde a Vercel se destaca? O cache de build é muito bom. Em um projeto com muitas imagens e dependências, ela reaproveita a build anterior, e a segunda pode levar apenas 3 ou 4 minutos. A Cloudflare Pages costuma reconstruir tudo, o que pode passar de dez minutos. A Vercel também tem integração profunda com Next.js, então é a melhor escolha para quem usa o framework intensivamente.

Minha recomendação:

  • Blog estático em Astro → Cloudflare Pages, pela franquia de tráfego grátis
  • Projeto com tráfego imprevisível → Cloudflare Pages, para evitar cobranças inesperadas
  • Uso intensivo de Next.js → Vercel, pela melhor experiência
  • Iterações rápidas e builds frequentes → Vercel, pelo cache de build

Cloudflare Pages vs. Workers: o que mudou em 2025

Essa diferença também me confundiu no começo. Tanto Pages quanto Workers podem implantar Astro; qual usar?

A diferença essencial é simples. Workers é a plataforma de computação serverless da Cloudflare, onde você executa JavaScript na borda. Pages pode ser entendida como um pacote de Workers com ferramentas automatizadas de build. Ela usa Workers por baixo, mas acrescenta integração com Git e implantação automática.

Em 2025, a Cloudflare começou a recomendar Workers para novos projetos, principalmente por oferecer mais flexibilidade e controle. Para usuários de Astro, porém, não é necessário levar a recomendação ao extremo.

Minha experiência prática:

  • Com Pages: você conecta o repositório do GitHub e cada push inicia a build automaticamente. É uma solução direta para quem quer implantar sem complicação.
  • Com Workers: você implanta manualmente com Wrangler CLI e configura o arquivo wrangler.jsonc. Em troca, tem controle mais preciso sobre variáveis de ambiente, bindings de KV e outros recursos.

Qual escolher para Astro?

  • Site totalmente estático (output: 'static'): use Pages e conecte o GitHub pelo Dashboard.
  • Site SSR (output: 'server' ou 'hybrid'): ambos funcionam, mas recomendo Pages + Wrangler CLI para combinar automação e flexibilidade.

Se for sua primeira implantação, comece pela integração Git da Pages. Em poucos minutos você vê o resultado e pode considerar Wrangler CLI mais tarde.

Processo completo de implantação de Astro na Cloudflare

Site estático: primeiros passos em 5 minutos

Se o projeto Astro for totalmente estático — um blog, uma documentação ou um portfólio — a implantação é muito simples.

Pré-requisitos:

  • o projeto já foi enviado ao GitHub;
  • você tem uma conta da Cloudflare, que pode ser gratuita.

Etapas:

  1. Entre no Cloudflare Dashboard
    Abra dash.cloudflare.com e acesse Workers & Pages no menu lateral.

  2. Crie um projeto
    Clique em Create applicationPagesConnect to Git.

  3. Conecte o repositório do GitHub
    Selecione o repositório do projeto Astro. Na primeira vez, autorize o acesso da Cloudflare seguindo as instruções.

  4. Configure a build
    Esta etapa é importante: um valor errado impede a implantação.

    • Framework preset: selecione Astro
    • Build command: npm run build
    • Build output directory: dist
    • Root directory: deixe em branco se o projeto estiver na raiz; caso contrário, informe o caminho
  5. Inicie a implantação
    Clique em Save and Deploy e aguarde alguns minutos. A Cloudflare baixa o código, instala as dependências, executa a build e publica o resultado.

Ao concluir, você recebe um domínio como your-project.pages.dev. Cada push ao GitHub inicia automaticamente uma nova build.

Problemas comuns:

  • A build falha por causa da versão do Node.js: adicione .nvmrc ou .node-version à raiz do projeto com 18 ou 20.
  • A página retorna 404: confirme se Build output directory é dist. Dependendo de astro.config.mjs, o valor pode ser public ou build.
  • A build excede o tempo limite: pode haver dependências demais ou um problema de rede. Tente implantar novamente.

Vincular um domínio próprio (opcional):

Depois da implantação, abra Custom domains nas configurações do projeto, clique em Set up a custom domain e informe o domínio, como blog.yourdomain.com. A Cloudflare fornece um registro CNAME para adicionar ao provedor de DNS. Se o domínio já usa o DNS da Cloudflare, a configuração é automática.

Site SSR: configuração detalhada do adaptador @astrojs/cloudflare

A documentação de SSR pode parecer espalhada. A seguir, organizei as etapas na ordem em que você realmente as executa.

Quando usar SSR?

  • Dados em tempo real: comentários, estatísticas de acesso ou login
  • Lógica no servidor: chamadas de API, consultas ao banco ou autorização
  • Renderização sob demanda: muito conteúdo que você não quer pré-renderizar por completo

Se você mantém apenas um blog em Markdown, não precisa de SSR; uma implantação estática basta.

Etapa 1: instalar o adaptador @astrojs/cloudflare

Na raiz do projeto, execute:

npx astro add cloudflare

O comando faz três coisas:

  1. instala o pacote @astrojs/cloudflare;
  2. adiciona o adaptador a astro.config.mjs;
  3. cria wrangler.jsonc, o arquivo de configuração do Cloudflare Workers.

Depois disso, astro.config.mjs deve se parecer com este exemplo:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server', // linha adicionada
  adapter: cloudflare(),
});

Etapa 2: escolher o modo de renderização

Há três opções:

1. output: 'server' — SSR em todo o site

  • Todas as páginas são renderizadas no servidor.
  • Indicado para aplicações orientadas a dados e conteúdo atualizado com frequência.
  • Desvantagem: cada solicitação exige renderização e pode ser um pouco mais lenta.

2. output: 'hybrid' — modo híbrido (recomendado)

  • Por padrão, as páginas são estáticas.
  • Páginas específicas podem usar SSR.
  • Indicado para blogs em que a maior parte é estática, com alguns recursos dinâmicos.
  • Oferece boa flexibilidade e desempenho.

3. output: 'static' — totalmente estático

  • Não exige adaptador; é a implantação estática descrita antes.

Minha recomendação: em 90% dos casos, escolha hybrid, a menos que tenha certeza de que todo o site precisa de SSR.

Exemplo do modo híbrido:

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // altere para hybrid
  adapter: cloudflare(),
});

Na página que precisa de SSR, adicione:

// src/pages/api/comments.js
export const prerender = false; // esta página usa SSR

export async function GET() {
  // Busca os comentários no banco de dados
  const comments = await fetchComments();
  return new Response(JSON.stringify(comments));
}

As demais páginas continuam estáticas por padrão.

Etapa 3: configurar bindings de serviços da Cloudflare (opcional)

Para usar KV, D1 ou R2, configure os bindings em wrangler.jsonc.

Neste exemplo, um namespace KV armazena sessões de usuários:

// wrangler.jsonc
{
  "name": "my-astro-app",
  "compatibility_date": "2024-01-01",
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "your-kv-namespace-id"
    }
  ]
}

Primeiro, crie um namespace KV no Cloudflare Dashboard e copie o ID para o arquivo.

Depois, use-o no código:

// src/pages/api/session.js
export const prerender = false;

export async function GET({ locals }) {
  const { MY_KV } = locals.runtime.env;
  const sessionData = await MY_KV.get('user:123');
  return new Response(sessionData);
}

Etapa 4: desenvolver e testar localmente

Instale o Wrangler CLI, a ferramenta oficial da Cloudflare:

npm install wrangler --save-dev

Execute localmente:

npm run build
npx wrangler pages dev ./dist

Isso inicia um servidor local que simula o ambiente da Cloudflare e permite testar SSR e bindings.

Etapa 5: publicar

Há duas formas.

Opção 1: Wrangler CLI (recomendada, com mais controle)

# Entre na conta da Cloudflare
npx wrangler login

# Gere a build
npm run build

# Implante
npx wrangler pages deploy ./dist

Na primeira implantação, informe o nome do projeto. Nas próximas, basta repetir o comando.

Opção 2: implantação automática pela integração Git

Conecte o repositório do GitHub como na implantação estática. A Cloudflare reconhece o adaptador @astrojs/cloudflare. Para usar KV e outros serviços, porém, você precisa configurar os bindings manualmente no Dashboard.

Solução de erros comuns:

  1. “Hydration completed but contains mismatches”
    Esse erro costuma ser causado pelo Auto Minify da Cloudflare, que altera o HTML. Abra Cloudflare Dashboard → domínio → Speed → Optimization e desative HTML, CSS e JS em Auto Minify.

  2. “Cannot find module ‘MY_KV’”
    O binding não está configurado corretamente. Confirme que o nome binding em wrangler.jsonc é igual ao nome usado no código.

  3. Erro 500 depois da implantação
    Abra Cloudflare Dashboard → Workers & Pages → projeto → Logs e veja o erro detalhado. É provável que o código esteja acessando um recurso sem binding.

Variáveis de ambiente e gerenciamento de segredos

É fácil confundir essas configurações. Eu mesmo já enviei uma chave de API ao GitHub por engano e precisei removê-la rapidamente.

Ambiente de desenvolvimento local:

Crie .dev.vars na raiz do projeto:

# .dev.vars
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=your-secret-key-for-dev

Importante: inclua .dev.vars em .gitignore e nunca envie o arquivo ao GitHub.

No desenvolvimento local, o Wrangler lê esse arquivo automaticamente. Acesse a variável assim:

export const prerender = false;

export async function GET({ locals }) {
  const apiKey = locals.runtime.env.API_KEY;
  // Usa apiKey para chamar uma API de terceiros
}

Ambiente de produção:

Não use .dev.vars. Configure as variáveis no Cloudflare Dashboard:

  1. abra Workers & Pages e selecione o projeto;
  2. clique em SettingsEnvironment Variables;
  3. clique em Add variable e informe nome e valor;
  4. selecione Production ou Preview.

Use Secrets para dados sensíveis:

Para dados especialmente sensíveis, como chaves de API de pagamento, use Secrets, que são armazenados com criptografia:

npx wrangler secret put API_KEY

O comando solicita o valor sem exibi-lo no terminal.

Minha recomendação:

  • URL de banco e chaves de APIs externas → Secrets
  • Configurações públicas, como nome do site e endereço da CDN → variáveis comuns

Otimização prática da velocidade de acesso na China

Diagnóstico: meça a velocidade real do site na China

Depois da implantação, meça antes de otimizar. Nem todo site precisa de mudanças; se seus usuários estão principalmente fora da China, a configuração padrão da Cloudflare funciona muito bem.

Ferramentas de teste on-line:

  1. 17ce.com (recomendada)
    Abra 17ce.com, informe o domínio e selecione o teste de velocidade do site. A ferramenta mede a partir de várias províncias e operadoras chinesas. Observe o tempo de resposta: menos de 200 ms é bom; acima de 300 ms sugere a necessidade de otimização.

  2. Teste de ping do Chinaz
    tool.chinaz.com/speedtest oferece funções semelhantes e informações detalhadas de rota.

Teste local:

Se você estiver na China:

  1. pressione F12 para abrir o DevTools do Chrome;
  2. abra a guia Network;
  3. recarregue a página e observe o valor Time da primeira solicitação.

Referências:

  • Latência < 150 ms: muito boa, sem necessidade de otimizar
  • Latência entre 150 e 250 ms: aceitável; depende da necessidade
  • Latência > 250 ms ou carregamento > 3 segundos: otimização recomendada

Por que o acesso na China é lento?

A Cloudflare usa Anycast. Por causa das características da rede chinesa, a rota às vezes dá uma volta desnecessária. Uma conexão de Pequim, por exemplo, pode passar por Hong Kong antes de voltar. IP selecionado e CNAME tentam apontar para nós com rotas mais diretas.

Opção 1: IP selecionado (grátis e com o melhor resultado)

Foi a opção com maior impacto nos meus testes: a latência caiu de cerca de 280 ms para 70 ms. Ela exige um pouco mais de trabalho e envolve riscos, explicados adiante.

O que é um IP selecionado?

A Cloudflare tem centenas de endereços IP ligados a diferentes data centers. A velocidade de acesso a cada IP varia bastante na China. Selecionar um IP significa encontrar um endereço rápido e fazer o domínio apontar diretamente para ele.

Etapa 1: testar IPs

Baixe o CloudflareSpeedTest em XIU2/CloudflareSpeedTest.

No Windows, baixe CloudflareST.exe; no Linux ou macOS, use a versão correspondente.

No Windows, execute:

# Clique duas vezes ou execute no terminal
CloudflareST.exe

A ferramenta testa centenas de IPs da Cloudflare em 5 a 10 minutos e apresenta os mais rápidos:

Endereço IP      Latência  Velocidade de download
104.16.160.10   68ms      15.2MB/s
172.64.32.5     75ms      14.8MB/s
104.23.240.28   82ms      13.9MB/s

Anote o primeiro, que tem a menor latência.

Etapa 2: alterar o DNS

Pré-requisito importante: o DNS do domínio não pode estar hospedado na Cloudflare. Use outro provedor, como Alibaba Cloud ou DNSPod. Se estiver na Cloudflare DNS, migre-o primeiro.

Isso é necessário porque o DNS da Cloudflare força o uso de Anycast, mesmo que você altere o registro A.

Configuração no DNSPod:

  1. Entre no provedor de DNS.
  2. Adicione ou altere o registro A:
    • Nome: @ para o domínio raiz, ou www
    • Tipo: A
    • Valor: 104.16.160.10, substituído pelo IP testado
    • TTL: 600, ou 10 minutos
  3. Salve e aguarde de 5 a 10 minutos.

Etapa 3: verificar o resultado

Quando o DNS for propagado, teste novamente em 17ce.com. A melhora deve ser visível.

Aviso de risco:

Em janeiro de 2025, a Cloudflare atualizou os termos de serviço e incluiu a possibilidade de limitar ou punir comportamentos considerados abusivos. O texto não diz explicitamente se IP selecionado se enquadra nisso, mas existe risco.

Minha recomendação:

  • Blog pessoal ou projeto pequeno: pode usar; o risco é baixo.
  • Site comercial ou de alto tráfego: aja com cautela e prefira CNAME ou DNS por região.
  • Verificação periódica: teste a cada um ou dois meses, pois o IP pode parar de funcionar.

Problemas comuns:

  1. A alteração do DNS não foi aplicada

    • Limpe o cache do navegador ou use uma janela anônima.
    • Execute nslookup yourdomain.com para conferir a resolução.
  2. O IP ficou lento depois de algum tempo

    • Execute um novo teste e substitua o IP.
  3. Algumas regiões estão rápidas e outras lentas

    • China Telecom, China Unicom e China Mobile podem ter IPs ideais diferentes. O DNS por rota resolve esse caso.

Opção 2: domínio CNAME selecionado (grátis e mais estável)

Se testar IPs manualmente parecer trabalhoso ou você não quiser acompanhar a validade deles, use um CNAME público otimizado. Esses domínios apontam para IPs mantidos por terceiros e atualizados periodicamente.

Como funciona:

Alguns desenvolvedores ou organizações mantêm um domínio que aponta para os IPs mais rápidos no momento. Ao criar um CNAME para esse domínio, você aproveita a mesma otimização.

Etapa 1: escolher um CNAME público

Exemplos de domínios públicos — teste-os antes de usar:

  • cdn.cloudflare.quest
  • cf.xiu2.xyz

Atenção: um CNAME público pode parar de funcionar a qualquer momento. Acompanhe a comunidade responsável para saber quais domínios continuam disponíveis.

Etapa 2: alterar o DNS

O DNS também não pode estar na Cloudflare. No DNSPod:

  1. entre no provedor;
  2. adicione um registro CNAME:
    • Nome: @ ou www
    • Tipo: CNAME
    • Valor: cdn.cloudflare.quest, ou o domínio escolhido
    • TTL: 600
  3. salve e aguarde a propagação.

Etapa 3: resolver um possível erro 403

O método por CNAME pode gerar 403 Forbidden quando a Cloudflare detecta que o domínio acessado pelos IPs dela não está registrado no sistema.

Para resolver:

  1. migre o DNS para fora da Cloudflare, caso ainda esteja lá;
  2. exclua o site no Cloudflare Dashboard;
  3. aguarde alguns minutos e teste novamente.

Etapa 4: verificar o resultado

Depois da propagação, execute nslookup yourdomain.com, confirme que o domínio resolve para o CNAME público e faça um teste de velocidade.

Vantagens e desvantagens:

  • Vantagens:

    • dispensa testes manuais de IP;
    • o responsável atualiza os endereços, o que melhora a estabilidade;
    • o risco é um pouco menor que apontar diretamente para um IP.
  • Desvantagens:

    • você depende de um terceiro;
    • o resultado pode ser inferior a um IP testado especificamente para sua rede.

Minha recomendação: é uma opção equilibrada para quem quer otimizar sem dedicar muito tempo à manutenção.

Opção 3: DNS por região e operadora (pago e com o melhor resultado)

Esta é a solução mais completa. Ela tem um pequeno custo e é indicada para sites com muitos usuários dentro e fora da China e requisitos maiores de desempenho.

Ideia central:

O DNS retorna um IP diferente conforme a origem do usuário:

  • usuário da China Telecom → IP otimizado para essa operadora;
  • usuário da China Unicom → IP otimizado para essa operadora;
  • usuário fora da China → endereço padrão da Cloudflare ou your-project.pages.dev.

Assim, cada grupo usa uma rota adequada.

Ferramentas necessárias:

Use um provedor de DNS com resolução inteligente, por exemplo:

  • DNSPod, da Tencent Cloud, cujo plano pessoal grátis inclui funções básicas;
  • Alibaba Cloud DNS, pago e mais completo;
  • Cloudflare DNS, que não oferece rotas específicas por operadora chinesa e não serve para este cenário.

Configuração no DNSPod:

  1. Teste IPs em cada operadora

    Execute CloudflareSpeedTest em redes da China Telecom, China Unicom e China Mobile e anote o melhor IP. Estes blocos são apenas referências; seus próprios testes serão mais precisos:

    • China Telecom: 104.16.160.0/24
    • China Unicom: 104.23.240.0/24
    • China Mobile: 172.64.32.0/24
  2. Configure a resolução por rota

    Adicione vários registros A no DNSPod e defina uma rota diferente para cada um:

    Registro 1:
    - Nome: @
    - Tipo: A
    - Rota: China Telecom
    - Valor: 104.16.160.10
    
    Registro 2:
    - Nome: @
    - Tipo: A
    - Rota: China Unicom
    - Valor: 104.23.240.5
    
    Registro 3:
    - Nome: @
    - Tipo: A
    - Rota: China Mobile
    - Valor: 172.64.32.8
    
    Registro 4 (rota padrão para usuários no exterior):
    - Nome: @
    - Tipo: CNAME
    - Rota: padrão
    - Valor: your-project.pages.dev
  3. Salve e aguarde a propagação

Resultado:

Usuários das diferentes operadoras chinesas acessam o nó mais rápido, enquanto usuários no exterior continuam na rede nativa da Cloudflare.

Custo:

  • DNSPod pessoal: grátis, com rotas básicas
  • DNSPod profissional: 20 yuans por mês, com regiões mais específicas
  • Alibaba Cloud DNS: cobrança por consultas; um site pequeno gasta apenas alguns yuans por mês

Minha recomendação: se o site recebe mais de 10 mil visitas por mês, o pequeno custo pode valer a melhoria na experiência.

Comparação dos resultados e monitoramento

Como essas opções se comportam na prática? Estes são dados de um blog testado numa conexão da China Telecom em Pequim.

OpçãoLatência médiaTTFBTempo de carregamentoCusto
Sem otimização, Cloudflare padrão280 ms1,8 s3,2 sGrátis
Opção 1: IP selecionado75 ms0,5 s1,1 sGrátis
Opção 2: CNAME público120 ms0,7 s1,5 sGrátis
Opção 3: DNS por rota65 ms0,4 s0,9 s20 yuans/mês

Depois da otimização, a velocidade ficou 3 a 5 vezes maior, com uma diferença clara para os usuários.

Monitoramento contínuo:

A otimização não termina na configuração, porque um IP pode deixar de funcionar.

Ferramentas recomendadas:

  1. UptimeRobot (uptimerobot.com)

    • Monitora 50 sites no plano grátis.
    • Faz ping a cada 5 minutos e envia e-mail em caso de indisponibilidade.
    • Exibe a evolução do tempo de resposta.
  2. Cloudflare Analytics

    • Incluído gratuitamente no Cloudflare Dashboard.
    • Exibe origem dos acessos, uso de largura de banda e taxa de erros.
    • Não mostra a latência específica dentro da China.
  3. Better Uptime (betteruptime.com)

    • É pago, mas tem plano grátis.
    • Permite criar uma página pública de status.

Quando trocar o IP selecionado:

Crie um lembrete para verificar a cada um ou dois meses:

  1. teste em 17ce.com e veja se a latência aumentou;
  2. se passar de 200 ms, execute CloudflareSpeedTest e escolha outro IP;
  3. atualize o registro DNS.

Na minha experiência, a velocidade de um IP costuma oscilar de forma perceptível a cada dois ou três meses. Substituí-lo a tempo resolve o problema.

Conclusão

Em termos de implantação, a Cloudflare Pages simplifica bastante o uso de Astro. Para um site estático, conecte o GitHub e termine em poucos minutos. Se precisar de SSR, execute npx astro add cloudflare, escolha hybrid ou server e combine páginas estáticas e dinâmicas conforme a necessidade.

Na configuração de SSR, lembre-se destes pontos:

  • o modo hybrid atende melhor a 90% dos cenários;
  • configure os bindings em wrangler.jsonc para usar KV, D1 ou R2;
  • use .dev.vars localmente e o Dashboard para as variáveis de produção;
  • se houver erro de hidratação, desative Auto Minify.

Para otimizar o acesso na China, cada opção atende a um perfil:

  • Opção 1, IP selecionado: melhor resultado e grátis, mas requer manutenção e envolve algum risco.
  • Opção 2, CNAME público: simples, grátis e com resultado intermediário.
  • Opção 3, DNS por rota: solução mais completa, com pequeno custo e bom acesso dentro e fora da China.

Minha recomendação:

  • Blog pessoal ou pouco tráfego → opção 1 ou 2
  • Mais tráfego e foco na experiência → opção 3
  • Projeto comercial → use IP selecionado com cautela; prefira a opção 3 ou aceite a velocidade padrão

Próximos passos:

  1. crie uma conta da Cloudflare e teste uma implantação estática;
  2. se o acesso na China estiver lento, meça primeiro em 17ce.com;
  3. depois da otimização, crie um lembrete para verificar periodicamente o IP.

Para avançar:

A implantação é apenas o começo. O ecossistema Cloudflare também inclui:

  • Workers KV: armazenamento chave-valor para cache e sessões;
  • D1: banco SQLite executado diretamente na borda;
  • R2: armazenamento de objetos comparável ao AWS S3, com uma boa franquia grátis;
  • Pages Functions: funções serverless escritas diretamente na Pages.

Todos esses serviços podem ser integrados ao Astro e explorados aos poucos.

Se este artigo ajudou, compartilhe sua experiência de implantação ou os problemas que encontrou nos comentários.

Guia completo para implantar Astro na Cloudflare: do zero à publicação

Implante o projeto em 20 minutos, configure os três modos do adaptador SSR e conheça três formas de acelerar o acesso na China, com redução de latência de 3 vezes nos testes.

⏱️ Estimated time: 20 min

  1. 1

    Step 1: Por que escolher a Cloudflare Pages? Comparação entre plataformas

    Vantagens da Cloudflare Pages:
    • Largura de banda ilimitada e gratuita (o plano grátis da Vercel inclui 100 GB por mês e cobra US$ 40 por cada 100 GB adicional)
    • Mais de 300 data centers distribuídos pelo mundo
    • Proteção contra DDoS incluída no plano grátis, sem configuração extra

    Vantagens da Vercel:
    • Cache de build eficiente (uma segunda build pode levar apenas 3 ou 4 minutos)
    • Integração profunda com Next.js, o que faz da Vercel a melhor opção para esse framework

    Minha recomendação:
    • Blog estático em Astro → Cloudflare Pages, pela franquia de tráfego gratuita
    • Projeto com tráfego imprevisível → Cloudflare Pages, para evitar cobranças inesperadas
    • Uso intensivo de Next.js → Vercel, pela melhor experiência
    • Iterações rápidas e builds frequentes → Vercel, pelo cache de build
  2. 2

    Step 2: Implantação de site estático: primeiros passos em 5 minutos

    Se o projeto Astro for totalmente estático, como um blog, uma documentação ou um portfólio, a implantação é muito simples.

    Etapas:
    1. Entre no Cloudflare Dashboard, abra Workers & Pages e clique em Create application
    2. Selecione Connect to Git e autorize o acesso ao repositório do GitHub ou GitLab
    3. Escolha o repositório do projeto
    4. Preencha Project name e Production branch
    5. Configure Build command, normalmente npm run build, e Build output directory, normalmente dist
    6. Clique em Save and Deploy

    Depois da implantação:
    • A Cloudflare Pages fornece um domínio .pages.dev
    • Abra o link e confirme que o blog é exibido corretamente

    Problemas comuns:
    • Página em branco → verifique os logs da build e o diretório de saída
    • Falha na build → verifique o comando e a instalação das dependências
    • Estilos ausentes → verifique os caminhos dos recursos
  3. 3

    Step 3: Configuração de SSR: os três modos do adaptador

    Os três modos do adaptador SSR:

    1. Modo estático (output: 'static')
    • A forma mais prática é conectar o GitHub à Pages pelo Dashboard
    • Indicado para blogs, documentação, portfólios e outros conteúdos estáticos

    2. Modo SSR (output: 'server')
    • Use Pages com Wrangler CLI para combinar automação e flexibilidade
    • Indicado para conteúdo dinâmico renderizado no servidor

    3. Modo híbrido (output: 'hybrid')
    • Páginas estáticas usam SSG e páginas dinâmicas usam SSR
    • Permite combinar SSR e SSG no mesmo projeto
    • As páginas estáticas mantêm pontuação 95+ no Lighthouse e as dinâmicas oferecem personalização

    Configuração:
    1. Instale o adaptador @astrojs/cloudflare com npx astro add cloudflare
    2. Configure astro.config.mjs com output: 'server' ou 'hybrid' e o adaptador
    3. Implante na Cloudflare Pages por integração com GitHub ou manualmente com Wrangler CLI
  4. 4

    Step 4: Otimização do acesso na China: três opções com latência 3 vezes menor

    Opção 1 — IP selecionado (melhor resultado, mas exige manutenção periódica):
    • Use CloudflareSpeedTest para encontrar o melhor IP
    • Aponte o registro DNS A para esse IP
    • Nos testes, o tempo caiu de 5 para 1,5 segundo
    • O IP pode deixar de funcionar e precisa ser verificado periodicamente

    Opção 2 — CNAME público (grátis e simples, resultado intermediário):
    • Use um serviço público de CNAME otimizado
    • É gratuito, prático e oferece resultado intermediário
    • Indicado para quem não quer fazer manutenção manual

    Opção 3 — DNS por rota (solução mais completa, com pequeno custo):
    • Atende bem usuários dentro e fora da China
    • Tem um pequeno custo, mas oferece o melhor resultado
    • Indicado para projetos com mais tráfego e foco na experiência

    Minha recomendação:
    • Blog pessoal ou pouco tráfego → opção 1 ou 2
    • Mais tráfego e foco na experiência → opção 3
    • Em projetos comerciais, use IP selecionado com cautela; prefira a opção 3 ou aceite a velocidade padrão
  5. 5

    Step 5: Integrações do ecossistema Cloudflare e próximos estudos

    Integrações do ecossistema Cloudflare:
    • Workers KV: armazenamento chave-valor para cache e sessões
    • D1: banco SQLite executado diretamente na borda
    • R2: armazenamento de objetos comparável ao AWS S3, com uma boa franquia gratuita
    • Pages Functions: funções serverless escritas diretamente na Pages

    Todos esses serviços podem ser integrados ao Astro.

    Próximos passos:
    1. Crie uma conta da Cloudflare e teste uma implantação estática
    2. Se o acesso na China estiver lento, meça em 17ce.com antes de decidir se precisa otimizar
    3. Depois da otimização, crie um lembrete para verificar periodicamente se o IP continua válido

    A implantação é apenas o começo; o ecossistema Cloudflare oferece muitos outros recursos.

FAQ

Por que escolher a Cloudflare Pages e qual é a diferença para a Vercel?
Vantagens da Cloudflare Pages:
• Largura de banda ilimitada e gratuita (o plano grátis da Vercel inclui 100 GB por mês e cobra US$ 40 por cada 100 GB adicional. Um projeto meu apareceu numa lista popular, o tráfego disparou e a conta da Vercel chegou logo depois. Na Cloudflare Pages, a largura de banda ilimitada evita esse tipo de surpresa)
• Mais de 300 data centers no mundo (meus testes na Europa, Ásia e América tiveram baixa latência; a rede de borda da Vercel também é boa, mas tem relativamente menos nós)
• Proteção contra DDoS incluída no plano grátis, sem configuração extra

Vantagens da Vercel:
• Cache de build eficiente: em projetos com muitas imagens e dependências, uma segunda build pode levar apenas 3 ou 4 minutos, enquanto a Cloudflare Pages costuma reconstruir tudo
• Integração profunda com Next.js, que torna a Vercel a escolha natural para esse framework

Minha recomendação:
• Blog estático em Astro → Cloudflare Pages
• Tráfego imprevisível → Cloudflare Pages
• Uso intensivo de Next.js → Vercel
• Builds frequentes e iteração rápida → Vercel
Como implantar Astro na Cloudflare Pages?
Para um site estático, o processo leva cerca de 5 minutos.

Etapas:
1) Entre no Cloudflare Dashboard, abra Workers & Pages e clique em Create application
2) Selecione Connect to Git e autorize o repositório do GitHub ou GitLab
3) Escolha o repositório do projeto
4) Preencha Project name e Production branch
5) Configure Build command, normalmente npm run build, e Build output directory, normalmente dist
6) Clique em Save and Deploy

Ao terminar, a Cloudflare Pages fornece um domínio .pages.dev. Abra-o e confirme que o site funciona. Em caso de página em branco, falha na build ou estilos ausentes, verifique principalmente os logs, o diretório de saída e os caminhos dos recursos.
Como configurar SSR no Astro e quais são os três modos do adaptador?
Os três modos são:

1) Estático (output: 'static'):
• A forma mais prática é conectar o GitHub à Pages pelo Dashboard
• Indicado para blogs, documentação e portfólios

2) SSR (output: 'server'):
• Use Pages com Wrangler CLI para combinar automação e flexibilidade
• Indicado para conteúdo dinâmico renderizado no servidor

3) Híbrido (output: 'hybrid'):
• Páginas estáticas usam SSG e páginas dinâmicas usam SSR
• Permite usar SSR e SSG no mesmo projeto
• As páginas estáticas mantêm pontuação 95+ no Lighthouse e as dinâmicas oferecem personalização

Configuração:
1) Instale @astrojs/cloudflare com npx astro add cloudflare
2) Adicione output: 'server' ou 'hybrid' e o adaptador em astro.config.mjs
3) Implante na Cloudflare Pages pela integração com GitHub ou com Wrangler CLI
Como acelerar o acesso na China e quais são as três opções?
Opção 1 — IP selecionado:
• Use CloudflareSpeedTest para encontrar o melhor IP
• Aponte o registro DNS A para ele
• Nos testes, o tempo caiu de 5 para 1,5 segundo
• Verifique periodicamente, pois o IP pode deixar de funcionar

Opção 2 — CNAME público:
• Use um serviço público de CNAME otimizado
• É grátis, simples e tem resultado intermediário
• Indicado para quem não quer fazer manutenção

Opção 3 — DNS por rota:
• Otimiza o acesso dentro e fora da China
• Tem pequeno custo, mas oferece o melhor resultado
• Indicado para projetos com mais tráfego

Recomendação:
• Blog pessoal ou pouco tráfego → opção 1 ou 2
• Mais tráfego e foco na experiência → opção 3
• Projetos comerciais → use IP selecionado com cautela e prefira a opção 3 ou a velocidade padrão

Se ainda não começou, crie uma conta da Cloudflare, teste a implantação estática, meça em 17ce.com e só então decida se precisa otimizar.
Qual é a diferença entre Cloudflare Pages e Workers? Qual devo escolher?
Workers é a plataforma de computação serverless da Cloudflare, capaz de executar JavaScript na borda. Pages pode ser entendida como Workers mais ferramentas automatizadas de build: usa Workers por baixo, mas acrescenta integração com Git e implantação automática.

Em 2025, a Cloudflare passou a recomendar Workers para novos projetos por oferecer mais flexibilidade e controle. Para usuários de Astro, porém, não é necessário seguir isso de forma rígida.

Na prática:
• Pages: conecte o repositório do GitHub e cada push inicia uma build automaticamente; é a opção simples
• Workers: exige implantação manual com Wrangler CLI e configuração de wrangler.jsonc, mas dá mais controle sobre variáveis e bindings de KV

Para Astro:
• Site estático (output: 'static') → Pages com GitHub pelo Dashboard
• Site SSR (output: 'server' ou 'hybrid') → ambos funcionam, mas Pages com Wrangler CLI combina automação e flexibilidade

Na primeira implantação, comece pela integração Git da Pages e considere Wrangler CLI quando já estiver familiarizado.
Quais outros recursos do ecossistema Cloudflare podem ser integrados?
O ecossistema inclui Workers KV para armazenamento chave-valor, cache e sessões; D1, um banco SQLite executado na borda; R2, armazenamento de objetos comparável ao AWS S3; e Pages Functions, para funções serverless dentro da Pages. Todos podem ser integrados ao Astro. A implantação é apenas o primeiro passo.

18 min de leitura · Publicado em: 3 dez 2025 · Atualizado em: 4 set 2026

Comentários

Entre com GitHub para comentar

Easton BlogEaston Blog