Utilize o Dev Proxy com o WSL

De relance
Objetivo: Utilize o Dev Proxy com o Windows Subsystem para Linux (WSL)
Tempo: 15 minutos
Pré-requisitos:Configurar Dev Proxy, WSL instalado

Ao desenvolver aplicações em WSL (Subsistema Windows para Linux), tem duas opções para usar o Dev Proxy: executá-lo no seu host Windows ou dentro do WSL. Ambas as abordagens têm as suas vantagens dependendo do seu fluxo de trabalho de desenvolvimento.

Opção 1: Proxy de Desenvolvimento no host Windows (recomendado)

A abordagem mais simples é instalar e executar Dev Proxy no Windows. Com o Auto Proxy e o modo de rede espelhada do WSL, o WSL utiliza o proxy do sistema Windows, pelo que as aplicações a correr no WSL têm o seu tráfego intercetado pelo Dev Proxy sem necessidade de configurar o proxy no WSL.

Configurar a rede WSL

O Dev Proxy regista-se como proxy do sistema Windows num endereço localhost (127.0.0.1:8000 por defeito). Para aplicações em WSL utilizarem este proxy, ative as seguintes definições na [wsl2] secção do ficheiro de configuração WSL localizada em %UserProfile%\.wslconfig no Windows:

[wsl2]
networkingMode=mirrored
autoProxy=true

Setting	Description
networkingMode=mirrored	Espelha as interfaces de rede do Windows no Linux, o que permite que aplicações em WSL se liguem a servidores a correr no Windows, como o Dev Proxy, usando 127.0.0.1. Requer Windows 11 versão 22H2 ou posterior. O valor predefinido é nat.
autoProxy=true	Faz com que o WSL use as definições do proxy HTTP do Windows, para que o proxy configurado no Windows seja automaticamente definido no WSL. Disponível no Windows 11. Ativado por padrão.

Depois de alterar o .wslconfig ficheiro, reinicie o WSL para que as alterações entrem em vigor:

wsl --shutdown

Observação

No modo de rede NAT predefinido, as aplicações em WSL não conseguem ligar-se ao Dev Proxy no Windows usando 127.0.0.1. Se não conseguires usar o modo de rede espelhada, executa Dev Proxy dentro do WSL. Para mais informações, consulte a Opção 2: Dev Proxy dentro do WSL.

Para mais informações, consulte Aceder a aplicações de rede com WSL e configuração de definições avançadas em WSL.

Configurar o Proxy de Desenvolvimento no Windows

1. Instala o Proxy de Desenvolvimento no Windows usando o Winget ou instalação manual.

2. Inicie o Dev Proxy:

   devproxy
   

3. Confie no certificado quando solicitado.

Usa o Proxy de Desenvolvimento do WSL

Quando o Dev Proxy corre como proxy do sistema no Windows (o comportamento padrão) e tiveres configurado a rede WSL, as aplicações em WSL encaminham automaticamente o seu tráfego através dele.

Começa a tua candidatura no WSL como farias normalmente. O Dev Proxy interceta pedidos HTTPS feitos por aplicações que respeitam as definições do proxy.

Importante

Reiniciar o WSL depois de iniciar ou parar o Dev Proxy

O WSL lê as definições do proxy do Windows quando arranca. Se iniciar o Dev Proxy depois de o WSL já estar a correr, ou se parar e reiniciar o Dev Proxy, precisa de reiniciar o WSL para que as alterações tenham efeito:

wsl --shutdown

Depois começa uma nova sessão de WSL.

Confie no certificado em WSL

Para que o Proxy de Desenvolvimento intercete o tráfego HTTPS, as aplicações em WSL precisam de confiar no certificado do Proxy de Desenvolvimento. Podes copiar o certificado do Windows ou exportá-lo usando a API Dev Proxy.

Opção A: Copiar o certificado do Windows

1. No WSL, copie o certificado do Windows:

   cp "/mnt/c/Users/<your-username>/AppData/Local/Programs/Dev Proxy/rootCert.pfx" ~/
   

2. Exportar e instalar o certificado:

   # Export the certificate
   openssl pkcs12 -in ~/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
   # Install the certificate
   sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
   # Update certificates
   sudo update-ca-certificates
   

Opção B: Usar a API do Proxy de Desenvolvimento

A API Dev Proxy requer um token portador. Enquanto o Dev Proxy está a correr no Windows, obtenha o token executando o comando token da API num terminal Windows:

devproxy api token

Depois, no WSL, descarrega e instala o certificado. Substitua <token> pelo token que recuperou:

# Download the certificate from Dev Proxy API
curl -H "Authorization: Bearer <token>" -o dev-proxy-ca.crt "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"
# Install the certificate
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
# Update certificates
sudo update-ca-certificates

Observação

Algumas aplicações podem exigir configuração extra para confiar no armazenamento de certificados do sistema. Para Node.js aplicações, pode ser necessário definir NODE_TLS_REJECT_UNAUTHORIZED=0 para fins de desenvolvimento. Desativar a validação de certificados não é recomendado para código de produção.

Opção 2: Proxy de desenvolvimento dentro do WSL

Se preferires correr o Proxy de Desenvolvimento inteiramente dentro do WSL, instala-o usando o método de instalação do Linux e configura o proxy manualmente.

Instalar o Proxy de Desenvolvimento no WSL

O script de configuração exige unzip para extrair o Dev Proxy. Distribuições WSL novas, como o Ubuntu, não o incluem por defeito. Instalar unzip:

sudo apt update
sudo apt install unzip

Instale o Dev Proxy usando o script de configuração:

bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

Configure o proxy manualmente

Como o WSL não tem um ambiente gráfico de ambiente de trabalho, o Dev Proxy não pode registar-se automaticamente como proxy do sistema. Configura as tuas aplicações para usarem o proxy manualmente.

1. Crie um ficheiro de configuração Dev Proxy com asSystemProxy definido para false:

   {
     "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/rc.schema.json",
     "asSystemProxy": false,
     "plugins": [
       {
         "name": "RetryAfterPlugin",
         "enabled": true,
         "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
       },
       {
         "name": "GenericRandomErrorPlugin",
         "enabled": true,
         "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
         "configSection": "genericRandomErrorPlugin"
       }
     ],
     "urlsToWatch": [
       "https://jsonplaceholder.typicode.com/*"
     ],
     "genericRandomErrorPlugin": {
       "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/genericrandomerrorplugin.schema.json",
       "errorsFile": "devproxy-errors.json",
       "rate": 50
     },
     "logLevel": "information"
   }
   

2. Inicie o Dev Proxy:

   devproxy
   

3. Confie no certificado:

   # Export Dev Proxy root certificate
   openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
   # Install the certificate
   sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
   # Update certificates
   sudo update-ca-certificates
   

4. Configura a tua aplicação para usar o proxy. Defina a variável de HTTPS_PROXY ambiente:

   export HTTPS_PROXY=http://127.0.0.1:8000
   

   Ou especifique-o ao executar a sua aplicação:

   HTTPS_PROXY=http://127.0.0.1:8000 node app.js
   

Sugestão

Para mais informações sobre como configurar o proxy para Node.js aplicações, veja Usar Proxy de Desenvolvimento com Node.js aplicações.

Comparação de abordagens

Característica	Host Windows (Opção 1)	Dentro da WSL (Opção 2)
Complexidade da configuração	Simples	Moderado
Requirements	Windows 11 22H2 ou posterior, modo de rede espelhada WSL	None
Gestão de certificados	Cópia única a partir do Windows	Exportação manual
Configuração do proxy	Automático (WSL Auto Proxy)	Manual (HTTPS_PROXY)
Reinício da WSL é necessário	Sim, ao alternar o proxy	Não
Funciona com todas as aplicações WSL	Yes	Depende do suporte para proxy de aplicativo

Para a maioria dos cenários, correr Dev Proxy no Windows (Opção 1) é a abordagem recomendada devido à sua simplicidade e configuração automática do proxy.

Solução de problemas

Os pedidos não são interceptados ao usar o host do Windows

Se o Dev Proxy no Windows não interceptar pedidos do WSL:

1. Verifica se networkingMode=mirrored e autoProxy=true estão definidos na [wsl2] secção do teu .wslconfig ficheiro. Para mais informações, consulte Configurar rede WSL.

2. Reiniciar o WSL para atualizar as definições do proxy:

   wsl --shutdown
   

3. Verifique se o Proxy de Desenvolvimento está a correr e registado como proxy do sistema.

4. Verifica se o certificado Dev Proxy é confiável no WSL.

unzip: comando não encontrado

Se o script de configuração falhar com o unzip: command not found erro, instale unzip e execute novamente o script de configuração:

sudo apt update
sudo apt install unzip

Erros de certificado

Se vir erros de certificado:

1. Certifique-se de que instalou o certificado no WSL seguindo os passos em Confiar no certificado no WSL.
2. Para Node.js aplicações, pode ser necessário configurar a aplicação para usar o agente proxy. Veja Utilizar o Proxy de Dev com aplicações Node.js.

Problemas de rede na WSL

O WSL 2 utiliza um adaptador de rede virtualizado. Se tiver problemas de rede:

1. Assegure-se de que o seu firewall do Windows permite o Dev Proxy.
2. Tente usar localhost em vez de 127.0.0.1 quando configurar o endereço proxy.

Conteúdo relacionado

• Usa Dev Proxy com aplicações Node.js
• Utilize o Dev Proxy com aplicações .NET
• Usar Proxy de Desenvolvimento num contentor Docker