Se um site local ou servidor de desenvolvimento funcionar em 127.0.0.1, mas falhar em localhost, ou funcionar em uma família de endereços e na outra não, verifique o endereço de escuta do servidor e teste cada caminho separadamente. Em um Mac, 127.0.0.1 é o endereço de loopback IPv4 e ::1 é o endereço de loopback IPv6; ambos se referem ao seu próprio computador. Um teste bem-sucedido em um não prova que o serviço esteja escutando no outro.

1. Verifique se o serviço está escutando

Use a porta na qual sua aplicação deve servir. Os exemplos abaixo usam a porta 8000; substitua-a pela porta real.

lsof -nP -iTCP:8000 -sTCP:LISTEN

O lsof lista arquivos abertos, incluindo sockets de rede. As opções restringem os resultados aos listeners TCP nessa porta e evitam a resolução de nomes. Se não houver saída, o serviço pode não estar em execução, pode usar uma porta diferente ou pode não ter aberto um listener TCP. Verifique a saída de inicialização da aplicação e a porta configurada antes de alterar as configurações de rede do macOS. (Manual do lsof)

Observe o endereço na coluna NAME. Um listener exibido em 127.0.0.1:8000 está vinculado ao loopback IPv4; um exibido em [::1]:8000 está vinculado ao loopback IPv6. Um endereço curinga pode indicar que está escutando em mais do que apenas o loopback, dependendo do servidor e do sistema operacional. O diagnóstico fundamental é verificar se o endereço de bind real do servidor inclui a família de endereços que você está testando. Essa interpretação decorre do endereço de socket que está sendo relatado pelo lsof; a configuração da aplicação determina qual endereço o servidor abre.

2. Teste o IPv4 e o IPv6 diretamente

Faça uma requisição para a mesma porta e caminho por meio de cada endereço de loopback. O curl permite testar a conexão HTTP sem depender da seleção de endereços de um navegador.

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

Os colchetes são obrigatórios ao redor de um literal IPv6 em uma URL; -g diz ao curl para não tratá-los como sintaxe de globbing de URL. As aspas simples preservam a URL literalmente nos shells padrão do macOS. O Curl documenta essas regras de URL e fornece --ipv4 e --ipv6 para restringir a resolução de nomes de host. (Sintaxe de URL do curl, manual do curl)

Uma recusa de conexão geralmente significa que não há nenhum listener aceitando conexões naquele endereço e porta. Um timeout (tempo limite esgotado) sugere que a conexão não foi concluída dentro do limite. Se o curl exibir uma resposta HTTP, incluindo um status de erro como 404, a conexão TCP e HTTP alcançou um servidor; investigue o caminho ou a resposta da aplicação em vez de tratar isso como uma falha de conexão IPv4/IPv6.

3. Compare o localhost com cada endereço

Agora teste o nome de host usando as opções IPv4 e IPv6 do curl e, em seguida, tente sem restrição de família:

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/

As opções -4 e -6 do curl solicitam endereços apenas IPv4 ou apenas IPv6 para nomes de host. Sua documentação observa que o macOS pode retornar endereços mapeados para IPv4 em uma solicitação de resolução apenas IPv6; portanto, trate esses testes como tentativas de conexão restritas do curl, não como uma auditoria completa do comportamento do resolvedor de todas as aplicações. (Manual do curl)

Use os resultados para delimitar a causa. Se o teste direto de IPv4 funcionar e o teste direto de IPv6 falhar, enquanto o lsof mostrar apenas um listener IPv4, provavelmente o servidor precisará ser configurado para escutar também em IPv6, se o acesso IPv6 for necessário. O inverso se aplica quando apenas o listener IPv6 funciona. Se ambos os testes diretos funcionarem, mas o localhost não, compare os resultados do curl com família forçada e inspecione as configurações de nome de host, proxy ou URL da aplicação. Aplicações diferentes podem resolver nomes ou conectar-se a eles de maneiras diferentes; a Apple recomenda APIs de rede agnósticas quanto à família de endereços para desenvolvedores que criam apps que precisam lidar com IPv4 e IPv6. (Apple Developer: Suporte a redes somente IPv6)

4. Aplique a correção onde as evidências indicarem

Quando apenas um endereço de loopback aceitar conexões, altere a configuração de endereço de vinculação (bind address) do servidor local ou use a família de endereços à qual ele realmente oferece suporte. Não presuma que alterar as configurações de IPv4 ou IPv6 do Wi-Fi do Mac corrigirá um listener de loopback: as solicitações de loopback têm como destino o próprio Mac, enquanto essas configurações de Rede configuram a conexão de rede de uma interface. Os controles de TCP/IP da Apple podem configurar o IPv4 e o IPv6 para um serviço de rede selecionado, mas não configuram o socket de escuta de uma aplicação individual. (Suporte da Apple: Alterar as configurações de TCP/IP no Mac)

Se nenhum dos endereços diretos funcionar, verifique se o servidor está em execução, se a porta está correta e se o protocolo esperado é HTTP ou HTTPS. Se um endereço direto funcionar, mas os testes com o nome de host forem diferentes, use o endereço do lsof e a saída do curl em conjunto para decidir se deve ajustar o endereço de bind do servidor ou a URL do cliente. Essa sequência distingue a falta de um listener de um problema de bind específico de uma família, sem presumir que toda falha de localhost seja um problema de DNS.

Fontes