Si un site web local ou un serveur de développement fonctionne sur 127.0.0.1 mais échoue sur localhost, ou fonctionne sur une famille d’adresses mais pas sur l’autre, vérifiez l’adresse d’écoute du serveur et testez chaque chemin séparément. Sur un Mac, 127.0.0.1 est l’adresse de bouclage IPv4 et ::1 est l’adresse de bouclage IPv6 ; toutes deux font référence à votre propre ordinateur. Un test réussi sur l’une ne prouve pas que le service écoute sur l’autre.

1. Vérifier si le service est en écoute

Utilisez le port sur lequel votre application est censée fonctionner. Les exemples ci-dessous utilisent le port 8000 ; remplacez-le par le port réel.

lsof -nP -iTCP:8000 -sTCP:LISTEN

lsof répertorie les fichiers ouverts, y compris les sockets réseau. Les options permettent de restreindre les résultats aux écouteurs TCP sur ce port et d’éviter la résolution des noms. S’il n’y a aucune sortie, le service n’est peut-être pas en cours d’exécution, utilise peut-être un autre port ou n’a peut-être pas ouvert d’écouteur TCP. Vérifiez la sortie de démarrage de l’application et le port configuré avant de modifier les réglages réseau de macOS. (manuel lsof)

Examinez l’adresse dans la colonne NAME. Un écouteur affiché sur 127.0.0.1:8000 est lié au bouclage IPv4 ; un écouteur affiché sur [::1]:8000 est lié au bouclage IPv6. Une adresse générique (wildcard) peut indiquer une écoute au-delà du bouclage, selon le serveur et le système d’exploitation. Le diagnostic clé consiste à déterminer si l’adresse de liaison (bind) réelle du serveur inclut la famille d’adresses que vous testez. Cette interprétation découle de l’adresse de socket rapportée par lsof ; la configuration de l’application détermine l’adresse que le serveur ouvre.

2. Tester IPv4 et IPv6 directement

Effectuez une requête vers le même port et le même chemin via chaque adresse de bouclage. curl vous permet de tester la connexion HTTP sans dépendre de la sélection d’adresse d’un navigateur.

curl -v --connect-timeout 3 http://127.0.0.1:8000/
curl -g -v --connect-timeout 3 'http://[::1]:8000/'

Les crochets sont requis autour d’une adresse littérale IPv6 dans une URL ; -g indique à curl de ne pas les traiter comme une syntaxe de globbing d’URL. Les guillemets simples préservent l’URL littéralement dans les shells par défaut de macOS. Curl documente ces règles d’URL et fournit --ipv4 et --ipv6 pour contraindre la résolution des noms d’hôte. (syntaxe d’URL de curl, manuel de curl)

Un refus de connexion signifie généralement qu’aucun écouteur n’accepte de connexions à cette adresse et à ce port. Un délai d’attente dépassé (timeout) suggère que la connexion n’a pas abouti dans la limite impartie. Si curl affiche une réponse HTTP, y compris un code d’erreur tel que 404, la connexion TCP et HTTP a bien atteint un serveur ; examinez le chemin ou la réponse de l’application plutôt que de traiter cela comme un échec de connexion IPv4/IPv6.

3. Comparer localhost avec chaque adresse

Testez maintenant le nom d’hôte à l’aide des options IPv4 et IPv6 de curl, puis essayez sans restriction de famille :

curl -4 -v --connect-timeout 3 http://localhost:8000/
curl -6 -v --connect-timeout 3 http://localhost:8000/
curl -v --connect-timeout 3 http://localhost:8000/

Les options -4 et -6 de curl demandent des adresses IPv4 uniquement ou IPv6 uniquement pour les noms d’hôte. Sa documentation précise que macOS peut renvoyer des adresses mappées en IPv4 lors d’une demande de résolution IPv6 uniquement ; considérez donc ces tests comme des tentatives de connexion contraintes de curl, et non comme un audit complet du comportement du résolveur de chaque application. (manuel de curl)

Utilisez les résultats pour cerner la cause. Si le test IPv4 direct fonctionne et que le test IPv6 direct échoue, alors que lsof n’indique qu’un écouteur IPv4, le serveur doit probablement être configuré pour écouter également sur IPv6 si l’accès IPv6 est requis. L’inverse s’applique lorsque seul l’écouteur IPv6 fonctionne. Si les deux tests directs fonctionnent mais pas localhost, comparez les résultats de curl avec famille imposée et inspectez le nom d’hôte, le proxy ou les paramètres d’URL de l’application. Différentes applications peuvent résoudre ou se connecter aux noms différemment ; Apple recommande des API réseau indépendantes de la famille d’adresses pour les développeurs qui créent des applications devant gérer IPv4 et IPv6. (Apple Developer: Supporting IPv6-only Networks)

4. Appliquer le correctif là où les éléments le justifient

Lorsque seule l’une des adresses de bouclage accepte les connexions, modifiez la configuration de l’adresse de liaison (bind) du serveur local ou utilisez la famille d’adresses qu’il prend réellement en charge. Ne partez pas du principe que la modification des paramètres Wi-Fi IPv4 ou IPv6 du Mac corrigera un écouteur de bouclage : les requêtes de bouclage ciblent le Mac lui-même, tandis que ces réglages Réseau configurent la connexion réseau d’une interface. Les commandes TCP/IP d’Apple permettent de configurer IPv4 et IPv6 pour un service réseau sélectionné, mais elles ne configurent pas le socket d’écoute d’une application individuelle. (Assistance Apple : Modifier les réglages TCP/IP sur Mac)

Si aucune des adresses directes ne fonctionne, vérifiez que le serveur est bien en cours d’exécution, que le port est correct et que le protocole attendu est HTTP ou HTTPS. Si une adresse directe fonctionne mais que les tests de nom d’hôte diffèrent, utilisez conjointement l’adresse fournie par lsof et la sortie de curl pour décider s’il faut ajuster l’adresse de liaison du serveur ou l’URL du client. Cet enchaînement permet de distinguer un écouteur manquant d’un problème de liaison propre à une famille d’adresses, sans supposer que chaque échec de localhost est un problème de DNS.

Sources