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

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

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

# Zaktualizuj Astro i oficjalne integracje razem
pnpm dlx @astrojs/upgrade

# 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.

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

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!

Uaktualnienia

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

Zaktualizowano: Vite 5.0

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.

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

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.

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

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)

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ć?

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

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.

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.

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

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.

Co powinienem zrobić?

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'
          }
        });
      },
    },
  };
}

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.

Co powinienem zrobić?

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

 import customLang from './custom.tmLanguage.json'

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

Niewspierane funkcje

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

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.

Co powinienem zrobić?

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>

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

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.

Co powinienem zrobić?

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`

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.

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`

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.

Co powinienem zrobić?

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

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

Usunięto: `markdown.drafts`

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.

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()`

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ć?

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();

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ć?

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

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.

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`

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.

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':

// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

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.

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.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

Zasoby społecznościowe

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

Znane problemy

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

Zaktualizuj do Astro v4.0

Zaktualizuj Astro

Usunięto Eksperymentalne Flagi w Astro v4.0

Uaktualnienia

Zaktualizowano: Vite 5.0

Co powinienem zrobić?

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

Co powinienem zrobić?

Zmiany powodujące problemy

Zmieniona nazwa: entrypoint (API integracji)

Co powinienem zrobić?

Zmiana: Podpis app.render w API Integracji

Co powinienem zrobić?

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

Co powinienem zrobić?

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

Co powinienem zrobić?

Niewspierane funkcje

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

Co powinienem zrobić?

Poprzednio niewspierane, teraz usunięte funkcje

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

Co powinienem zrobić?

Usunięto: build.split i build.excludeMiddleware

Co powinienem zrobić?

Usunięto: Astro.request.params

Co powinienem zrobić?

Usunięto: markdown.drafts

Co powinienem zrobić?

Usunięto: getHeaders()

Co powiniem zrobić?

Usunięto: użycie rss w getStaticPaths()

Co powinienem zrobić?

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

Co powinienem zrobić?

Usunięto: przekierowania 301 przy braku prefiksu base

Co powinienem zrobić?

Usunięto: Automatyczna konwersja astro/client-image

Co powinienem zrobić?

Zasoby społecznościowe

Znane problemy

Zmieniona nazwa: `entrypoint` (API integracji)

Zmiana: Podpis `app.render` w API Integracji

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

Usunięto: `build.split` i `build.excludeMiddleware`

Usunięto: `Astro.request.params`

Usunięto: `markdown.drafts`

Usunięto: `getHeaders()`

Usunięto: użycie `rss` w `getStaticPaths()`

Usunięto: przekierowania 301 przy braku prefiksu `base`

Usunięto: Automatyczna konwersja `astro/client-image`