| title | description | i18nReady |
|---|---|---|
Zaktualizuj do Astro v4.0 |
Jak zaktualizować projekt do najnowszej wersji Astro (v4.0). |
true |
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
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.
```shell # Zaktualizuj Astro i oficjalne integracje razem npx @astrojs/upgrade ``` ```shell # Zaktualizuj Astro i oficjalne integracje razem pnpm dlx @astrojs/upgrade ``` ```shell # Zaktualizuj Astro i oficjalne integracje razem yarn dlx @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.
:::note[Potrzebujesz kontynuować?] 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.
Usuń flagę eksperymentalną devOverlay i przenieś konfigurację i18n na najwyższy poziom w 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.
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.
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'
});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 })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.
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'
}
});
},
},
};
}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.
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.
---
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.
<form action="/contact" data-astro-reload>
<!-- -->
</form>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.
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);
}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.
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.
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':
// To access public/images/my-image.png:
<img src="/docs/images/my-image.png" alt="">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.
/// <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.