Astro Deployment

6 Kernkonzepte

Die wichtigsten Deployment-Strategien für Astro-Projekte: Build & Optimierung · Vercel · Netlify · Cloudflare Pages · Docker · Umgebungsvariablen Astro-Seiten können als statische Dateien, serverseitig gerendert (SSR) oder hybrid ausgeliefert werden. Diese Cheatsheet fasst die wichtigsten Deployment-Methoden und Plattformen zusammen.

Build & Optimierung – astro build

astro build · dist/ · optimization

npm run build # oder npx astro build # Ausgabe im dist/-Verzeichnis npm run preview # Vorschau der gebauten Seite

Astro Build erzeugt das produktionsreife Bundle im dist/-Verzeichnis. Der Build-Prozess optimiert automatisch Assets, minimiert CSS/JS und generiert statische Seiten.

Build-Optionen in astro.config.mjs

Option	Beschreibung
outDir: './dist'	Ausgabeverzeichnis (Standard)
publicDir: './public'	Verzeichnis für statische Assets
build.assetsPrefix	CDN-Präfix für Assets
build.format: 'file'	Datei-basierte Ausgabe (Standard)
build.format: 'directory'	Verzeichnis-basierte Ausgabe
build.inlineStylesheets: 'auto'	Stylesheets automatisch inlinen
compressHTML: true	HTML komprimieren (Standard)

Beispiele

// astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({

outDir: './dist',

publicDir: './public',

build: {

format: 'file',

inlineStylesheets: 'auto',

assetsPrefix: 'https://cdn.example.com',

compressHTML: true,

});

// package.json Scripts

"scripts": {

"dev": "astro dev",

"build": "astro build",

"preview": "astro preview",

"deploy": "npm run build && netlify deploy --prod"

}

Tipp: Verwenden Sie npm run preview, um die gebaute Seite lokal zu testen – das ist besonders vor dem Deployment wichtig.

Vercel – Deployment mit Vercel

vercel · @astrojs/vercel

# Installation npm install @astrojs/vercel # Deployment npx vercel npx vercel --prod

Vercel ist die empfohlene Plattform für Astro-Deployments. Die offizielle Integration unterstützt statische Seiten und serverseitiges Rendering (SSR) mit Serverless Functions.

Beispiele

// astro.config.mjs

import { defineConfig } from 'astro/config';

import vercel from '@astrojs/vercel';

export default defineConfig({

output: 'static', // oder 'server' für SSR

adapter: vercel({

edgeRuntime: 'edge', // oder 'nodejs'

analytics: true, // Vercel Analytics aktivieren

}),

});

// vercel.json (optional)

{

"installCommand": "npm install",

"buildCommand": "npm run build",

"outputDirectory": "dist"

}

Tipp: Vercel erkennt Astro automatisch. Für SSR müssen Sie den output: 'server' Modus und den vercel()-Adapter konfigurieren.

Netlify – Deployment mit Netlify

netlify.toml · @astrojs/netlify

# Installation npm install @astrojs/netlify # Deployment netlify deploy --prod

Netlify ist eine beliebte Plattform für statische Sites und unterstützt Astro nativ. Die Integration bietet sowohl statische als auch serverseitige Rendering-Optionen.

Beispiele

// astro.config.mjs

import { defineConfig } from 'astro/config';

import netlify from '@astrojs/netlify';

export default defineConfig({

output: 'static', // oder 'server' für SSR

adapter: netlify({

edge: false, // Netlify Edge Functions

dist: new URL('./dist', import.meta.url),

}),

});

// netlify.toml

[build]

command = "npm run build"

publish = "dist"

[build.environment]

NODE_VERSION = "18"

Tipp: Netlify erkennt astro build automatisch. Für SSR benötigen Sie den netlify-Adapter und output: 'server'.

Cloudflare Pages – Deployment mit Cloudflare

@astrojs/cloudflare

# Installation npm install @astrojs/cloudflare # Deployment über Cloudflare Dashboard

Cloudflare Pages bietet ein schnelles und kostengünstiges Hosting für Astro-Projekte mit globalem CDN und Unterstützung für Edge Functions.

Beispiele

// astro.config.mjs

import { defineConfig } from 'astro/config';

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({

output: 'server', // Cloudflare Pages benötigt 'server'

adapter: cloudflare({

mode: 'advanced', // oder 'directory'

routes: {

strategy: 'include',

include: ['/*'],

exclude: ['/static/*'],

}),

});

// wrangler.toml (optional)

name = "my-astro-site"

compatibility_date = "2023-01-01"

Tipp: Cloudflare Pages benötigt für SSR den output: 'server'-Modus. Statische Seiten funktionieren ohne Adapter, direkt mit astro build.

Docker – Containerisierung mit Node.js

Dockerfile · node:alpine

# Dockerfile FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build CMD ["npm", "run", "preview"]

Docker ermöglicht die Containerisierung von Astro-Anwendungen für konsistente Deployments in jeder Umgebung – ideal für eigene Server oder Kubernetes.

Beispiele

# Multi-Stage Dockerfile

# Build-Stage

FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json .

RUN npm ci

COPY . .

RUN npm run build

# Production-Stage

FROM node:20-alpine AS runner

WORKDIR /app

COPY --from=builder /app/dist ./dist

COPY --from=builder /app/package.json ./

COPY --from=builder /app/node_modules ./node_modules

EXPOSE 4321

CMD ["npm", "run", "preview", "--host"]

# .dockerignore

node_modules/

dist/

.env

.git/

# Build & Run

docker build -t my-astro-site .

docker run -p 4321:4321 my-astro-site

Tipp: Verwenden Sie ein Multi-Stage Dockerfile, um die Build- und Runtime-Environment zu trennen – das reduziert die Image-Größe erheblich.

Umgebungsvariablen – .env · import.meta.env

.env · .env.production · PUBLIC_

# .env (lokal) PUBLIC_API_URL=https://api.example.com DATABASE_URL=postgresql://user:pass@localhost/db # In Komponente const apiUrl = import.meta.env.PUBLIC_API_URL;

Umgebungsvariablen in Astro werden über import.meta.env bereitgestellt. Variablen mit PUBLIC_-Präfix sind auch im Client verfügbar.

Umgebungsvariablen in Astro

Datei	Verwendung
.env	Lokale Entwicklung (wird nicht eingecheckt)
.env.production	Produktionsumgebung
.env.staging	Staging-Umgebung
PUBLIC_*	Im Client verfügbare Variablen
SERVER_*	Nur serverseitig (nicht im Client)

Beispiele

# .env

PUBLIC_SITE_TITLE=Meine Astro-Seite

PUBLIC_API_URL=https://api.example.com

DATABASE_URL=postgresql://user:pass@localhost:5432/db

SECRET_KEY=mein-geheimer-schluessel

// In einer Astro-Komponente

---

// Client-seitig verfügbar (PUBLIC_*)

const title = import.meta.env.PUBLIC_SITE_TITLE;

const apiUrl = import.meta.env.PUBLIC_API_URL;

// Nur serverseitig verfügbar

const dbUrl = import.meta.env.DATABASE_URL;

const secret = import.meta.env.SECRET_KEY;

---

// In einem React/Vue/Svelte-Component

export default function MyComponent() {

// Nur PUBLIC_* Variablen sind hier verfügbar

const apiUrl = import.meta.env.PUBLIC_API_URL;

// DATABASE_URL wäre hier undefined

}

// Vercel/Netlify: Umgebungsvariablen im Dashboard setzen

# Netlify: netlify.toml

[build.environment]

PUBLIC_API_URL = "https://api.example.com"

Tipp: Verwenden Sie PUBLIC_ für alle Variablen, die im Client benötigt werden. Alle anderen Variablen bleiben sicher auf dem Server und werden nicht an den Client gesendet.

Astro Deployment im Überblick

build astro build
dist/ Verzeichnis

Vercel @astrojs/vercel
SSR, Edge

Netlify @astrojs/netlify
SSR, Functions

Cloudflare @astrojs/cloudflare
Edge, CDN

Docker Container
Eigene Server

.env Umgebungsvariablen
PUBLIC_*, import.meta.env

Quick Summary

build

Build & Optimierung

Vercel

Vercel Deployment

Netlify

Netlify Deployment

Cloudflare

Cloudflare Pages

Docker

Containerisierung

.env

Umgebungsvariablen

npm run build · npx vercel --prod · netlify deploy --prod · docker build -t my-site .