Usar o Proxy de Desenvolvimento com WSL

Visão geral
Meta: Usar o Dev Proxy com o Subsistema do Windows para Linux (WSL)
Tempo: 15 minutos
Pré-requisitos:Configurar o Dev Proxy, WSL instalado

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

A abordagem mais simples é instalar e executar o Proxy de Desenvolvimento no Windows. Com o Proxy Automático do WSL e o modo de rede espelhado, o WSL usa o proxy do sistema Windows, portanto, os aplicativos em execução no WSL têm o tráfego interceptado pelo Dev Proxy sem configurar o proxy no WSL.

Configurar a rede WSL

O Dev Proxy registra-se como o proxy do sistema do Windows em um endereço localhost (127.0.0.1:8000 por padrão). Para aplicativos no WSL usarem esse proxy, habilite as seguintes configurações na [wsl2] seção do arquivo de configuração do WSL localizado em %UserProfile%\.wslconfig Windows:

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

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

wsl --shutdown

Observação

No modo de rede NAT padrão, os aplicativos no WSL não podem se conectar ao Dev Proxy no Windows usando 127.0.0.1. Se você não puder usar o modo de rede espelhado, execute o Proxy de Desenvolvimento dentro do WSL. Para obter mais informações, consulte a Opção 2: Proxy de Desenvolvimento dentro do WSL.

Para obter mais informações, consulte Acessar aplicativos de rede com o WSL e Configuração avançada de definições no WSL.

Configurar o Proxy de Desenvolvimento no Windows

  1. Instale o Proxy de Desenvolvimento no Windows usando winget ou instalação manual.

  2. Iniciar Proxy de Desenvolvimento:

    devproxy

  3. Confie no certificado quando solicitado.

Usar o Dev Proxy do WSL

Quando o Dev Proxy é executado como o proxy do sistema no Windows (o comportamento padrão) e você configurou a rede WSL, os aplicativos no WSL roteiam automaticamente o tráfego por ele.

Inicie seu aplicativo no WSL como faria normalmente. O Dev Proxy intercepta solicitações HTTPS feitas por aplicativos que respeitam as configurações de proxy.

Importante

Reinicie o WSL depois de iniciar ou parar o Dev Proxy

O WSL lê as configurações de proxy de Windows quando é iniciado. Se você iniciar o Proxy de Desenvolvimento depois que o WSL já estiver em execução ou se você parar e reiniciar o Proxy de Desenvolvimento, será necessário reiniciar o WSL para que as alterações entrem em vigor:

wsl --shutdown

Em seguida, inicie uma nova sessão WSL.

Confiar no certificado em WSL

Para que o Proxy de Desenvolvimento intercepte o tráfego HTTPS, os aplicativos no WSL precisam confiar no certificado de Proxy de Desenvolvimento. Você pode copiar o certificado do Windows ou exportá-lo usando a API de Proxy de Desenvolvimento.

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 de Proxy de Desenvolvimento

A API do Dev Proxy exige um token de portador. Enquanto o Dev Proxy estiver em execução no Windows, obtenha o token executando o comando api token em um terminal do Windows:

devproxy api token

Em seguida, no WSL, baixe e instale o certificado. Substitua <token> pelo token que você 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

Alguns aplicativos podem exigir uma configuração extra para confiar no repositório de certificados do sistema. Para Node.js aplicativos, talvez seja necessário definir NODE_TLS_REJECT_UNAUTHORIZED=0 para fins de desenvolvimento. Não é recomendável desabilitar a validação de certificado para o código de produção.

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

Se você preferir executar o Proxy de Desenvolvimento inteiramente dentro do WSL, instale-o usando o método de instalação do Linux e configure o proxy manualmente.

Instalar o Proxy de Desenvolvimento no WSL

O script de instalação requer unzip para extrair o Dev Proxy. Distribuições novas do WSL, como o Ubuntu, não a incluem por padrão. Instale unzip:

sudo apt update
sudo apt install unzip

Instale o Proxy de Desenvolvimento usando o script de instalação:

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

Configurar o proxy manualmente

Como o WSL não tem um ambiente de área de trabalho gráfico, o Dev Proxy não pode se registrar automaticamente como o proxy do sistema. Configure seus aplicativos para usar o proxy manualmente.

  1. Crie um arquivo de configuração do Proxy de Desenvolvimento com asSystemProxy definido como 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. Iniciar Proxy de Desenvolvimento:

    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. Configure seu aplicativo 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 seu aplicativo:

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

Dica

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

Comparação de abordagens

Característica Host do Windows (Opção 1) Opção 2: Dentro do WSL
Complexidade de configuração Simples Moderado
Requirements Windows 11 22H2 ou posterior, modo de rede espelhado WSL None
Gerenciamento de certificados Cópia única a partir do Windows Exportação manual
Configuração de proxy Automático (Proxy Automático do WSL) Manual (HTTPS_PROXY)
Reinicialização do WSL necessária Sim, ao alternar proxy Não
Funciona com todos os aplicativos WSL Yes Depende do suporte ao proxy de aplicativo

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

Resolução de problemas

As solicitações não são interceptadas ao usar o host do Windows

Se o Proxy de Desenvolvimento no Windows não estiver interceptando solicitações do WSL:

  1. Verifique se networkingMode=mirrored e autoProxy=true estão definidos na seção [wsl2] do arquivo .wslconfig. Para obter mais informações, consulte Configurar a rede WSL.

  2. Reinicie o WSL para atualizar as configurações de proxy:

    wsl --shutdown

  3. Verifique se o Proxy de Desenvolvimento está em execução e registrado como proxy do sistema.

  4. Verifique se o certificado de Proxy de Desenvolvimento é confiável no WSL.

unzip: comando não encontrado

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

sudo apt update
sudo apt install unzip

Erros de certificado

Se você vir erros de certificado:

  1. Verifique se você instalou o certificado no WSL seguindo as etapas em Confiar no certificado no WSL.
  2. Para Node.js aplicativos, talvez seja necessário configurar o aplicativo para usar o agente proxy. Consulte Uso do Proxy de Desenvolvimento com aplicativos Node.js.

Problemas de rede WSL

O WSL 2 usa um adaptador de rede virtualizado. Se você tiver problemas de rede:

  1. Verifique se o Firewall do Windows permite o Proxy de Desenvolvimento.
  2. Tente usar localhost em vez de 127.0.0.1 ao configurar o endereço proxy.

Conteúdo relacionado

  • Última atualização em