Eine bereitgestellte Site weiterentwickeln

EmDash speichert Kollektionen, Felder und Taxonomien in der Datenbank, neben dem Inhalt selbst. Das Deployen von neuem Code ändert sie nicht: Ein Deploy ersetzt den Worker- (oder Server-) Code, während das Schema und der Inhalt in der Datenbank unverändert bleiben. Diese Seite erklärt, wie man das Inhaltsmodell einer bereits bereitgestellten Site ändert, wobei Cloudflare D1 als laufendes Beispiel dient. Die gleichen Workflows gelten für die anderen Datenbankoptionen.

Was was ändert

Eine Site durchläuft vier verschiedene Workflows. Jeder betrifft eine andere Schicht:

Workflow	Was sich ändert	Wie
Inhaltsbearbeitung	Einträge, Medien, Einstellungen	Admin-Panel oder Inhalts-API
Code-Deploy	Templates, Konfiguration, EmDash-Version	`wrangler deploy` — lässt Schema und Inhalt unberührt
Erstmalige Initialisierung	Alles, von leer	Migrationen + Seed-Datei + Setup-Assistent, automatisch beim ersten Start
Schema-Evolution	Kollektionen, Felder, Taxonomien	Admin-Panel oder `emdash schema` gegen die Live-Site (diese Seite)

Die Seed-Datei ist nur an der dritten Zeile beteiligt. Sie wird einmal angewendet, wenn die Datenbank leer ist und der Setup-Assistent nicht abgeschlossen wurde. Das Deployen einer geänderten Seed-Datei gegen eine bestehende Datenbank bewirkt nichts — die Weiterentwicklung des Schemas einer Live-Site geschieht immer über das Admin-Panel oder die API.

Das Schema im Admin-Panel ändern

Das Admin-Panel ist der primäre Weg, eine bereitgestellte Site weiterzuentwickeln. Öffnen Sie Content Types im Admin und fügen Sie Kollektionen und Felder hinzu, bearbeiten oder entfernen Sie sie. Änderungen werden sofort wirksam — die Inhalts-API, der Loader und die Bearbeitungs-UI lesen alle das Schema zur Laufzeit aus der Datenbank.

Siehe Kollektionen & Felder für die verfügbaren Feldtypen, Validierungsregeln und Widget-Optionen.

Nach der Änderung des Schemas regenerieren Sie die TypeScript-Typen, die Ihre Templates verwenden. Der Befehl emdash types liest das Schema von einer laufenden Instanz, sodass er direkt auf die bereitgestellte Site zeigen kann:

npx emdash types --url https://example.com

Das Schema über die CLI ändern

Die emdash schema-Befehle kommunizieren über die REST-API mit einer laufenden Instanz, sodass sie gegen eine bereitgestellte Site genauso funktionieren wie gegen lokales Dev. Authentifizieren Sie sich einmal mit dem Device-Flow:

npx emdash login --url https://example.com

Alternativ erstellen Sie einen API-Token im Admin unter Settings → API Tokens und übergeben ihn mit --token oder der Umgebungsvariable EMDASH_TOKEN — nützlich für CI.

Dann entwickeln Sie das Schema mit den gleichen Befehlen weiter, die Sie lokal verwenden würden:

npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com

Da diese Befehle einfache CLI-Aufrufe sind, können sie geskriptet werden: Eine wiederholbare „Migration” für Ihr Inhaltsmodell ist ein Shell-Skript mit emdash schema-Aufrufen, das in Ihr Repository eingecheckt und nacheinander gegen jede Umgebung ausgeführt wird.

Siehe die CLI-Referenz für die vollständige Befehlsliste.

Die Seed-Datei synchron halten

Die in Ihrem Build eingebettete Seed-Datei bestimmt, womit eine frische Datenbank initialisiert wird: eine neue Vorschau-Umgebung, ein Disaster-Recovery-Rebuild oder ein zweites Deployment derselben Site. Wenn die Seed-Datei noch den Starter-Blog beschreibt, während die Produktion sich zu etwas anderem entwickelt hat, startet jede frische Umgebung mit dem falschen Modell.

Der Build bettet die erste gefundene Seed-Datei ein unter .emdash/seed.json, dem Pfad in package.json#emdash.seed oder seed/seed.json. Wenn keine vorhanden ist, wird eine integrierte Standard-Seed (das Starter-Blog-Modell) eingebettet, und astro dev gibt eine Warnung aus.

Nach der Weiterentwicklung des Schemas einer bereitgestellten Site exportieren Sie das Live-Modell zurück in Ihr Repository. emdash export-seed liest eine lokale SQLite-Datei, und wrangler d1 export erzeugt eine aus der bereitgestellten D1-Datenbank:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json

Die exportierte Seed enthält die Einstellungen, Kollektionen, Taxonomien, Menüs und Widget-Bereiche der Live-Site. Fügen Sie --with-content hinzu, um Einträge einzuschließen. Committen Sie die aktualisierte .emdash/seed.json zusammen mit dem Code, der vom neuen Schema abhängt, damit eine frische Umgebung immer mit einem Modell startet, das der Code versteht.

Änderungen in einer Vorschau-Umgebung proben

Eine destruktive Schema-Änderung (Entfernen eines Feldes, Umstrukturierung einer Kollektion) wird am sichersten gegen eine Wegwerfkopie der Produktion geprobt.

Fügen Sie eine Vorschau-Umgebung mit eigener D1-Datenbank zu wrangler.jsonc hinzu:

{
  "env": {
    "preview": {
      "d1_databases": [{ "binding": "DB", "database_name": "emdash-db-preview" }],
    },
  },
}

Kopieren Sie die Produktion hinein:

npx wrangler d1 export emdash-db --remote --output=./prod.sql
npx wrangler d1 execute emdash-db-preview --remote --file=./prod.sql

Deployen Sie und führen Sie die Schema-Änderung gegen die Vorschau-URL aus:

npx wrangler deploy --env preview
npx emdash schema remove-field posts legacy_field --url https://preview.example.com

Überprüfen Sie, ob die Site rendert und der Admin sich wie erwartet verhält, dann führen Sie dieselben Befehle gegen die Produktion aus.

Von einer Fehlentscheidung erholen

Ein Feld wurde versehentlich entfernt. Die Spalte und ihre Daten sind aus der Live-Datenbank verschwunden. Stellen Sie von einem D1 Time Travel Point-in-Time-Backup wieder her, oder fügen Sie das Feld erneut hinzu und stellen Sie seine Werte aus einem früheren wrangler d1 export wieder her.
Eine frische Umgebung wurde mit dem falschen Modell gestartet. Die eingebettete Seed war veraltet oder fehlte. Aktualisieren Sie .emdash/seed.json (siehe Die Seed-Datei synchron halten), bauen Sie neu und zeigen Sie das Deploy auf eine leere Datenbank, um erneut zu initialisieren.
Das Schema und die Templates stimmen nicht überein. Deploys und Schema-Änderungen sind unabhängig, also ordnen Sie sie bewusst: additive Schema-Änderungen (neue Kollektion, neues optionales Feld) kommen zuerst, dann der Code, der sie nutzt. Für Entfernungen deployen Sie zuerst den Code, der das Feld nicht mehr nutzt, dann entfernen Sie das Feld.