Przejdź do głównej zawartości

Zaktualizuj do Astro v4.0

Ten przewodnik pomoże Ci zaktualizować projekt z Astro v3 do Astro v4.

Potrzebujesz zaktualizować starszy projekt do v3? Zobacz nasz starszy przewodnik migracyjny.

Potrzebujesz zobaczyć dokumentacje v3? Odwiedź tę starszą wersję strony dokumentacji (nieutrzymywany snapshot v3.6).

Zaktualizuj wersję Astro i wszystkie oficjalne integracje do najnowszych wersji za pomocą menedżera pakietów.

Okno terminala
# Zaktualizuj Astro i oficjalne integracje razem
npx @astrojs/upgrade

Możesz również zaktualizować integracje Astro manualnie, jeśli to konieczne, i być może będziesz musiał zaktualizować inne zależności w swoim projekcie.

Astro v4.0 zawiera potencjalne zmiany, które mogą powodować problemy, jak również usunięcie niektórych wcześniej zdezaktualizowanych funkcji.

Jeśli Twój projekt nie działa zgodnie z oczekiwaniami po aktualizacji do wersji v4.0, sprawdź ten przewodnik, aby uzyskać przegląd wszystkich zmian powodujących problemy i instrukcje dotyczące aktualizacji kodu.

Zobacz dziennik zmian w celu uzyskania pełnych notatek wydania.

Usunięto Eksperymentalne Flagi w Astro v4.0

Dział zatytułowany Usunięto Eksperymentalne Flagi w Astro v4.0

Usuń flagę eksperymentalną devOverlay i przenieś konfigurację i18n na najwyższy poziom w astro.config.mjs:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
devOverlay: true,
i18n: {
defaultLocale: "en",
locales: ["en", "fr", "pt-br", "es"],
}
},
i18n: {
defaultLocale: "en",
locales: ["en", "fr", "pt-br", "es"],
},
})

Konfiguracje, i18n i przemianowane devToolbar, są teraz dostępne w Astro v4.0.

Przeczytaj więcej o tych dwóch ekscytujących funkcjach, i o wielu innych w tym wpisie na blogu v4.0!

Jakakolwiek znacząca aktualizacja zależności Astro może wprowadzić istotne zmiany w Twoim projekcie.

W Astro v3.0, Vite 4 był używany jako serwer deweloperski i bundler produkcyjny.

Astro v4.0 aktualizuje z Vite 4 do Vite 5.

Jeśli używasz wtyczek, konfiguracji lub API specyficznych dla Vite, sprawdź przewodnik migracyjny Vite w celu sprawdzenia zmian powodujących problemy i zaktualizuj swój projekt w razie potrzeby. W Astro samym w sobie nie ma zmian powodujących problemy.

Uaktualnione: jednolite zależności dla remark i rehype

Dział zatytułowany Uaktualnione: jednolite zależności dla remark i rehype

W Astro w wersji 3.x używano jednolitej wersji 10 oraz związanych z nią zgodnych pakietów remark/rehype do przetwarzania Markdown i MDX.

W wersji 4.0 Astro uaktualnia jednolitą do wersji 11 oraz inne pakiety remark/rehype do najnowszej wersji.

Jeśli korzystałeś z niestandardowych pakietów remark/rehype, zaktualizuj wszystkie z nich do najnowszej wersji za pomocą menedżera pakietów, aby upewnić się, że obsługują one jednolitą w wersji 11. Pakiety, których używasz, można znaleźć w pliku astro.config.mjs.

Nie powinno być żadnych istotnych zmian łamiących, jeśli korzystasz z aktywnie aktualizowanych pakietów, ale niektóre pakiety mogą jeszcze nie być kompatybilne z jednolitą w wersji 11. Przed wdrożeniem sprawdź wizualnie swoje strony Markdown/MDX, aby upewnić się, że Twoja witryna działa zgodnie z zamierzeniami.

Następujące zmiany są uważane za zmiany powodujące problemy w Astro. Zmiany powodujące problemy mogą lub nie muszą zapewniać tymczasową kompatybilność wsteczną, a cała dokumentacja jest aktualizowana, aby odnosić się tylko do obecnie obsługiwanego kodu.

Jeśli potrzebujesz odnosić się do dokumentacji dla projektu v3.x, możesz przeglądać ten (nieutrzymywany) snapshot dokumentacji sprzed wydania v4.0.

Zmieniona nazwa: entrypoint (API integracji)

Dział zatytułowany Zmieniona nazwa: entrypoint (API integracji)

W Astro v3.x, właściwość entryPoint API integracji injectRoute, która określała punkt wejścia, była nazwana entryPoint.

Astro v4.0 zmienia nazwę tej właściwości na entrypoint, aby była zgodna z innymi API Astro. Właściwość entryPoint jest niewspierana, ale nadal będzie działać i wyświetlać ostrzeżenie, które zaleca aktualizację kodu.

Jeśli masz integracje, które używają API injectRoute, zmień nazwę właściwości entryPoint na entrypoint. Jeśli jesteś autorem biblioteki i chcesz obsługiwać zarówno Astro 3, jak i 4, możesz określić zarówno entryPoint, jak i entrypoint, w takim przypadku ostrzeżenie nie zostanie wyświetlone.

injectRoute({
pattern: '/fancy-dashboard',
entryPoint: '@fancy/dashboard/dashboard.astro'
entrypoint: '@fancy/dashboard/dashboard.astro'
});

Zmiana: Podpis app.render w API Integracji

Dział zatytułowany Zmiana: Podpis app.render w API Integracji

W Astro v3.0, metoda app.render() przyjmuje routeData i locals jaki osobne, opcionalne argumenty.

Astro v4.0 zmienia podpis app.render(). Te dwie właściwości są teraz dostępne w jednym obiekcie. Zarówno obiekt, jak i te dwie właściwości są nadal opcjonalne.

Jeśli utrzymujesz adapter, obecny podpis będzie nadal działać do następnej głównej wersji. Aby przejść do nowego podpisu, przekaż routeData i locals jako właściwości obiektu zamiast jako wiele niezależnych argumentów.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Zmiana: adaptery muszą teraz określić obsługiwane funkcje

Dział zatytułowany Zmiana: adaptery muszą teraz określić obsługiwane funkcje

W Astro w wersji 3.x nie było wymagane, aby adaptery określały funkcje, które obsługują.

W Astro w wersji 4.0 adaptery muszą przekazywać właściwość supportedAstroFeatures{} w celu określenia listy obsługiwanych funkcji. Ta właściwość nie jest już opcjonalna.

Autorzy adapterów muszą przekazać opcję supportedAstroFeatures{} w celu określenia listy obsługiwanych funkcji.

my-adapter.mjs
export default function createIntegration() {
return {
name: '@matthewp/my-adapter',
hooks: {
'astro:config:done': ({ setAdapter }) => {
setAdapter({
name: '@matthewp/my-adapter',
serverEntrypoint: '@matthewp/my-adapter/server.js',
supportedAstroFeatures: {
staticOutput: 'stable'
}
});
},
},
};
}

Usunięto: Właściwość path języka Shiki

Dział zatytułowany Usunięto: Właściwość path języka Shiki

W Astro w wersji 3.x, język Shiki przekazywany do markdown.shikiConfig.langs był automatycznie konwertowany na język kompatybilny z Shikiji. Shikiji to narzędzie wewnętrzne używane przez Astro do podświetlania składni.

Astro w wersji 4.0 usuwa obsługę właściwości path języka Shiki, która była myląca w konfiguracji. Została zastąpiona importem, który można przekazać bezpośrednio do langs.

Plik JSON zawierający definicję języka powinien być importowany i przekazywany jako opcja.

astro.config.js
import customLang from './custom.tmLanguage.json'
export default defineConfig({
markdown: {
shikiConfig: {
langs: [
{ path: '../../custom.tmLanguage.json' },
customLang,
],
},
},
})

Następujące niewspierane funkcje nie są już obsługiwane i nie są już dokumentowane. Proszę zaktualizować swój projekt odpowiednio.

Niektóre zdezaktualizowane funkcje mogą tymczasowo nadal działać, dopóki nie zostaną całkowicie usunięte. Inne mogą nie mieć żadnego efektu lub zgłosić błąd, zachęcając do aktualizacji kodu.

Niewspierane: handleForms dla zdarzeń submit w przejściach widoku

Dział zatytułowany Niewspierane: handleForms dla zdarzeń submit w przejściach widoku

W Astro w wersji 3.x projekty korzystające z komponentu <ViewTransitions /> musiały wyraźnie zdecydować o obsłudze zdarzeń submit dla elementów form. Było to realizowane poprzez przekazywanie właściwości handleForms.

Astro v4.0 handles submit events for form elements by default when <ViewTransitions /> are used. The handleForms prop has been deprecated and no longer has any effect. W Astro w wersji 4.0 zdarzenia submit dla elementów form są obsługiwane domyślnie, gdy używane są <ViewTransitions />. Właściwość handleForms została zdezaktualizowana i nie ma już żadnego efektu.

Usuń właściwość handleForms z komponentu ViewTransitions. Nie jest już potrzebna.

src/pages/index.astro
---
import { ViewTransitions } from "astro:transitions";
---
<html>
<head>
<ViewTransitions handleForms />
</head>
<body>
<!-- stuff here -->
</body>
</html>

Aby zrezygnować z obsługi zdarzenia submit, dodaj atrybut data-astro-reload do odpowiednich elementów form.

src/components/Form.astro
<form action="/contact" data-astro-reload>
<!-- -->
</form>

Poprzednio niewspierane, teraz usunięte funkcje

Dział zatytułowany Poprzednio niewspierane, teraz usunięte funkcje

Następujące zdezaktualizowane funkcje zostały całkowicie usunięte z bazy kodu i nie mogą już być używane. Niektóre z tych funkcji mogły nadal działać w Twoim projekcie nawet po zdezaktualizowaniu. Inne mogły cicho nie mieć żadnego efektu.

Projekty zawierające teraz usunięte funkcje nie będą w stanie być budowane, i nie będzie już żadnej dokumentacji wsparcia zachęcającej do usunięcia tych funkcji.

Usunięto: zwracanie prostych obiektów z endpointów

Dział zatytułowany Usunięto: zwracanie prostych obiektów z endpointów

W Astro w wersji 3.x zwracanie prostych obiektów z punktów końcowych było zdezaktualizowane, ale nadal było obsługiwane w celu zachowania kompatybilności z Astro w wersji 2. Dodatkowo dostarczono narzędzie ResponseWithEncoding, aby ułatwić migrację.

W Astro w wersji 4.0 usunięto obsługę prostych obiektów i wymaga, aby punkty końcowe zawsze zwracały Response. Narzędzie ResponseWithEncoding również zostało usunięte na rzecz właściwego typu Response.

Zaktualizuj endpoint aby zwracał obiekt ‘Response’ bezpośrednio.

export async function GET() {
return { body: { "title": "Bob's blog" }};
return new Response(JSON.stringify({ "title": "Bob's blog" }));
}

Aby usunąc użycie ResponseWithEncoding, przepisz swój kod, aby używał ArrayBuffer zamiast:

export async function GET() {
const file = await fs.readFile('./bob.png');
return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
return new Response(file.buffer);
}

Usunięto: build.split i build.excludeMiddleware

Dział zatytułowany Usunięto: build.split i build.excludeMiddleware

W Astro w wersji 3.0 opcje konfiguracyjne build.split i build.excludeMiddleware zostały zdezaktualizowane i zastąpione opcjami konfiguracyjnymi adaptera, które wykonują te same zadania.

W Astro w wersji 4.0 te właściwości zostały całkowicie usunięte.

Jeśli używasz zdezaktualizowanych build.split lub build.excludeMiddleware, musisz je teraz usunąć, ponieważ już nie istnieją.

Prosze zobacz przewodnik migracyjny v3, aby zaktualizować te zdezaktualizowane właściwości middleware z konfiguracjami adaptera.

W Astro v3.0, API Astro.request.params przestało być aktualizowane, ale zostało zachowane dla zachowania kompatybilności wstecznej.

W Astro v4.0 usunięto tę opcję całkowicie.

Zaktualizuj wszystkie wystąpienia do Astro.params, który jest obsługiwanym zamiennikiem.

const { id } = Astro.request.params;
const { id } = Astro.params;

W Astro w wersji 3.0 korzystanie z markdown.drafts do kontrolowania budowy projektów roboczych zostało zdezaktualizowane.

W Astro w wersji 4.0 ta opcja została całkowicie usunięta.

Jeśli korzystasz z niewspieranej markdown.drafts, musisz ją teraz usunąć, ponieważ już nie istnieje.

Aby kontynuować oznaczanie niektórych stron w projekcie jako robocze, przenieś się do kolekcji treści i ręcznie odfiltruj strony z właściwością frontmatter draft: true.

W Astro w wersji 3.0 eksport getHeaders() dla Markdowna został zdezaktualizowany i zastąpiony przez getHeadings().

W Astro w wersji 4.0 ta opcja została całkowicie usunięta.

Jeśli korzystasz z zdezaktualizowanej metody getHeaders(), musisz ją teraz usunąć, ponieważ nie istnieje już. Zastąp wszystkie wystąpienia metodą getHeadings(), która jest obsługiwaną zamienną.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

W Astro w wersji 3.0, użycie zdezaktualizowanego pomocnika rss w getStaticPaths() powodowało błąd.

W Astro w wersji 4.0 ten pomocnik został całkowicie usunięty.

Jeśli korzystasz z nieobsługiwaniej metody generowania kanałów RSS, musisz teraz użyć integracji @astrojs/rss dla kompletnego ustawienia RSS.

Usunięto: małe litery w nazwach metod HTTP

Dział zatytułowany Usunięto: małe litery w nazwach metod HTTP

W Astro w wersji 3.0 korzystanie z małych liter w nazwach metod żądań HTTP (get, post, put, all, del) było zdezaktualizowane.

W Astro w wersji 4.0 usunięto obsługę małych liter całkowicie. Wszystkie metody żądań HTTP muszą teraz być zapisywane z użyciem wielkich liter.

Jeśli korzystasz z zdezaktualizowanych nazw z małymi literami, musisz teraz zastąpić je ich odpowiednikami z wielkimi literami.

Proszę zajrzyj do przewodnika migracji v3 dla wskazówek dotyczących korzystania z metod żądań HTTP z wielkimi literami.

Usunięto: przekierowania 301 przy braku prefiksu base

Dział zatytułowany Usunięto: przekierowania 301 przy braku prefiksu base

W Astro w wersji 3.x serwer podglądu Astro zwracał przekierowanie 301 podczas dostępu do zasobów z katalogu publicznego bez ścieżki bazowej.

W Astro w wersji 4.0 zasoby katalogu publicznego, gdy serwer podglądu działa, zwracają status 404 bez prefiksu ścieżki bazowej, zgodnie z zachowaniem serwera deweloperskiego.

Podczas korzystania z serwera podglądu Astro, wszystkie importy i adresy URL statycznych zasobów z katalogu publicznego muszą mieć wartośc bazową dodaną jako prefiks do ścieżki.

Poniższy przykład pokazuje atrybut src, który jest wymagany do wyświetlenia obrazu z folderu publicznego, gdy skonfigurowano base: '/docs':

src/pages/index.astro
// To access public/images/my-image.png:
<img src="/docs/images/my-image.png" alt="">

Usunięto: Automatyczna konwersja astro/client-image

Dział zatytułowany Usunięto: Automatyczna konwersja astro/client-image

W Astro w wersji 3.x typ astro/client-image (używany dla zdezaktualizowanej integracji obrazu) został usunięty, ale był automatycznie konwertowany na domyślny typ Astro astro/client, jeśli został znaleziony w pliku env.d.ts.

Astro w wersji 4.0 ignoruje astro/client-image i nie będzie już automatycznie aktualizować env.d.ts dla Ciebie.

Jeśli miałeś skonfigurowane typy dla @astrojs/image w src/env.d.ts i aktualizacja do wersji v3.0 nie skonwertowała typu automatycznie, ręcznie zamień typ astro/client-image na astro/client.

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

Znasz jakieś dobre źródło zasobów dla Astro v4.0? Edytuj tę stronę i dodaj poniżej link!

Proszę sprawdź problemy Astro na GitHubie w celu sprawdzenia zgłoszonych problemów lub zgłoszenia nowego problemu.

Pomóż nam

Jak chcesz ją przekazać?

Otwórz Issue na GitHubie

Najszybszy sposób na powiadomienie nas o problemie.

Społeczność