Komponent Image w Next.js: sizes, preload i zdalne obrazy
Przewodnik po komponencie Image w Next.js
Next.js Image: sizes, preload, remotePatterns i LCP | We.Inc
Jak działa next/image w Next.js 16: width, height i fill, kalkulator sizes, preload zamiast priority, remotePatterns, qualities i domyślne szerokości srcset.
Zaimportuj Image z next/image i podaj src, alt oraz albo width i height, albo fill. Dodaj ciąg sizes zawsze, gdy renderowana szerokość zmienia się wraz z ekranem, aby przeglądarka pobrała mniejszy plik. Dla obrazu hero, który jest Twoim LCP, ustaw preload (w Next.js 16 zastąpił priority). Zewnętrzne hosty dopuść przez images.remotePatterns.
Propsy, od których zależy szybkość
Prop
Domyślnie
Używaj, gdy
width / height
Obraz ma stały rozmiar albo chcesz zarezerwować proporcje
O rozmiarze decyduje kontener nadrzędny (karty, hero, okładki)
przeglądarka zakłada 100vw
Obraz jest responsywny lub używa fill
Obraz jest elementem LCP na pierwszym ekranie
Ustaw eager tylko dla obrazów, które muszą załadować się od razu
Serwowane są tylko wartości wymienione w images.qualities
W Next.js łatwo popełnić dwa błędy z obrazami: obraz z fill bez sizes, przez co telefony pobierają pliki desktopowe, oraz hero czekający na leniwe ładowanie. Ta strona prostymi słowami wyjaśnia każdy prop, daje kalkulator, który pisze ciąg sizes dla Twojego układu, i wymienia domyślne ustawienia konfiguracji, których Next.js używa dziś.
Wybierz układ, w którym jest obraz, na przykład pełna szerokość, podział na dwie kolumny lub siatka trzech kart.
Ustaw breakpointy używane w Twoim CSS. Kalkulator napisze pasującą wartość sizes.
Wybierz szerokość telefonu i gęstość pikseli, aby zobaczyć, którą domyślną szerokość srcset przeglądarka najpewniej pobierze.
Skopiuj gotowy element Image i wklej go do swojego komponentu.
Statyczne importy (import hero from './hero.jpg') same uzupełniają width, height i blurDataURL, więc wybieraj je dla obrazów trzymanych w repozytorium.
Daj obrazowi z fill rodzica z position: relative i realną wysokością, inaczej zapadnie się do zera.
Tylko jeden obraz na viewport powinien dostać preload. Oznaczenie kilku obrazów niweczy cel i sprawia, że konkurują o przepustowość.
Ograniczaj remotePatterns: podaj protokół, dokładną nazwę hosta i prefiks ścieżki zamiast dopuszczać całą domenę.
Gdy podana jakość nie występuje w images.qualities, Next.js serwuje najbliższą dozwoloną wartość i ostrzega w trybie deweloperskim.
Najczęściej zadawane pytania
Czy prop priority jest przestarzały?
Tak. Od Next.js 16 dokumentacja oznacza priority jako przestarzały na rzecz preload, który wstawia link preload do head. Dokumentacja mówi też, że w większości przypadków lepszym wyborem jest loading="eager" lub fetchPriority="high", a preload nie powinien być łączony z żadnym z tych propsów.
Dlaczego next/image mówi, że host nie jest skonfigurowany?
Zewnętrzne obrazy muszą pasować do wpisu w images.remotePatterns w next.config. Dodaj obiekt z protocol, hostname i pathname, na przykład /photos/**, a potem uruchom ponownie serwer deweloperski. Żądania niepasujące do żadnego wzorca dostają od optymalizatora obrazów odpowiedź 400.
Co właściwie zmienia prop sizes?
Mówi przeglądarce, jak szeroki będzie obraz w każdym breakpoincie, zanim załaduje się CSS. Z sizes Next.js generuje też pełny srcset oparty na szerokościach (640w, 750w i tak dalej) zamiast tylko 1x i 2x, więc telefon może wybrać znacznie mniejszy plik.
Czy z fill potrzebuję width i height?
Nie. fill oraz width/height to alternatywy. Z fill obraz rozciąga się do pozycjonowanego rodzica, a kadrowanie kontrolujesz przez object-fit w propie style lub className.
Jak długo buforowane są zoptymalizowane obrazy?
Domyślne minimumCacheTTL to 14400 sekund, czyli cztery godziny. Faktyczny max age to większa z dwóch wartości: ta albo nagłówek Cache-Control wysłany przez oryginalny obraz. Obrazy importowane statycznie dostają długotrwałe niezmienne buforowanie, bo ich nazwy plików zawierają hash.
Po co istnieje ten komponent
Zwykły tag img wysyła jeden plik na każde urządzenie. next/image skaluje źródło na żądanie, konwertuje je do nowoczesnego formatu akceptowanego przez przeglądarkę, domyślnie ładuje leniwie i rezerwuje miejsce, żeby układ nie skakał podczas ładowania.
Haczyk polega na tym, że sensowny plik może wybrać tylko wtedy, gdy wie, jak szeroki będzie obraz. To zadanie width, height i sizes, i właśnie tu zdarza się większość błędów w praktyce.
Poprawne LCP
Largest Contentful Paint to często zdjęcie hero. Leniwe ładowanie tego zdjęcia opóźnia metrykę, więc oznacz je preload albo loading="eager" z fetchPriority="high", a wszystkie obrazy poniżej pierwszego ekranu zostaw przy domyślnym leniwym ładowaniu.
Połącz to z uczciwą wartością sizes. Hero na całą szerokość telefonu, ale na połowę strony na desktopie, powinien to mówić, inaczej i duże, i małe ekrany dostaną zły plik.
Konfiguracja, którą będziesz zmieniać
remotePatterns wymienia zewnętrzne hosty, którym ufasz. qualities to lista dozwolonych wartości jakości, wymagana od Next.js 16, a dokumentacja ustawia ją domyślnie na 75. formats pozwala dodać AVIF przed WebP, kosztem przechowywania obu wersji w buforze.
deviceSizes i imageSizes razem tworzą kandydujące szerokości w każdym srcset. Rzadko trzeba je zmieniać, ale znajomość wartości domyślnych pomaga odczytać w panelu sieci, co przeglądarka pobrała.
Wszystkie propsy, których prawdopodobnie użyjesz
Propsy next/image (dokumentacja Next.js 16)
Prop
Typ
Co robi
string lub statyczny import
Ścieżka lokalna w public, importowany plik lub zewnętrzny URL dopuszczony przez remotePatterns
Wymagany tekst alternatywny; pusty string tylko dla obrazów dekoracyjnych
width, height
liczba całkowita (px)
Rozmiar własny używany do proporcji; niepotrzebny przy statycznych importach i fill
Rozciągnij do pozycjonowanego rodzica zamiast używać width i height
Warunki media i szerokości slotów, które sterują wyborem z srcset
liczba całkowita od 1 do 100
Jakość wyjściowa, domyślnie 75, dopasowana do listy images.qualities
Dodaje link preload w head dla obrazu LCP
lazy lub eager
Domyślnie lazy
empty, blur lub data URL
Co widać podczas ładowania; blur wymaga blurDataURL, chyba że obraz jest importowany statycznie
Serwuj plik źródłowy bez zmian, bez skalowania i zmiany formatu
Przestarzały w Next.js 16; używaj preload
Domyślne ustawienia konfiguracji obrazów
Ustawienia images w next.config i ich wartości domyślne
Ustawienie
Domyślnie
Uwagi
deviceSizes
Szerokości dla obrazów na pełną szerokość i z fill
imageSizes
Dodatkowe małe szerokości, używane tylko, gdy obraz ma prop sizes
Wymagana lista dozwolonych wartości od Next.js 16
minimumCacheTTL
14400 (4 godziny)
Wygrywa większa z tej wartości i nagłówka Cache-Control źródła
remotePatterns
Każdy zewnętrzny host musi być wymieniony
Przykłady do skopiowania
Obraz hero ze statycznego importu
Import daje Next.js rzeczywiste wymiary i rozmyty placeholder. preload rozpoczyna pobieranie z head.
Siatka kart z fill i sizes
Każda karta zajmuje jedną trzecią strony na desktopie, połowę na tabletach i pełną szerokość na telefonach, i dokładnie to mówi wartość sizes.
next.config.ts dla zdalnego hosta obrazów
Dozwolone są tylko pliki HTTPS w /uploads/ na jednym hoście. Dopuszczone są dwie wartości jakości.
Pełna szerokość
Połowa na desktopie
Siatka 2 kolumn
Siatka 3 kart
Siatka 4 kart
Kalkulator sizes
Wybierz układ i breakpointy, aby wygenerować atrybut sizes, a potem zobacz, którą domyślną szerokość srcset dany ekran prawdopodobnie pobierze.
Układ
Breakpoint telefonu (px)
Breakpoint tabletu (px)
Szerokość ekranu: {n}px
Gęstość pikseli
Przy {screen}px slot obrazu ma około {slot}px szerokości ({vw}vw). Przy gęstości {dpr}x potrzeba {need} pikseli urządzenia, więc przeglądarka najpewniej pobierze kandydata {pick}w.
Kopiuj
Domyślne kandydujące szerokości: {list}. Przeglądarki mogą wybrać inaczej, na przykład gdy większy plik jest już w buforze.