Astro : rendu et déploiement

Statique ou serveur

Mode	`output`	Résultat	Usage
Statique (défaut)	`'static'`	Fichiers HTML dans `dist/`	Sites de contenu, documentation, vitrines
Serveur	`'server'`	Un serveur Node.js à exécuter	Pages dépendant de la requête (sessions, base de données)
Mixte	`'static'` + `export const prerender = false` sur certaines pages	Statique avec quelques pages dynamiques	Presque tout statique, un formulaire ou une API

Le mode statique est le plus simple, le plus rapide et le plus sûr : aucun processus à superviser sur le serveur.

Déployer un site statique

npm run build          # produit dist/
npm run preview        # contrôle local

Copier dist/ dans le dossier servi par le serveur web :

rsync -az --delete --dry-run dist/ utilisateur@serveur.exemple.com:/var/www/monsite/
rsync -az --delete dist/ utilisateur@serveur.exemple.com:/var/www/monsite/

Toujours lire la sortie du --dry-run : les lignes deleting indiquent les fichiers qui seront supprimés. Un script scripts/deploy.sh qui lit les paramètres depuis un .env non versionné évite les erreurs (voir SSH : transferts). Pour automatiser le déploiement après chaque envoi : Gitea Actions : exemples.

Caddy pour un site statique

exemple.com {
    root * /var/www/monsite
    encode zstd gzip
    file_server

    @assets path /_astro/*
    header @assets Cache-Control "public, max-age=31536000, immutable"

    header {
        Strict-Transport-Security "max-age=31536000"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        -Server
    }

    handle_errors {
        @notfound `{err.status_code} == 404`
        rewrite @notfound /404.html
        file_server
    }
}

www.exemple.com {
    redir https://exemple.com{uri} permanent
}

/_astro/* : fichiers dont le nom contient une empreinte du contenu, donc cachables « pour toujours ».
handle_errors renvoie 404.html avec le code 404 (important pour le référencement).
Les autres pages ne doivent pas être mises en cache longtemps.

Voir Caddy : exemples réutilisables et Nginx : performances et journaux.

Vérifier après déploiement

curl -sI https://exemple.com/ | head -5
curl -sI https://exemple.com/page-inexistante/ | head -1       # HTTP/2 404
curl -s  https://exemple.com/sitemap-index.xml | head -5
curl -sI https://www.exemple.com/ | head -3                    # redirection vers exemple.com

Mode serveur avec l’adaptateur Node

npx astro add node

astro.config.mjs :

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

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

npm run build
HOST=127.0.0.1 PORT=4321 node dist/server/entry.mjs

Le serveur est lancé par node dist/server/entry.mjs ; HOST et PORT fixent l’adresse d’écoute. Écouter sur 127.0.0.1 et publier derrière un reverse proxy.

Service systemd

/etc/systemd/system/monsite.service :

[Unit]
Description=Site Astro (mode serveur)
After=network.target

[Service]
User=monsite
Group=monsite
WorkingDirectory=/srv/monsite/app
Environment=HOST=127.0.0.1
Environment=PORT=4321
EnvironmentFile=/etc/monsite.env
ExecStart=/usr/bin/node dist/server/entry.mjs
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now monsite
curl -I http://127.0.0.1:4321/

Reverse proxy Caddy : reverse_proxy 127.0.0.1:4321. Voir systemd : écrire un service, Node.js : mise en production et, pour plusieurs instances, PM2.

Pages dynamiques dans un site statique

---
export const prerender = false; // cette page est rendue à la demande
const q = Astro.url.searchParams.get('q');
---

<p>Recherche : {q}</p>

Avec output: 'static' et un adaptateur installé, seules les pages marquées prerender = false sont rendues à la demande.

Variables d’environnement en production

Variables PUBLIC_* : intégrées à la compilation dans le JavaScript client (changer la valeur impose un nouveau build).
Variables privées : lues à l’exécution en mode serveur (/etc/monsite.env, droits 640) ou à la compilation en statique.
Aucun secret dans une variable PUBLIC_ ni dans le dépôt.

Liste de contrôle

site défini, trailingSlash cohérent.
404.html servie avec le code 404.
Cache long sur /_astro/*, court sur le HTML.
Compression (encode) et HTTPS.
robots.txt, sitemap, balises canoniques.
Droits de lecture du dossier servi par le serveur web.

Dépannage

Symptôme	Piste
Toutes les pages inexistantes répondent 200	`handle_errors` absent : la 404 est servie sans code d’erreur
Les anciennes pages restent affichées	Cache du navigateur ou du serveur sur le HTML
`403` sur les fichiers	Droits du dossier servi (`chmod 755`/`644`)
`502` en mode serveur	Service arrêté : `systemctl status monsite`, journal
`No adapter installed`	`output: 'server'` sans adaptateur : `npx astro add node`
Variable `PUBLIC_` obsolète	Reconstruire le site
Liens cassés après déploiement	`site` ou `base` incorrects

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Astro. Le chemin de node (which node) dépend de l’installation de Node.js.

Pour aller plus loin

Déployer un site Astro, Adaptateur Node
Suite : Dépannage