Como alojar um site Astro: opções estáticas e SSR

O Astro pode entregar o seu site de duas formas muito diferentes, e a que escolher decide onde e como o aloja. Por defeito, o Astro constrói uma pasta de simples ficheiros HTML, CSS e JS — ficheiros que qualquer alojamento estático pode servir. Mas o Astro também pode correr num servidor, renderizando páginas a pedido (SSR) para coisas como autenticação, formulários ou dados por pedido. Este guia explica ambos os modos de saída, os comandos de build por detrás deles, como se encaixam os adaptadores, e como escolher um alojamento para cada um.

Estático vs servidor: a decisão central

Toda escolha de alojamento para o Astro nasce de uma pergunta: o seu site precisa de um servidor em execução no momento do pedido?

• Estático (o modo por defeito). As páginas são renderizadas uma vez, no momento do build, em ficheiros HTML. Não há processo de servidor — carrega a pasta construída para um CDN ou alojamento estático e este serve os ficheiros. O mais rápido, o mais barato, o mais simples. Ideal para blogues, documentação, sites de marketing e a maioria dos sites de conteúdo.
• Servidor / SSR. As páginas são renderizadas por pedido por um processo Node (ou edge). Necessário quando o conteúdo depende do pedido: utilizadores autenticados, processamento de formulários, personalização ao momento, ou dados que têm de estar frescos a cada carregamento.

Também pode misturar os dois: manter o site na sua maioria estático e optar por renderizar a pedido rotas específicas. A ideia é renderizar estaticamente onde puder, e pagar por um servidor apenas onde realmente precisar dele.

Os comandos de build

Seja qual for o modo, o fluxo de trabalho são os mesmos dois comandos — instalar, depois construir:

# install dependencies
npm install

# produce the production build
npm run build

# preview the production build locally before deploying
npm run preview

Por defeito, npm run build escreve um site estático na pasta dist/. Essa pasta é todo o seu site implementável em modo estático — não há mais nada para executar.

Configurar o modo de saída

Controla o modo em astro.config.mjs. O estático é o modo por defeito, por isso uma configuração mínima não precisa de nada de especial. Para renderizar no servidor, adiciona um adaptador — um pequeno pacote que ensina o Astro a correr numa plataforma específica (Node, ou um runtime edge/serverless):

// astro.config.mjs — server (SSR) output with the Node adapter
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Com o adaptador Node standalone, npm run build produz um ponto de entrada de servidor que inicia como qualquer app Node:

# after building with the Node adapter
node ./dist/server/entry.mjs

Se só precisa de um punhado de rotas dinâmicas, mantenha a saída estática por defeito e retire páginas individuais do prerender em vez de mudar o site inteiro para modo servidor:

---
// src/pages/dashboard.astro — render this page per request
export const prerender = false;
---

Escolher um alojamento por modo

Alojamento estático

Para a saída estática só precisa de algures onde servir o conteúdo de dist/ por HTTPS, idealmente a partir de um CDN. As definições de build/publicação são simples:

Build command:    npm run build
Publish/output:   dist

Muitas plataformas fazem isto — alojamentos estáticos geridos, armazenamento de objetos atrás de um CDN, ou um alojamento de uso geral que consiga servir uma pasta. Como não há servidor a manter vivo, o alojamento estático é barato e sem esforço de escalar. Alojar em infraestrutura europeia é uma boa escolha aqui quando o seu público ou as suas necessidades de residência de dados apontam nessa direção.

Alojamento de servidor (SSR)

O SSR precisa de um runtime que mantenha um processo vivo. Duas vias gerais:

• Um alojamento Node / VPS. Com o adaptador Node constrói um servidor standalone e executa-o como qualquer serviço Node. Um VPS dá-lhe controlo total sobre o processo, o ambiente e a escalabilidade — útil se já executa outros serviços lá.
• Serverless / edge. Adaptadores específicos de plataforma empacotam a sua app para correr como funções. Menos para gerir, mas fica preso ao modelo dessa plataforma.

Uma forma simples de executar o build Node no seu próprio servidor é um gestor de processos para que reinicie em caso de falha ou reinício:

# example: keep the Astro Node server running with PM2
npm install -g pm2
pm2 start ./dist/server/entry.mjs --name astro-site
pm2 save

Referência rápida

Necessidade	Modo	O que alojar
Blogue, documentação, marketing, conteúdo	Estático (por defeito)	A pasta dist/ num CDN/alojamento estático
Na sua maioria estático, algumas rotas dinâmicas	Estático + prerender = false por página	Um alojamento/adaptador que suporte rotas a pedido
Auth, formulários, dados por pedido em todo o lado	Servidor (SSR)	Um runtime Node / VPS ou plataforma serverless

Como decidir

Comece estático — é o modo por defeito por uma razão: mais barato, mais rápido e mais simples de alojar. Só recorra ao adaptador de servidor quando um requisito real (estado autenticado, processamento de formulários, dados sempre frescos) obrigar à renderização por pedido, e mesmo então considere retirar apenas essas rotas do prerender em vez de correr o site inteiro num servidor. Adapte o alojamento ao modo com que acaba: um alojamento estático apoiado em CDN para os ficheiros construídos, ou um VPS com capacidade Node / plataforma serverless quando genuinamente precisar de um servidor.