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 Astro
Dział zatytułowany Zaktualizuj AstroZaktualizuj wersję Astro i wszystkie oficjalne integracje do najnowszych wersji za pomocą menedżera pakietów.
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.
Po zaktualizowaniu Astro do najnowszej wersji, możesz nie musieć wprowadzać żadnych zmian do swojego projektu!
Jednakże, jeśli zauważysz błędy lub nieoczekiwane zachowanie, proszę sprawdź poniżej, co się zmieniło i co może wymagać aktualizacji w Twoim 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.0Usuń flagę eksperymentalną devOverlay
i przenieś konfigurację i18n
na najwyższy poziom w astro.config.mjs
:
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!
Uaktualnienia
Dział zatytułowany UaktualnieniaJakakolwiek znacząca aktualizacja zależności Astro może wprowadzić istotne zmiany w Twoim projekcie.
Zaktualizowano: Vite 5.0
Dział zatytułowany Zaktualizowano: Vite 5.0W Astro v3.0, Vite 4 był używany jako serwer deweloperski i bundler produkcyjny.
Astro v4.0 aktualizuje z Vite 4 do Vite 5.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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 rehypeW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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.
Zmiany powodujące problemy
Dział zatytułowany Zmiany powodujące problemyNastę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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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.
Zmiana: Podpis app.render
w API Integracji
Dział zatytułowany Zmiana: Podpis app.render w API IntegracjiW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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.
Zmiana: adaptery muszą teraz określić obsługiwane funkcje
Dział zatytułowany Zmiana: adaptery muszą teraz określić obsługiwane funkcjeW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?Autorzy adapterów muszą przekazać opcję supportedAstroFeatures{}
w celu określenia listy obsługiwanych funkcji.
Usunięto: Właściwość path języka Shiki
Dział zatytułowany Usunięto: Właściwość path języka ShikiW 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
.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?Plik JSON zawierający definicję języka powinien być importowany i przekazywany jako opcja.
Niewspierane funkcje
Dział zatytułowany Niewspierane funkcjeNastę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 widokuW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?Usuń właściwość handleForms
z komponentu ViewTransitions
. Nie jest już potrzebna.
Aby zrezygnować z obsługi zdarzenia submit
, dodaj atrybut data-astro-reload
do odpowiednich elementów form
.
Poprzednio niewspierane, teraz usunięte funkcje
Dział zatytułowany Poprzednio niewspierane, teraz usunięte funkcjeNastę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ówW 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
.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?Zaktualizuj endpoint aby zwracał obiekt ‘Response’ bezpośrednio.
Aby usunąc użycie ResponseWithEncoding
, przepisz swój kod, aby używał ArrayBuffer
zamiast:
Usunięto: build.split
i build.excludeMiddleware
Dział zatytułowany Usunięto: build.split i build.excludeMiddlewareW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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.
Usunięto: Astro.request.params
Dział zatytułowany Usunięto: Astro.request.paramsW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?Zaktualizuj wszystkie wystąpienia do Astro.params
, który jest obsługiwanym zamiennikiem.
Usunięto: markdown.drafts
Dział zatytułowany Usunięto: markdown.draftsW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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
.
Usunięto: getHeaders()
Dział zatytułowany Usunięto: getHeaders()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.
Co powiniem zrobić?
Dział zatytułowany Co powiniem zrobić?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ą.
Usunięto: użycie rss
w getStaticPaths()
Dział zatytułowany Usunięto: użycie rss w getStaticPaths()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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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 HTTPW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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 baseW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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'
:
Usunięto: Automatyczna konwersja astro/client-image
Dział zatytułowany Usunięto: Automatyczna konwersja astro/client-imageW 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.
Co powinienem zrobić?
Dział zatytułowany Co powinienem zrobić?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
.
Zasoby społecznościowe
Dział zatytułowany Zasoby społecznościoweZnasz jakieś dobre źródło zasobów dla Astro v4.0? Edytuj tę stronę i dodaj poniżej link!
Znane problemy
Dział zatytułowany Znane problemyProszę sprawdź problemy Astro na GitHubie w celu sprawdzenia zgłoszonych problemów lub zgłoszenia nowego problemu.
Upgrade Guides