Jak zamienić stronę internetową w progresywną aplikację webową
Jak zamienić stronę w PWA (przetestowany kod) | We.Inc
Spraw, by dowolna strona dała się zainstalować i działała offline: generator manifestu, przetestowany service worker, przycisk instalacji, ograniczenia na iPhonie oraz konfiguracja Vite lub Next.js.
Jak zamienić stronę internetową w progresywną aplikację webową
Aby zamienić stronę w progresywną aplikację webową, serwuj ją przez HTTPS, dodaj manifest.webmanifest z nazwą, start_url, trybem wyświetlania i ikonami 192 i 512 pikseli, podlinkuj go na każdej stronie i zarejestruj service worker, który zapisuje pliki w cache do użytku offline. Przeglądarki Chromium zaproponują wtedy instalację; użytkownicy Safari dodają ją z menu Udostępnij.
Trzy części PWA
Część
Co robi
Nazwa, ikony, kolory i sposób otwierania aplikacji
Service worker (sw.js)
Zapisuje pliki w cache, aby strony ładowały się offline
HTTPS
Wymagane dla service workerów i instalacji
Wypełnij formularz, aby otrzymać manifest i tagi do wklejenia w sekcji head, a potem skopiuj service worker i skrypt instalacji. Worker z tej strony uruchomiliśmy w prawdziwej przeglądarce z odciętą siecią, zanim go opublikowaliśmy.
Przygotuj ikony 192 i 512 pikseli oraz wersję maskable z logo mieszczącym się w środkowych 80 procentach.
Wygeneruj manifest formularzem, zapisz go jako manifest.webmanifest w katalogu głównym strony i wklej tagi head na każdą stronę.
Zapisz sw.js, offline.html i skrypt rejestrujący, a podstawowe pliki wypisz w PRECACHE.
Otwórz Chrome DevTools, panel Application: sprawdź Manifest pod kątem problemów z instalacją i Service workers, aby zobaczyć działający worker. Zaznacz Offline i przeładuj, aby przetestować.
Gdy zmienisz pliki w cache, podbij VERSION, aby powracający odwiedzający dostali nowe.
Serwuj sw.js z katalogu głównego strony. Worker kontroluje tylko strony w swoim folderze i poniżej.
Nie zapisuj samego sw.js w cache z długimi nagłówkami HTTP cache; przeglądarki sprawdzają go pod kątem aktualizacji.
Trzymaj listę precache krótką. Wszystko, co na niej jest, pobiera się przy pierwszej wizycie.
Na iPhonie powiedz ludziom, jak zainstalować: Udostępnij, a potem Do ekranu początkowego. Nie ma okna instalacji, które można wywołać.
Testuj offline, zatrzymując też lokalny serwer, a nie tylko zaznaczając pole Offline, aby zawiodły również żądania samego workera.
Najczęściej zadawane pytania
Czy PWA potrzebuje service workera, żeby dało się ją zainstalować?
W obecnym Chrome nie: poprawny manifest, HTTPS i trochę interakcji użytkownika wystarczą, by pojawiła się opcja instalacji. Worker nadal jest potrzebny, bo bez niego zainstalowana aplikacja offline pokazuje stronę błędu przeglądarki.
Czy PWA działają na iPhonie?
Tak, z ograniczeniami. Użytkownicy Safari instalują z menu Udostępnij, nie ma zdarzenia okna instalacji, a powiadomienia push działają tylko dla strony dodanej do ekranu początkowego w iOS 16.4 lub nowszym. Cache offline działa.
Dlaczego mój przycisk instalacji nigdy się nie pojawia?
beforeinstallprompt uruchamia się tylko w przeglądarkach Chromium, tylko gdy spełnione są kryteria instalacji i nie wtedy, gdy aplikacja jest już zainstalowana. Przyczynę znajdziesz w sekcji Manifest panelu Application w DevTools.
Jak sprawdzić PWA teraz, gdy Lighthouse nie ma już oceny PWA?
Lighthouse 12 usunął kategorię PWA. Użyj panelu Application w Chrome DevTools: widok Manifest wypisuje błędy instalowalności i problemy z ikonami, a widok Service workers pokazuje rejestrację, aktualizacje i przełącznik Offline.
Jak zaktualizować PWA po wydaniu?
Zmień VERSION cache w sw.js. Przeglądarka widzi zmieniony worker, instaluje go, a krok activate usuwa stare cache. Dzięki skipWaiting i clients.claim nowy worker przejmuje kontrolę przy następnym ładowaniu.
Najpierw cache czy najpierw sieć
Strategia cache-first odpowiada z cache i sięga do sieci tylko po to, czego nie ma zapisanego. Jest szybka i właściwa dla plików, których zawartość nigdy się nie zmienia pod tą samą nazwą, takich jak skrypty z hashem, czcionki i ikony.
Strategia network-first pyta serwer i korzysta z cache tylko wtedy, gdy to zawiedzie. Pasuje do stron HTML, gdzie pokazanie starej kopii po aktualizacji wprowadzałoby ludzi w błąd. Worker powyżej używa obu: network-first przy ładowaniu stron, cache-first dla całej reszty.
Typowe błędy
Rejestrowanie workera ze ścieżki w podfolderze, na przykład /js/sw.js, co ogranicza go do stron w /js/.
Zapominanie o zmianie VERSION, przez co powracający odwiedzający mają stary CSS i skrypty przez całe tygodnie.
Zapisywanie w cache odpowiedzi z innych witryn lub odpowiedzi z błędami. Worker powyżej pomija żądania cross-origin i zapisuje tylko udane odpowiedzi z zasobami.
Testowanie tylko w Chrome. Otwórz stronę na iPhonie, aby zobaczyć, co faktycznie dostają użytkownicy Safari.
Co zyskujesz i jakie są ograniczenia na iPhonie
Instalacja daje Twojej stronie własną ikonę i okno bez paska adresu. Service worker dodaje strony offline. Push wymaga obu, a Apple pozwala na niego tylko dla stron, które użytkownik dodał do ekranu początkowego.
Co potrafi PWA na poszczególnych platformach
Funkcja
Chrome / Edge (komputer, Android)
Safari na iPhonie i iPadzie
Firefox
Instalacja na ekranie początkowym lub pulpicie
Tak, z oknem instalacji
Tak, ręcznie: Udostępnij, a potem Do ekranu początkowego
Android: tak. Komputer: ograniczona, sprawdź swoją wersję
Własny przycisk instalacji (beforeinstallprompt)
Tak
Nie
Nie
Offline z service workerem
Tak
Tak
Tak
Powiadomienia web push
Tak
Tylko dla strony dodanej do ekranu początkowego, iOS 16.4 lub nowszy
Tak
Trwała pamięć
Tak, może zostać usunięta przy braku miejsca
W kartach Safari pamięć zapisana przez skrypty może zostać wyczyszczona po 7 dniach korzystania z przeglądarki bez wizyty; aplikacje z ekranu początkowego mają własny licznik
Tak, może zostać usunięta przy braku miejsca
Synchronizacja w tle
Tak
Nie
Nie
Działający service worker
Trzy pliki sprawiają, że strona działa offline: worker, strona zapasowa i kilka linii do jego rejestracji. Uruchomiliśmy dokładnie te pliki na localhost w Chromium: worker się zainstalował, cache się wypełnił, a po zatrzymaniu serwera strona główna załadowała się z cache, podczas gdy nigdy nieodwiedzona strona pokazała offline.html.
sw.js: minimalny service worker działający offline
Strony najpierw próbują sieci, aby ludzie widzieli świeżą treść, potem sięgają po kopię z cache, a na końcu po offline.html. Pliki takie jak CSS, skrypty i ikony pochodzą najpierw z cache. Zmiana VERSION sprawia, że następny krok activate usuwa stare cache.
offline.html: strona zapasowa
Niech będzie samowystarczalna: style inline i żadnych zewnętrznych plików, bo gdy się wyświetla, nic innego może nie być osiągalne.
Przycisk instalacji
app.js: zarejestruj worker i pokaż przycisk instalacji
Zdarzenie beforeinstallprompt uruchamia się tylko w przeglądarkach Chromium (Chrome, Edge, Samsung Internet, Opera). Safari i Firefox nigdy go nie wysyłają, więc tam przycisk pozostaje ukryty, a ludzie korzystają z menu samej przeglądarki.
Obecne kryteria instalacji
Chrome nie wymaga już service workera, zanim zaproponuje instalację; sprawdza manifest i poniższe elementy. Lighthouse 12 usunął kategorię PWA, więc instalowalność sprawdzaj w Chrome DevTools: panel Application, a potem Manifest, gdzie wszelkie problemy są wypisane pod Installability.
Wymagania instalacji w Chrome
Wymaganie
Szczegóły
HTTPS
Serwowane bezpiecznie. localhost liczy się jako bezpieczny do testów.
Nazwa w manifeście
name lub short_name
Ikony w manifeście
Co najmniej ikona 192 px i 512 px
Obecne w manifeście
fullscreen, standalone, minimal-ui lub window-controls-overlay
Brak lub false
Zaangażowanie
Odwiedzający co najmniej raz kliknął lub dotknął strony i spędził na niej trochę czasu
Konfiguracje Vite i Next.js
Vite: vite-plugin-pwa
Zainstaluj przez npm i -D vite-plugin-pwa. Wtyczka zapisuje manifest i generuje service worker Workbox podczas builda, więc nie piszesz sw.js ręcznie. Ikony umieść w public/.
Next.js App Router: app/manifest.ts
Next.js serwuje ten plik pod /manifest.webmanifest i sam dodaje tag link. Dla obsługi offline umieść powyższy sw.js w public/ i zarejestruj go z małego komponentu klienckiego.
Next.js: zarejestruj public/sw.js z komponentu klienckiego
Wyrenderuj to raz w app/layout.tsx. Pomiń rejestrację w trybie deweloperskim, aby zbuforowany build nie ukrywał Twoich zmian.
Nazwa aplikacji
Krótka nazwa (pod ikoną)
Startowy URL
Folder ikon
Kolor motywu
Kolor tła
Kopiuj
Generator manifestu
Tryb wyświetlania
Dołącz ikonę maskable
Zapisz ikony jako icon-192.png i icon-512.png (oraz icon-512-maskable.png) w folderze ikon.