Para publicar Astro na Cloudflare, primeiro descubra se o projeto gera páginas estáticas ou precisa renderizar conteúdo a cada solicitação. Um site pré-renderizado pode entregar arquivos estáticos; um projeto com SSR usa o runtime e o adapter da Cloudflare. Build local, preview remoto e deploy são etapas diferentes.

Este guia resume a documentação oficial consultada em 27 de outubro de 2026. Os comandos e caminhos abaixo não foram executados neste projeto; confira a versão do Astro, os scripts e os bindings do seu repositório antes de seguir. Para entender a diferença entre DNS, proxy e hospedagem, veja também o guia sobre como Cloudflare funciona, publicado antes deste artigo.

1. Escolha entre site estático e SSR

• Pré-renderizado — Como funciona: Astro produz HTML e arquivos durante o build. A hospedagem serve esses assets sem executar a aplicação para cada página. — Quando pode fazer sentido: Conteúdo que pode ser gerado antes da visita, como páginas institucionais e parte dos blogs.

• SSR sob demanda — Como funciona: Um runtime executa a aplicação para montar respostas quando chegam solicitações. — Quando pode fazer sentido: Rotas que dependem de autenticação, sessão ou dados calculados por solicitação.

Não adicione SSR apenas por parecer mais moderno. Ele traz configuração e execução no servidor. Mas também não transforme em arquivo público uma página que depende de dados privados ou atualizados em tempo real.

2. Comece em um ambiente local

Para iniciar um projeto novo, o guia atual da Cloudflare usa o Create Cloudflare CLI com Astro:

npm create cloudflare@latest -- meu-site --framework=astro

O assistente cria a estrutura e pode oferecer uma etapa de publicação. Se você quer apenas preparar ou estudar o projeto, não confirme o deploy nessa etapa. Depois de entrar na pasta criada, a documentação apresenta npm run dev para desenvolvimento local; confira o package.json, pois projetos existentes podem usar outros scripts ou outro gerenciador de pacotes.

Antes de alterar um site existente, leia o lockfile, package.json, astro.config.* e wrangler.jsonc ou wrangler.toml, se houver. Não substitua a configuração de um site em funcionamento por um exemplo genérico: nomes de binding, adapter, diretório de assets e compatibilidade dependem da arquitetura atual.

3. Workers ou Pages?

Cloudflare mantém guias oficiais para Astro tanto em Workers quanto em Pages. Workers oferece publicação de Static Assets e suporte a aplicações Astro com SSR; Pages tem seu próprio processo de build e implantação. A escolha deve preservar o que já funciona e considerar renderização, bindings, fluxo de publicação, domínio e manutenção.

• É totalmente pré-renderizado — Investigue primeiro…: Se pode publicar assets estáticos sem adicionar um Worker ou adapter desnecessário.

• Usa SSR ou lógica no servidor — Investigue primeiro…: O adapter `@astrojs/cloudflare`, os bindings e os caminhos de runtime necessários.

• Já está em Pages — Investigue primeiro…: O guia e o pipeline atuais do projeto antes de migrar. Não mude de plataforma só para seguir um tutorial novo.

Se o domínio estiver na Cloudflare, isso por si só não revela onde os arquivos do Astro são servidos. DNS e proxy são uma parte diferente da hospedagem; veja o guia de DNS, proxy e cache na Cloudflare.

4. Faça a verificação antes do deploy

Uma sequência prudente para um projeto existente é:

1. Instale dependências usando o gerenciador indicado pelo lockfile.

2. Rode o script de desenvolvimento e confira as rotas principais no navegador.

3. Execute o build local definido no package.json.

4. Confira páginas de erro, busca, formulários, imagens, metadados e rotas dinâmicas.

5. Confirme que secrets e dados privados não foram incluídos no repositório ou nos arquivos públicos.

6. Revise bindings, variáveis, adapter, ambiente e domínio de destino antes de publicar.

7. Documente como reverter a versão caso o deploy cause um problema.

Um comando de deploy não é uma verificação local. A documentação atual informa que o Wrangler pode detectar um projeto Astro existente sem configuração Wrangler e gerar a configuração necessária ao publicar. Por isso, wrangler deploy pode alterar o ambiente remoto: não use esse comando como teste casual.

5. Avalie consumo e limites

Segundo a documentação atual da Cloudflare, solicitações que retornam Static Assets são gratuitas e ilimitadas; solicitações que executam o script Worker — por exemplo, conteúdo SSR — seguem as regras de cobrança de Workers. Essa diferença não torna todo o projeto automaticamente sem limites: chamadas ao Worker, bindings e outros produtos têm regras próprias. Confirme os limites vigentes da conta e evite publicar repetidamente só para validar CSS ou conteúdo que pode ser conferido localmente.

Um preview remoto também usa uma conta e pode envolver recursos. Veja o que o comando selecionado fará antes de confirmar uma implantação ou criar recursos. Para páginas estáticas, uma etapa de build local costuma ser suficiente para encontrar erros de compilação; ela não comprova, sozinha, que bindings e domínio estão corretos em produção.

Checklist final

• O modelo escolhido (estático ou SSR) corresponde ao que as rotas realmente precisam.

• O build local termina sem erro e as páginas importantes foram abertas.

• A configuração existente de Astro/Wrangler foi revisada antes de ser alterada.

• Secrets não aparecem em arquivos públicos ou no bundle do navegador.

• O destino, os bindings e o plano de reversão foram conferidos antes do deploy.

• Uma mudança no DNS não foi confundida com a publicação dos arquivos do site.

Perguntas frequentes

Todo site Astro precisa de um Worker?

Não. Um projeto totalmente estático pode publicar arquivos pré-renderizados. SSR e lógica executada a cada solicitação precisam de um runtime configurado.

Posso testar com wrangler deploy?

Esse comando publica. Faça primeiro o desenvolvimento e o build local; só execute deploy quando souber o projeto e o ambiente que serão alterados.

Astro só funciona em Cloudflare Workers?

Não. A Cloudflare mantém guias de Astro para Workers e Pages. Compare o fluxo atual do projeto e suas necessidades antes de migrar.