localhost nie działa między WSL a Windows

Localhost niedziałający między WSL a Windows w starszych wersjach WSL1 wymagał ręcznego przekierowania portów — WSL2 domyślnie współdzieli localhost z hostem Windows.

Co oznacza problem „localhost nie działa między WSL a Windows”

Określenie to opisuje sytuację, w której aplikacja uruchomiona w środowisku Windows Subsystem for Linux nie może połączyć się z usługą działającą w systemie Windows przez adres localhost, albo odwrotnie. Sam zapis localhost oznacza komputer, z którego wykonywane jest połączenie, ale w układzie Windows–WSL znaczenie tego adresu zależy od wersji WSL, sposobu uruchomienia środowiska oraz konfiguracji sieciowej. Dlatego ten sam adres wpisany w przeglądarce Windows i użyty w poleceniu curl wewnątrz WSL może wskazywać różne interfejsy.

W WSL1 procesy linuksowe korzystają znacznie bliżej ze stosu sieciowego Windows, natomiast WSL2 działa w lekkiej maszynie wirtualnej z własnym interfejsem sieciowym. W praktyce wpływa to na kierunek połączenia. Usługa uruchomiona w WSL2 może nie być dostępna z Windows przez localhost, jeśli przekazywanie portu nie działa, usługa nasłuchuje wyłącznie na adresie pętli zwrotnej Linuksa albo ustawienia danego wydania WSL nie zapewniają automatycznego mapowania. W nowszych konfiguracjach część funkcji poprawiających dostęp przez localhost jest dostępna domyślnie, lecz nie należy zakładać, że zachowanie będzie identyczne na każdym komputerze.

Problem nie musi oznaczać awarii samej aplikacji. Często działa ona poprawnie, ale pozostaje dostępna tylko pod adresem 127.0.0.1 wewnątrz WSL, podczas gdy połączenie przychodzi z systemu Windows przez inny interfejs. Znaczenie ma również port, na którym uruchomiono usługę, protokół używany przez aplikację oraz to, czy połączenie jest wykonywane z terminala, przeglądarki, kontenera czy narzędzia deweloperskiego.

Jak działa komunikacja WSL2 z systemem Windows

Najpierw należy rozdzielić dwa kierunki ruchu: Windows do WSL oraz WSL do Windows. Jeżeli serwer deweloperski działa w WSL2, a przeglądarka jest uruchomiona w Windows, dostęp pod http://localhost:PORT może zadziałać dzięki mechanizmowi automatycznego przekazywania portów. Gdy funkcja ta nie jest aktywna, konieczne może być użycie adresu interfejsu WSL albo ręczne przekierowanie portu. Adres środowiska WSL2 może się zmieniać po ponownym uruchomieniu, dlatego rozwiązanie oparte wyłącznie na aktualnym adresie IP bywa nietrwałe.

W odwrotnym kierunku, gdy program w WSL2 ma połączyć się z usługą uruchomioną w Windows, localhost oznacza przede wszystkim bieżące środowisko Linux. Nie zawsze wskazuje więc usługę działającą na hoście Windows. W zależności od konfiguracji można potrzebować adresu bramy widocznego z WSL, nazwy hosta rozpoznawanej przez system albo ustawień trybu sieciowego. Samo uruchomienie usługi w Windows nie gwarantuje dostępności z WSL, ponieważ aplikacja może nasłuchiwać tylko na interfejsie loopback albo połączenie może być filtrowane przez Zaporę systemu Windows.

Przy diagnozie warto ustalić, na jakim adresie nasłuchuje usługa. Serwer przypięty do 127.0.0.1 przyjmuje połączenia lokalne tylko z określonego środowiska, natomiast nasłuchiwanie na wszystkich interfejsach może umożliwić dostęp przez adres sieciowy. Takiej zmiany nie powinno się jednak wykonywać bez sprawdzenia wpływu na bezpieczeństwo. W środowisku testowym można dodatkowo zweryfikować, czy port jest otwarty, czy nazwa hosta jest poprawnie rozpoznawana oraz czy aplikacja rzeczywiście korzysta z tego samego portu, który został wpisany w adresie.

Pomocne jest sprawdzenie stanu WSL poleceniami administracyjnymi, informacji o adresach interfejsów, mapowania portów i reguł zapory. Należy też uwzględnić plik konfiguracyjny WSL oraz ustawienia związane z integracją sieciową. W przypadku usług uruchamianych w Dockerze dodatkową warstwę stanowi publikowanie portu kontenera, ponieważ port dostępny w kontenerze nie musi być automatycznie dostępny na hoście Windows ani bezpośrednio w dystrybucji WSL.

Najczęstsze przyczyny niedostępnego localhost

Jednym z typowych powodów jest błędny adres bindowania. Framework aplikacji może domyślnie uruchamiać serwer wyłącznie na 127.0.0.1, przez co połączenie z innego środowiska zostaje odrzucone. W podobny sposób może działać usługa skonfigurowana na konkretnym adresie IPv4, gdy klient próbuje połączyć się przez IPv6, na przykład z użyciem ::1. Różnica między localhost, 127.0.0.1 a adresem interfejsu WSL może wtedy wskazać, czy problem dotyczy rozpoznawania nazwy, routingu czy samego serwera.

Częstym błędem jest również pomylenie portu aplikacji z portem wystawionym przez narzędzie uruchomieniowe. Program może działać na jednym porcie, ale konfiguracja przekierowania, plik projektu, kontener lub skrypt startowy może udostępniać inny. Warto odczytać port bezpośrednio z komunikatu startowego aplikacji i porównać go z wynikiem testu połączenia. Sam fakt, że proces jest widoczny na liście uruchomionych zadań, nie potwierdza jeszcze, że nasłuchuje on na właściwym interfejsie.

Przyczyną może być zapora Windows, oprogramowanie ochronne, firmowa polityka sieciowa albo filtr działający w dystrybucji Linux. Zdarza się także, że usługa kończy pracę po uruchomieniu, ale terminal pozostawia komunikat sugerujący poprawny start. W takim przypadku należy sprawdzić logi aplikacji, kod zakończenia procesu i próbę połączenia z tego samego środowiska, w którym działa serwer. Jeżeli połączenie lokalne w WSL działa, a połączenie z Windows nie, poszukiwania należy skierować w stronę przekierowania portów, interfejsu nasłuchu i zapory.

Osobną grupę problemów stanowią zmiany po aktualizacji Windows, WSL lub dystrybucji Linux. Mogą one zmienić tryb sieciowy, sposób rozwiązywania nazw albo zachowanie automatycznego przekazywania portów. Warto sprawdzić wersję WSL, stan używanej dystrybucji, ustawienia integracji oraz to, czy problem występuje po ponownym uruchomieniu systemu. Należy unikać trwałego wpisywania przypadkowego adresu IP do konfiguracji aplikacji bez ustalenia, czy adres nie będzie się zmieniał.

Kiedy trzeba przekazać urządzenie do naprawy - localhost nie działa między WSL a Windows

Zgłoszenie do serwisu jest uzasadnione, gdy po sprawdzeniu procesu, portu i adresu nasłuchu nadal nie można ustalić, na którym etapie połączenie jest blokowane. Dotyczy to zwłaszcza sytuacji, w której jednocześnie używane są WSL2, kontenery, kilka dystrybucji Linux, lokalne serwery deweloperskie oraz zapora systemowa. Nieprawidłowa zmiana ustawień sieciowych może przy tym zakłócić działanie innych programów, dlatego bezpieczniej jest poprzedzić ją analizą konfiguracji i kopią istotnych plików.

W Warszawie takie przypadki można przekazać do „Warszawskiego Pogotowia Komputerowego 24/7”, gdzie problem może zostać przeanalizowany razem z ustawieniami Windows, dystrybucji WSL, usług i reguł sieciowych. Podczas zgłoszenia warto opisać, w którym kierunku ma działać połączenie, jaki port jest używany, z jakiego środowiska wykonywany jest test oraz jaki komunikat błędu się pojawia. Pomocne będzie również wskazanie, czy usługa działa bezpośrednio w Windows, w WSL, czy wewnątrz kontenera.

Przed przekazaniem komputera można przygotować kopię konfiguracji projektu, listę używanych poleceń i wynik prostych testów połączenia, bez udostępniania haseł ani kluczy dostępowych. Takie dane ułatwiają odtworzenie problemu i odróżnienie awarii aplikacji od błędu warstwy sieciowej. Po przywróceniu komunikacji należy jeszcze sprawdzić działanie po ponownym uruchomieniu Windows, WSL i aplikacji, ponieważ rozwiązanie zależne od chwilowego adresu lub ręcznie uruchomionego przekierowania może nie przetrwać restartu.