A resposta curta
Para fazer deploy de um site Astro, comece pelo modo de renderização. Se o HTML pode ser gerado no build, hospede os arquivos de dist. O preset Astro da Unbroker serve esse build. Se uma página precisa dos dados do visitante em cada request, adicione um adaptador de servidor e publique essa saída como serviço Node.js ou com um Dockerfile.
Deixe o preset estático apontando para os arquivos gerados. Configure site com a origem pública que você vai publicar, para que as URLs canônicas e o sitemap usem esse valor. A página do produto é Deploy de Astro. Os passos estão em Publicar um site Astro.
Comece pelo modo de renderização
A pergunta de hospedagem é quais páginas já existem antes de alguém pedir. O output padrão do Astro é 'static': as páginas são pré-renderizadas no build, e o resultado é um site estático quando nenhuma página sai desse modo. output: 'server' renderiza as páginas no servidor por padrão. A renderização sob demanda, também chamada de renderização no servidor, precisa de um adaptador. A referência é a configuração do Astro e on-demand rendering.
| Saída estática | Adaptador de servidor | |
|---|---|---|
| O que o build grava | HTML, CSS e JavaScript em dist, salvo se você mudar outDir | Os arquivos de servidor que esse adaptador precisa. É outra saída, diferente do preset estático. |
| O que roda em produção | Um servidor de arquivos. O preset Astro da Unbroker faz isso. | O processo do adaptador: um serviço Node.js ou um Dockerfile na Unbroker. |
| Quando cabe | Páginas de marketing, docs e blogs cujo HTML pode ser gerado no build. | Uma página que precisa dos dados de um usuário logado, ou de outros dados do request, em cada visita. |
Você pode manter o modo estático padrão e tirar uma rota com export const prerender = false depois de instalar um adaptador. O resto do site continua estático. output: 'server' troca o padrão. O guia do Astro pede para começar com 'static' até que a maior parte das páginas precise ser renderizada sob demanda, e diz que 'server' não acrescenta recursos: só muda quais páginas renderizam sob demanda por padrão.
Hospedar a saída estática do Astro
Confirme o build com o gerenciador de pacotes e o lockfile que o repositório já usa. O exemplo do guia da Unbroker é npm ci e depois npm run build. Um script build padrão do Astro roda astro build. Por padrão isso grava dist/. outDir muda o diretório. O guia de deploy do Astro lista o comando de build como astro build ou npm run build, e o diretório de publicação como dist. Veja Fazer deploy do seu site Astro.
No Cloud, crie um serviço de repositório e escolha Astro. Deixe o comando de build no script de build do projeto e o diretório de saída em dist, salvo se você tiver mudado o diretório de saída do Astro.
Abra a URL do serviço. Peça uma página aninhada direto, atualize e siga os links de imagens e folhas de estilo. Se faltarem assets, confira o diretório de saída e qualquer base configurado. base é o caminho que o Astro usa como raiz das páginas e dos assets. Se só a home existir, olhe as rotas geradas. Acrescentar um comando de servidor a um serviço estático não cria as páginas que faltam.
astro preview sobe um servidor local para o diretório estático já gerado. A CLI do Astro diz que ele serve para conferir o build antes do deploy, e que não foi feito para rodar em produção. O guia da Unbroker diz o mesmo para o preset estático: o preview local confere a saída, e o preset é o servidor de produção desses arquivos. A referência do comando é astro preview.
Quando você precisa de um adaptador de servidor
Uma página que exige os dados de um usuário logado na hora do request não se resolve com HTML estático. Adicione um adaptador para o runtime que vai renderizar essas rotas. O Astro mantém adaptadores oficiais para Node.js, Netlify, Vercel e Cloudflare. Na Unbroker, publique essa saída como serviço Node.js ou com um Dockerfile, e siga as instruções de build e de start do adaptador. O preset estático do Astro serve um site estático já gerado, então a saída de servidor vai pelo Node.js ou pelo Dockerfile.
A tabela de planos inclui Node.js gerenciado no Free e lista builds com Dockerfile como disponíveis no Pro. O guia do Astro nomeia o preset estático como o caminho que roda no Free. As linhas estão em Plans.
Astro estático e uma API separada
Se só algumas interações precisam de backend, manter o Astro estático e somar uma API separada pode ser mais simples. A configuração pública do frontend fica visível para o visitante. O Astro deixa variáveis com prefixo PUBLIC_ disponíveis para o código do cliente via import.meta.env. A Unbroker escolhe os prefixos públicos de build, inclusive PUBLIC_, VITE_ e NEXT_PUBLIC_, antes do build. Um valor que entra no bundle que o visitante baixa é público, mesmo que você tenha digitado em Variables.
Coloque as credenciais do banco e os outros segredos no serviço da API. Variáveis privadas ficam só em runtime, exceto as credenciais documentadas de um registro de pacotes. Como os escopos funcionam está em Variáveis de ambiente e segredos.
Faça deploy da API primeiro e confirme um endpoint na URL pública dela. Aponte a variável pública do frontend para essa origem e depois gere o build do frontend. Uma mudança num valor embutido no bundle pede um build novo. Configure o CORS da API para a origem exata do frontend. Um hostname privado do projeto não é alcançável pelo navegador do visitante. Chamadas do navegador precisam de uma rota pública. O passo a passo está em Publicar um frontend e uma API juntos. CORS, cookies e um preview que não deve chamar a API de produção estão em deploy de um frontend e uma API separados. O que o Free pode rodar para essa API está em Hospedagem de backend grátis.
Use a URL real de produção
Configure o site do Astro com a URL final publicada. O Astro usa essa URL completa para gerar o sitemap e as URLs canônicas no build. A opção é site. Se o site é servido sob um caminho, base é o ajuste correspondente para páginas e assets.
Um domínio próprio é um passo posterior, e exige Pro. Quando estiver pronto, confira se as URLs canônicas e as imagens sociais usam essa origem. O Astro documenta site para o sitemap e as URLs canônicas. O guia da Unbroker também pede para verificar as imagens sociais contra a origem de produção, e não contra um hostname de preview. O DNS e o certificado estão em Domínio próprio e HTTPS.
Mantenha o hostname que a Unbroker entrega. Ele serve para distinguir um problema de deploy de um problema de DNS.
Como isso funciona na Unbroker
O preset Astro serve um site estático já gerado. Ele está no Free e no Pro. No Free ele roda com Serverless: um serviço ocioso vai a zero e acorda no próximo request. O primeiro request depois de dormir pode demorar mais enquanto a aplicação inicia. Os apps do Pro não dormem por inatividade. Eles dormem só quando você liga o Serverless. Domínios próprios e TLS gerenciado estão no Pro.
Crie um serviço de repositório, selecione Astro e configure o comando de build e o diretório de saída. O Pro custa $25 por mês com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível ficar abaixo do crédito, a cobrança mensal continua o preço do plano. Os valores atuais estão em preços e em Plans.
A página do produto é Deploy de Astro. Qual push produziu a revisão está em Deploy com git push.
Checklist
- Decida se cada página pode ser gerada no build.
- Nesse caso, deixe a saída estática padrão e gere o build com o script de build do projeto.
- Confirme que
dist, ou o seuoutDir, contém as páginas e os assets que você espera. - Na Unbroker, escolha o preset Astro e configure o comando de build e o diretório de saída.
- Abra uma página aninhada, atualize e siga uma imagem e uma folha de estilo.
- Use
astro previewpara conferir o build localmente. Deixe esse comando fora do start de produção. - Se uma página precisa dos dados do visitante em cada request, adicione um adaptador de servidor e publique essa saída como Node.js ou Dockerfile.
- Coloque os segredos na API. Limite os valores
PUBLIC_à configuração que o visitante pode ver, e configure o CORS com a origem do frontend. - Configure
sitecom a origem pública real. Depois de um domínio próprio, confira as URLs canônicas, o sitemap e as imagens sociais. Mantenha o hostname da Unbroker. Domínios próprios exigem Pro.
Perguntas frequentes
Preciso de um servidor para hospedar um site Astro?
Não, quando o HTML pode ser gerado no build. A saída padrão do Astro é estática, e o preset Astro da Unbroker serve esse build no Free e no Pro. Uma página que precisa renderizar em cada request, por exemplo com os dados de um usuário logado, precisa de um adaptador de servidor. Essa saída é publicada como serviço Node.js ou com um Dockerfile. O preset estático fica para os arquivos gerados.
Qual é a diferença entre a saída estática do Astro e a renderização no servidor, para a hospedagem?
A saída estática pré-renderiza as páginas no build, e você hospeda esses arquivos. A renderização no servidor, que o Astro também chama de on-demand rendering, executa um adaptador quando a rota é pedida. output: 'static' é o padrão. output: 'server' torna a renderização por request o padrão. Depois de adicionar um adaptador, uma rota pode sair do pré-render com prerender = false, e o resto do site continua estático. A referência é o guia de on-demand rendering do Astro.
Para qual diretório o Astro faz o build?
Para dist, a menos que você mude outDir. O guia de deploy do Astro lista dist como diretório de publicação e o comando de build como astro build ou npm run build. Na Unbroker, deixe o diretório de saída do preset Astro em dist, salvo se você tiver mudado, e o comando de build no script de build do projeto.
Posso usar astro preview em produção?
Não. astro preview sobe um servidor local para o diretório estático já gerado, para você conferir esse build. A CLI do Astro diz que o comando não foi feito para rodar em produção. O guia da Unbroker diz o mesmo para o preset estático: o preview local confere o build, e o preset é o que serve esses arquivos.
Posso hospedar um site Astro no plano Free da Unbroker?
Sim, com o preset estático do Astro. No Free ele roda com Serverless: um serviço ocioso vai a zero e acorda no próximo request. Domínios próprios exigem Pro. A renderização no servidor é publicada como serviço Node.js ou com um Dockerfile. Node.js gerenciado está no Free. Builds com Dockerfile são Pro. O guia do Astro nomeia o preset estático como o caminho do Free.
Domínios próprios funcionam no Free?
Não. A tabela de planos lista domínios próprios e TLS gerenciado como indisponíveis no Free e disponíveis no Pro. O Pro custa $25 por mês com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível ficar abaixo do crédito, a cobrança mensal continua o preço do plano. Veja preços e Plans.
Como faço deploy na Unbroker de um site Astro com adaptador de servidor?
Adicione o adaptador e publique a saída dele como serviço Node.js ou com um Dockerfile. Siga as instruções de build e de start desse adaptador. O preset estático do Astro serve arquivos gerados, então a saída de servidor vai pelo Node.js ou pelo Dockerfile. Builds com Dockerfile exigem Pro. Node.js gerenciado está incluído no Free. Os adaptadores oficiais do Astro incluem um para Node.js.
Onde ficam as chaves de API num site Astro?
No serviço de backend, não no código do cliente. O Astro deixa variáveis com prefixo PUBLIC_ disponíveis para o navegador, e a Unbroker escolhe esse prefixo, junto com VITE_ e NEXT_PUBLIC_, como variável pública de build. Um valor que entra no bundle que o visitante baixa é público. Variáveis privadas ficam só em runtime, exceto as credenciais documentadas de um registro de pacotes. A divisão está no guia de frontend e API, e os escopos em Variáveis de ambiente e segredos.
Por que minhas URLs canônicas apontam para um hostname de preview?
As URLs canônicas e o sitemap saem do valor site do Astro. Defina site com a origem pública final e gere o build de novo. Se elas ainda mostrarem um hostname de preview, essa é a origem configurada naquele build. Quando o domínio próprio estiver pronto, confira as URLs canônicas, o sitemap e as imagens sociais contra a origem de produção. Mantenha o hostname da Unbroker para separar um problema de DNS do deploy. Domínios próprios exigem Pro.