Pułapki przy aktualizacji na Next.js 16: domyślne ścieżki równoległe i middleware do proxyowania

Najwięcej wysiłku przy aktualizacji do Next.js 16 poświęcono zmianom w obszarze asynchronicznego użycia params i searchParams, ponieważ powodują one poważne problemy wszędzie tam, gdzie są stosowane. Dwie mniej uderzające zmiany w routingu wymagają równie dużej uwagi: sloty trasowe typu parallel teraz wymagają wyraźnego pliku default.js, a intercepcja żądań przenosi się z middleware.ts do nowej konwencji proxy.ts. Żadna z tych zmian nie uszkadza stron, po których korzystasz codziennie, i właśnie dlatego umykają one uwadze podczas testowania. Ten przewodnik wyjaśnia obie zmiany, dlaczego pojawiają się późno oraz dostarcza listę kontrolną do przeprowadzenia przed wdrożeniem aktualizacji.

Sloty trasowe typu parallel wymagają pliku default.js

Ścieżki równoległe wykorzystują foldery z prefiksem @, aby zdefiniować nazwane pola, które układ renderuje obok siebie. Klasycznym przykładem są panele sterowania: główna obszar zawartości obok trwałego feedu aktywności lub panelu powiadomień, z których każdy ma własny stan nawigacji.

W Next.js 16 od każdego pola oczekuje się istnienia pliku default.js. To właśnie ten plik jest renderowany przez Next.js dla danego pola, gdy aktualna URL nie zawiera bardziej specyficznego dopasowania. Bez takiego pliku nawigacja prowadząca do takiej kombinacji zwraca błąd 404 zamiast przejść w tryb awaryjny, a według notatek dotyczących aktualizacji do Next.js 16 sam proces budowania może teraz odmówić dalszej pracy, jeśli dane pole nie ma pliku default – dlatego należy sprawdzić dokładne zachowanie w swojej wersji. Panel sterowania z polem feed wygląda tak:

app/
  dashboard/
    @feed/
      page.tsx       ← the "active" state for this slot
      default.js      ← required fallback when no more-specific match exists
    layout.tsx
    page.tsx

Rozwiązanie awaryjne rzadko musi wykonywać wiele działań. Wyświetlenie wartości null ukrywa dane w danym polu, a komponent stanu pustego sprawdza się wtedy, gdy chcesz, aby panel pozostał widoczny:

// app/dashboard/@feed/default.js
export default function Default() {
  return null;
}

Dlaczego brakujący standardowy stan pojawia się późno

Podczas rozwoju przeważnie przechodzimy między stanami, które stworzyliśmy i przetestowaliśmy, a wszystkie one odpowiadają czemuś w każdym polu. Problem pojawia się, gdy użytkownik trafi na kombinację, której nikt wcześniej nie wypróbował: łącze głębokie, odświeżenie strony na zagnieżdżonej adrese URL lub ścieżka istniejąca dla głównego treści, ale nie dla feedu. Pełne załadunek strony nie może ponownie wykorzystać poprzedniego stanu pola, dlatego Next.js potrzebuje pliku default.js, aby wiedzieć, co ma wyświetlić. W praktyce oznacza to, że błąd 404 jest często zgłaszany przez zdezorientowanego klienta w środowisku produkcyjnym, a nie wykrywany podczas rozwoju. Dodanie pliku dla każdego pola, nawet jeśli uważasz, że nigdy nie zostanie ono użyte, to tanie ubezpieczenie.

Od middleware.ts do proxy.ts

Druga zmiana dotyczy przechwytywania żądań na poziomie. Next.js 16 wprowadza proxy.ts jako standardową nazwę pliku dla logiki, która wcześniej znajdowała się w middleware.ts, a stara nazwa jest stopniowo usuwana. W chwili pisania tej treści migracja polega na przemianowaniu pliku oraz funkcji, którą on eksportuje, przy czym proxy ma działać w środowisku Node.js; szczegóły oraz oficjalny kod do wykonania tych działań znajdują się w aktualnej dokumentacji.

Jeśli twój middleware jest prosty, przeniesienie go zajmuje niewiele czasu. Jeśli pełni ważne funkcje, takie jak weryfikacja autoryzacji, identyfikacja użytkowników na poddomenach, przekierowania lub modyfikacja nagłówków, traktuj to jako zmianę kodu wymagającą przeglądu, a nie tylko przemianowania pliku.

Przeglądaj funkcje pojedynczo, a nie tylko poprzez przemianowanie nazw

Słепa operacja wyszukiwania i zastępowania z pliku middleware.ts do proxy.ts zakłada, że każda część logiki zachowuje się identycznie według nowych zasad. Zamiast tego przeanalizuj, co faktycznie robi dany plik, i sprawdź każdą z jego funkcji osobno:

• kterze żądania są objęte konfiguracją matchera oraz czy dodano lub usunięto jakieś ścieżki
• w jaki sposób podejmowane są decyzje dotyczące autoryzacji i co się dzieje, gdy sesja jest brakująca lub wygasła
• w jaki sposób identyfikatory użytkowników są wydobywane z nazw hostów lub nagłówków i przekazywane dalej
• kterze przekierowania i przepisywania są uruchamiane oraz w jakiej kolejności
• kterze nagłówki są odczytywane, dodawane lub usuwane

To właśnie na tym poziomie subtelna różnica w zachowaniu przekształca się z problemu estetycznego w lukę bezpieczeństwa. Pominięcie wpisu do listy dopasowań może spowodować, że dana trasa będzie dostępna bez autoryzacji; zmiana nagłówka może zniszczyć izolację poszczególnych użytkowników. Dlatego wymaga ona dokładnej analizy oraz testów od początku do końca, a nie tylko szybkich sprawdzeń wizualnych.

Dwie niespowiązane ze sobą zmiany o tym samym schemacie awarii

Standardowe ustawienia tras oraz migracja proxy technicznie nie mają ze sobą nic wspólnego. Zespoły zazwyczaj odkrywają je podczas tej samej aktualizacji, ponieważ wykazują wspólny schemat: obie w większości przypadków działają w środowisku rozwojowym, ale przestają działać w konkretnych scenariuszach produkcyjnych, których trudno odtworzyć.

Taki wzorzec zasługuje na nazwę. Zmiany, które zakłócają załadunek każdej strony, są wykrywane w ciągu kilku minut. Te ryzykowne pojawiają się jedynie przy nietypowych ścieżkach nawigacji lub określonych formatach żądań, więc zwykłe ręczne kliknięcie nigdy ich nie aktywuje. Twój plan testowania powinien celowo obejmować takie ścieżki.

Lista kontrolna audytu przed aktualizacją

Zanim oznaczysz, że aktualizacja do Next.js 16 została zakończona, sprawdź następujące kwestie:

1. Każda równoległa ścieżka ma plik default.js. Przeszukaj katalog app/ w poszukiwaniu folderów zaczynających się na @ i sprawdź każdy z nich.
2. Logika middleware została przeanalizowana pod kątem konwencji proxy.ts, jedna funkcja po drugiej, bez zmiany nazwy i bez zakładania jej identyczności z innymi elementami.

Po migracji przeprowadzono pełne testy autoryzacji i rozwiązywania problemów z tenantami, w tym przypadki negatywne takie jak brak sesji lub nieznany poddomen.

Celowo sprawdzano nietypowe ścieżki nawigacyjne, takie jak głębokie linki, ponowne załadowanie stron z zagnieżdżonych URL-ów oraz trasy, do których normalny kliknięcie nigdy by nie dotarło, ponieważ właśnie tam kryją się równoległe błędy 404.

Dlaczego panele multi-tenant niosą największe ryzyko

Panele SaaS często łączą obie te funkcje: równoległe trasy dla poszczególnych paneli oraz middleware, który mapuje poddomenę na konkretnego tenanta przed wyświetleniem jakiejkolwiek strony. To sprawia, że rozwiązywanie problemów z tenantami znajduje się bezpośrednio w kodzie najbardziej dotkniętym zmianą proxy.

Błąd w tym miejscu rzadko skutkuje widocznymi konsekwencjami. Zamiast strony błędu otrzymuje się raporty o tym, że jeden użytkownik przez chwilę miał dostęp do danych innego użytkownika, co stanowi incydent o podobnym stopniu powagi, jaki może mieć produkt SaaS. Obrona wielowarstwowa pomaga: nawet gdy proxy identyfikuje użytkownika, dostęp do danych w komponentach serwera i obsługujących ścieżki powinien ponownie sprawdzać prawa własności użytkownika, zamiast polegać na informacjach z nagłówków przekazanych z góry. Cacheowanie oparte na tagach wymaga takiej samej ostrożności, ponieważ klucze cache’u muszą zawierać informacje o użytkowniku; artykuł na temat Next.js 16 use cache i tag-based revalidation omawia ten aspekt.

Częste pytania

Czy pominięcie default.js powoduje niewidoczne błędy?

Nie do końca. W wersjach, które egzekwują to zasady, pojawia się błąd 404 lub błąd kompilacji, ale tylko dla ścieżek nawigacyjnych prowadzących do brakującego fallbacku. Ponieważ błąd pojawia się daleko od elementu, który go spowodował, łatwo jest błędnie uznać go za ogólny błąd routingu, chyba że znasz tę zmianę.

Czy możesz na razie nadal używać middleware.ts?

Zobacz dokumentację Next.js dla swojej dokładnej wersji minor, ponieważ wsparcie dla starej konwencji jest w ciągłym rozwoju. Biorąc pod uwagę, jak często w tym pliku znajduje się logika autoryzacji, odkładanie migracji na nieokreślony czas jest bardziej ryzykowne niż odroczenie większości innych zadań związanych z aktualizacją, a przeprowadzenie jej wcześnie daje czas na dokładną analizę.

Jak szybko znaleźć elementy typu slot bez pliku default.js?

Znajdź foldery w katalogu app/, których nazwy zaczynają się od @, i wylistuj te, które nie zawierają pliku default.js (lub default.tsx). Jedno przeszukanie za pomocą funkcji wyszukiwania plików w twoim edytorze lub krótka komenda w shellu pozwoli znaleźć wszystkie takie braki.

Podsumowanie

Najbardziej problematycznymi zmianami w Next.js 16 są te, które zakłócają normalny przebieg aplikacji. Szyny tras równoległych bez pliku domyślnego oraz pośpiesznie przemienione proxy przechodzą proste testy, ale zawodzą w przypadkach krawędziowych, czasami powodując problemy z bezpieczeństwem. Dodaj plik domyślny do każdej szyny, przeanalizuj logikę przechwytywania zadań po kolei i przeznacz odpowiedni czas na rzeczywiste testy tras, których zwykłe przeglądanie nigdy nie obejmuje.

Literatura pokrewna

• Jedyny źródło prawdy dla dróg w aplikacjach Next.js — Dowiedz się, jak typowany centralny moduł dróg zastępuje rozproszone ścieżki tekstowe w Next.js, dzięki funkcjom pomocniczym do obsługi dynamicznych segmentów i grupowania eksportów dróg.
• Migracja z next/router: Params, Shallow URLs i 404s w App Router — Zobacz, jak params, useParams, aktualizacje ścieżek typu shallow URL, nawigacja programowa oraz prawdziwe strony 404 funkcjonują w Next.js App Router po usunięciu next/router.