Auf Astro v2 aktualisieren

Diese Anleitung hilft dir bei der Migration von Astro v1 zu Astro v2.

Du musst ein älteres Projekt auf v1 aktualisieren? Siehe unsere ältere Anleitung zur Migration (EN).

Aktualisiere die Astro-Version deines Projekts mit deinem Paketmanager auf die neueste Version. Wenn du Astro-Integrationen verwendest, aktualisiere bitte auch diese auf die neueste Version.

Terminal-Fenster
# Upgrade auf Astro v2.x
npm install astro@latest
# Beispiel: React- und Tailwind-Integrationen aktualisieren
npm install @astrojs/react@latest @astrojs/tailwind@latest

Astro v2.0 enth√§lt einige wichtige √Ąnderungen und einige veraltete Funktionen wurden entfernt. Wenn dein Projekt nach dem Upgrade auf v2.0 nicht mehr wie erwartet funktioniert, findest du in dieser Anleitung eine √úbersicht √ľber alle √Ąnderungen und Anweisungen, wie du deine Codebasis aktualisieren kannst.

Siehe das √Ąnderungsprotokoll f√ľr die vollst√§ndigen Versionshinweise.

Entfernt: Unterst√ľtzung f√ľr Node 14

Abschnitt betitelt Entfernt: Unterst√ľtzung f√ľr Node 14

Der Node 14 wird voraussichtlich im April 2023 sein Lebensende erreichen.

Astro v2.0 verzichtet komplett auf die Unterst√ľtzung von Node 14, damit alle Astro-Benutzer die Vorteile der moderneren Funktionen von Node nutzen k√∂nnen.

Vergewissere dich, dass sowohl deine Entwicklungs- als auch dein Veröffentlichungs-Umgebung Node 16.12.0 oder höher verwenden.

  1. √úberpr√ľfe deine lokale Version von Node mit:

    Terminal-Fenster
    node -v

    Wenn deine lokale Entwicklungsumgebung aktualisiert werden muss, installiere Node.

  2. √úberpr√ľfe die Dokumentation deiner Aktualisierungsumgebung, um sicherzustellen, dass sie Node 16 unterst√ľtzt.

    Du kannst Node 16.12.0 f√ľr dein Astro-Projekt entweder in einer Dashboard-Konfigurationseinstellung oder in einer .nvmrc-Datei angeben.

Astro v2.0 enthält jetzt die Collections-API, mit der du deine Markdown- und MDX-Dateien in content collections (EN) organisieren kannst. Diese API reserviert src/content/ als einen speziellen Ordner.

Benenne einen bestehenden src/content/ Ordner um, um Konflikte zu vermeiden. Dieser Ordner kann, wenn er existiert, nur noch f√ľr Content Collections¬†(EN) verwendet werden.

Geändert: Astro.site nachfolgender Schrägstrich

Abschnitt betitelt Geändert: Astro.site nachfolgender Schrägstrich

In v1.x stellte Astro sicher, dass die URL, die du als site in astro.config.mjs einstellst, immer einen abschlie√üenden Schr√§gstrich hat, wenn sie √ľber Astro.site aufgerufen wird.

Astro v2.0 no longer modifies the value of site. Astro.site will use the exact value defined, and a trailing slash must be specified if desired.

F√ľge in der Datei astro.config.mjs einen abschlie√üenden Schr√§gstrich zu der in site festgelegten URL hinzu.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://example.com',
site: 'https://example.com/',
});

Ge√§ndert: _astro/ Ordner f√ľr Build-Assets

Abschnitt betitelt Ge√§ndert: _astro/ Ordner f√ľr Build-Assets

In v1.x wurden die Assets an verschiedenen Orten gebaut, darunter assets/, chunks/ und im Stammverzeichnis der Build-Ausgabe.

Astro v2.0 verschiebt und vereinheitlicht den Speicherort aller Build-Output-Assets in einen neuen _astro/ Ordner.

  • Verzeichnisdist/
    • Verzeichnis_astro
      • client.9218e799.js
      • index.df3f880e0.css

Du kannst diesen Ort mit der neuen Konfigurationsoption build.assets (EN) konfigurieren.

Aktualisiere die Konfiguration deiner Veröffentlichungsplattform, wenn sie auf den Speicherort dieser Assets angewiesen ist.

Geändert: Markdown Plugin Konfiguration

Abschnitt betitelt Geändert: Markdown Plugin Konfiguration

In v1.x verwendete Astro markdown.extendDefaultPlugins, um die Standard-Plugins von Astro wieder zu aktivieren, wenn du deine eigenen Markdown-Plugins hinzuf√ľgst.

Mit Astro v2.0 wurde diese Konfigurationsoption komplett entfernt, da das Verhalten nun standardmäßig ist.

Die Anwendung von Markdown-Plugins und Rehype-Plugins in deiner Markdown-Konfiguration deaktiviert nicht mehr die Standard-Plugins von Astro. GitHub-Flavored Markdown und Smartypants werden jetzt unabhängig davon angewendet, ob benutzerdefinierte remarkPlugins oder rehypePlugins konfiguriert sind oder nicht.

Entferne extendDefaultPlugins in deiner Konfiguration. Das ist jetzt das Standardverhalten von Astro in v2.0, und du kannst diese Zeile ersatzlos löschen.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins,
}
});

In v1.x konntest du die beiden Standard-Markdown-Plugins von Astro (GitHub-Flavored Markdown und SmartyPants) deaktivieren, indem du markdown.extendDefaultPlugins: false setzt.

Astro v2.0 ersetzt markdown.extendDefaultPlugins: false mit separaten boolschen Optionen, um jedes der in Astro eingebauten Standard-Markdown-Plugins einzeln zu steuern. Diese sind standardmäßig aktiviert und können unabhängig voneinander auf false gesetzt werden.

Entferne extendDefaultPlugins: false und f√ľge stattdessen die Optionen hinzu, um jedes Plugin einzeln zu deaktivieren.

  • markdown.gfm: false deaktiviert GitHub-Flavored Markdown
  • markdown.smartypants: false deaktiviert SmartyPants
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins: false,
smartypants: false,
gfm: false,
}
});

Geändert: MDX-Plugin-Konfiguration

Abschnitt betitelt Geändert: MDX-Plugin-Konfiguration

Ersetzt: extendPlugins geändert in extendMarkdownConfig

Abschnitt betitelt Ersetzt: extendPlugins geändert in extendMarkdownConfig

In Version 1.x wurde mit der Option extendPlugins der MDX-Integration gesteuert, wie deine MDX-Dateien deine Markdown-Konfiguration erben sollten: die gesamte Markdown-Konfiguration (markdown) oder nur die Standard-Plugins von Astro (default).

Astro v2.0 ersetzt das von mdx.extendPlugins gesteuerte Verhalten durch drei neue, unabhängig voneinander konfigurierbare Optionen, die standardmäßig true sind:

  • mdx.extendMarkdownConfig¬†(EN), um alle oder keine deiner Markdown-Konfigurationen zu erben
  • mdx.gfm zum Aktivieren oder Deaktivieren von GitHub-Flavored Markdown in MDX
  • mdx.smartypants zum Aktivieren oder Deaktivieren von SmartyPants in MDX

Lösche extendPlugins: 'markdown' in deiner Konfiguration. Dies ist jetzt das Standardverhalten.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'markdown',
}),
],
});

Ersetze extendPlugins: 'defaults' durch extendMarkdownConfig: false und f√ľge die separaten Optionen f√ľr GitHub-Flavored Markdown und SmartyPants hinzu, um diese Standard-Plugins einzeln in MDX zu aktivieren.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'defaults',
extendMarkdownConfig: false,
smartypants: true,
gfm: true,
}),
],
});

Hinzugef√ľgt: Mehr MDX-Konfigurationsoptionen zur Anpassung an Markdown

Abschnitt betitelt Hinzugef√ľgt: Mehr MDX-Konfigurationsoptionen zur Anpassung an Markdown

Mit Astro v2.0 kannst du jetzt jede verf√ľgbare Markdown-Konfigurationsoption¬†(EN) (au√üer drafts) einzeln in deiner MDX-Integrationskonfiguration einstellen.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
remarkPlugins: [remarkPlugin2],
gfm: false,
})
]
});

√úberpr√ľfe deine Markdown- und MDX-Konfiguration und vergleiche deine bestehende Konfiguration mit den neuen Optionen.

Geändert: Plugin-Zugriff auf Frontmatter

Abschnitt betitelt Geändert: Plugin-Zugriff auf Frontmatter

In v1.x hatten die Plugins remark und rehype keinen Zugriff auf das Frontmatter der Benutzer. Astro hat das Frontmatter der Plugins mit dem Frontmatter deiner Datei zusammengef√ľhrt, ohne das Frontmatter der Datei an deine Plugins weiterzugeben.

Mit Astro v2.0 können remark- und rehype-Plugins per Frontmatter-Injection auf das Frontmatter des Nutzers zugreifen. So können Plugin-Autoren das bestehende Frontmatter eines Benutzers ändern oder neue Eigenschaften auf der Grundlage anderer Eigenschaften berechnen.

√úberpr√ľfe alle remark und rehype Plugins, die du geschrieben hast, um zu sehen, ob sich ihr Verhalten ge√§ndert hat. Beachte, dass data.astro.frontmatter jetzt das Frontmatter des kompletten Markdown- oder MDX-Dokuments ist und nicht mehr ein leeres Objekt.

In v1.x erlaubte das RSS-Paket von Astro die Verwendung von items: import.meta.glob(...), um eine Liste von RSS-Feed-Einträgen zu erstellen. Diese Funktion ist jetzt veraltet und wird in Zukunft abgeschafft.

Astro v2.0 f√ľhrt einen pagesGlobToRssItems()-Wrapper f√ľr die Eigenschaft items ein.

Importiere und verpacke dann deine bestehende Funktion, die import.meta.glob() enthält, mit dem Helfer pagesGlobToRssItems().

src/pages/rss.xml.js
import rss, {
pagesGlobToRssItems
} from '@astrojs/rss';
export async function get(context) {
return rss({
items: await pagesGlobToRssItems(
import.meta.glob('./blog/*.{md,mdx}'),
),
});
}

Ge√§ndert: Svelte-IDE-Unterst√ľtzung

Abschnitt betitelt Ge√§ndert: Svelte-IDE-Unterst√ľtzung

Astro v2.0 benötigt eine svelte.config.js-Datei in deinem Projekt, wenn du die Integration @astrojs/svelte (EN) verwendest. Diese Datei wird benötigt, um die IDE-Autovervollständigung zu ermöglichen.

F√ľge eine Datei svelte.config.js zum Stammverzeichnis deines Projekts hinzu:

svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};

F√ľr neue Benutzer wird diese Datei automatisch hinzugef√ľgt, wenn sie astro add svelte ausf√ľhren.

Entfernt: legacy.astroFlavoredMarkdown

Abschnitt betitelt Entfernt: legacy.astroFlavoredMarkdown

In v1.0 hat Astro das alte Astro-Flavored Markdown (auch bekannt als Komponenten in Markdown) zu einem Legacy-Feature gemacht.

Astro v2.0 entfernt die Option legacy.astroFlavoredMarkdown vollständig. Das Importieren und Verwenden von Komponenten in .md-Dateien funktioniert nicht mehr.

Entferne dieses Legacy-Option. Sie ist in Astro nicht mehr verf√ľgbar.

astro.config.mjs
export default defineConfig({
legacy: {
astroFlavoredMarkdown: true,
},
})

Wenn du diese Funktion in v1.x verwendet hast, empfehlen wir die MDX-Integration¬†(EN), mit der du Komponenten und JSX-Ausdr√ľcke mit Markdown-Syntax kombinieren kannst.

In Version 0.24 hat Astro die Funktion Astro.resolve() veraltet, um aufgelöste URLs zu Assets zu erhalten, die du im Browser referenzieren möchtest.

Mit Astro v2.0 wurde diese Option komplett entfernt. die Option Astro.resolve() in deinem Code f√ľhrt zu einem Fehler.

Löse Asset-Pfade stattdessen mit import auf. Zum Beispiel:

src/pages/index.astro
---
import 'style.css';
import imageUrl from './image.png';
---
<img src={imageUrl} />

In Version 0.26 hat Astro die Funktion Astro.fetchContent() zum Abrufen von Daten aus deinen lokalen Markdown-Dateien veraltet.

Mit Astro v2.0 wurde diese Option komplett entfernt. Astro.fetchContent() in deinem Code wird einen Fehler verursachen.

Verwende Astro.glob(), um Markdown-Dateien zu laden, oder verwende stattdessen die Funktion Content Collections (EN).

src/pages/index.astro
---
const allPosts = await Astro.glob('./posts/*.md');
---

In v1.0 hat Astro die Funktion Astro.canonicalURL zur Erstellung einer kanonischen URL veraltet.

Mit Astro v2.0 wurde diese Option komplett entfernt. die Option Astro.canonicalURL in deinem Code f√ľhrt zu einem Fehler.

Verwende Astro.url, um eine kanonische URL zu erstellen.

src/pages/index.astro
---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

Astro v2.0 f√ľhrt ein Upgrade von Vite 3 auf Vite 4 durch, das im Dezember 2022 ver√∂ffentlicht wird.

Es sollten keine √Ąnderungen an deinem Code n√∂tig sein! Wir haben den Gro√üteil des Upgrades innerhalb von Astro f√ľr dich erledigt, aber einige Verhaltensweisen von Vite k√∂nnen sich zwischen den Versionen noch √§ndern.

Schau im offiziellen Vite Migration Guide nach, wenn du auf Probleme stößt.

Astro v2.0 Experimentelle Optionen wurden entfernt

Abschnitt betitelt Astro v2.0 Experimentelle Optionen wurden entfernt

Entferne die folgenden experimentellen Option aus astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
contentCollections: true,
prerender: true,
errorOverlay: true,
},
})

Diese Funktionen sind jetzt standardm√§√üig verf√ľgbar:

Es gibt derzeit keine bekannten Probleme.