Usando proxy com gerenciadores de pacotes

Para usar um proxy com gerenciadores de pacotes como npm, pip e composer, configure as definições de proxy por meio de variáveis de ambiente (HTTP_PROXY, HTTPS_PROXY), argumentos de linha de comando ou arquivos de configuração específicos de cada gerenciador de pacotes.

Muitos ambientes de desenvolvimento operam atrás de firewalls corporativos ou exigem monitoramento de tráfego, o que torna necessário o uso de um servidor proxy HTTP ou HTTPS para as conexões de saída. Os gerenciadores de pacotes, que baixam dependências de registries externos, precisam ser configurados para rotear suas requisições de rede por esses proxies para funcionar corretamente.

Conceitos gerais de configuração de proxy

Servidores proxy podem interceptar e encaminhar tráfego HTTP e HTTPS. Muitas vezes é necessária autenticação para acessar esses proxies.

Formato da URL do proxy

O formato padrão de uma URL de proxy, incluindo autenticação opcional, é:

protocol://[user:password@]host:port

• protocol: http ou https
• user:password: credenciais opcionais para autenticação no proxy.
• host: o hostname ou endereço IP do servidor proxy.
• port: a porta em que o servidor proxy escuta (por exemplo, 8080, 3128).

Exemplo: http://user:[email protected]:8080

Variáveis de ambiente

O método mais comum e geralmente reconhecido de forma universal para configurar proxies em diversas ferramentas, incluindo gerenciadores de pacotes, é por meio das variáveis de ambiente padrão.

• HTTP_PROXY ou http_proxy: define o servidor proxy para requisições HTTP.
• HTTPS_PROXY ou https_proxy: define o servidor proxy para requisições HTTPS.
• NO_PROXY ou no_proxy: uma lista separada por vírgulas de hostnames, domínios ou endereços IP que devem ignorar o proxy. Isso é essencial para acessar recursos internos ou servidores de desenvolvimento local diretamente.

Essas variáveis normalmente não diferenciam maiúsculas de minúsculas no Windows, mas diferenciam em sistemas Unix-like. É prática comum definir tanto as versões em UPPER_CASE quanto em lower_case para máxima compatibilidade.

# Example for Unix-like systems (Linux, macOS)
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080" # Muitas vezes o mesmo que HTTP_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

# For Windows Command Prompt
set HTTP_PROXY=http://user:[email protected]:8080
set HTTPS_PROXY=http://user:[email protected]:8080
set NO_PROXY=localhost,127.0.0.1,.internal.domain.com

# For Windows PowerShell
$env:HTTP_PROXY="http://user:[email protected]:8080"
$env:HTTPS_PROXY="http://user:[email protected]:8080"
$env:NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

npm (Node Package Manager)

O npm pode ser configurado pelo seu sistema de configuração interno ou por variáveis de ambiente.

Configuração via npm config

O método preferido para o npm é definir as configurações de proxy diretamente na sua configuração. Isso armazena as definições de forma persistente.

# Set HTTP proxy
npm config set proxy http://user:[email protected]:8080

# Set HTTPS proxy (often the same as HTTP proxy)
npm config set https-proxy http://user:[email protected]:8080

# To unset a proxy
npm config rm proxy
npm config rm https-proxy

# Verify settings
npm config get proxy
npm config get https-proxy

Se o seu proxy não exigir autenticação, omita o trecho user:password@.

Problemas com certificados SSL

Ao usar um proxy HTTPS ou um registry HTTPS através de um proxy HTTP, o npm pode encontrar problemas de verificação de certificado SSL. Isso acontece quando o proxy intercepta e recriptografa o tráfego HTTPS com seu próprio certificado, que não é confiável para o seu sistema.

Para resolver isso, você pode:
1. Adicionar o certificado CA do proxy ao repositório de confiança do seu sistema. Essa é a abordagem segura recomendada.
2. Indicar ao npm um arquivo de certificado CA específico:
bash npm config set cafile /path/to/proxy/ca-certificate.pem
3. Desativar a verificação estrita de SSL (não recomendado em produção):
bash npm config set strict-ssl false
Isso ignora a validação de certificado e pode expor você a ataques man-in-the-middle. Use apenas para depuração temporária em ambientes controlados.

Configuração do registry

Se a sua organização usa um registry npm privado (por exemplo, Nexus, Artifactory) acessível diretamente ou por outro proxy, verifique se a configuração registry está correta.

npm config set registry https://my-private-registry.example.com/npm/

pip (Python Package Installer)

O pip aceita configuração de proxy por flags de linha de comando, variáveis de ambiente ou um arquivo de configuração.

Flag de linha de comando

Para um único comando pip, use a flag --proxy:

pip install some-package --proxy http://user:[email protected]:8080

Arquivo de configuração

Para configurações de proxy persistentes, altere ou crie o arquivo de configuração do pip.
* Linux/macOS: ~/.config/pip/pip.conf ou ~/.pip/pip.conf
* Windows: %APPDATA%\pip\pip.ini ou %HOME%\pip\pip.ini

Adicione o seguinte à seção [global]:

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
proxy = http://user:[email protected]:8080

Variáveis de ambiente

O pip respeita as variáveis de ambiente padrão HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Se estiverem definidas, serão usadas automaticamente.

export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
pip install some-package

Problemas com certificados SSL

Assim como o npm, o pip pode apresentar erros de SSL.
1. Adicione o certificado CA do proxy ao repositório de confiança do sistema.
2. Defina um host confiável para o índice:
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] trusted-host = pypi.org
Isso faz o pip confiar no host indicado mesmo que a validação SSL falhe para ele. Use com cautela.
3. Defina um bundle CA personalizado:
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] cert = /path/to/proxy/ca-bundle.pem
Ou pela linha de comando: pip install some-package --cert /path/to/proxy/ca-bundle.pem

Índices de pacotes privados

Se você usa um índice privado de pacotes Python (por exemplo, Artifactory, Nexus), configure index-url ou extra-index-url:

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
index-url = https://my-private-pypi.example.com/simple/

Composer (PHP Dependency Manager)

O Composer depende fortemente de variáveis de ambiente para a configuração de proxy e também pode precisar das configurações de proxy do Git para repositórios obtidos via Git.

Variáveis de ambiente

O Composer usa principalmente as variáveis de ambiente padrão HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
composer install

Configuração do Composer (config.json)

Embora o Composer não tenha uma configuração proxy direta no seu config.json para tráfego HTTP/HTTPS geral, é possível configurar proxy para repositórios VCS específicos caso eles não sejam cobertos pelas variáveis de ambiente ou se forem necessários proxies diferentes.

Por exemplo, para configurar um proxy para o Git:

{
    "config": {
        "github-oauth": {
            "github.com": "YOUR_OAUTH_TOKEN"
        }
    }
}

Isso não é uma configuração de proxy propriamente dita, mas mostra onde outras configurações relacionadas à rede podem ficar. Para o proxy real do Git, veja a próxima seção.

Configuração de proxy no Git

O Composer frequentemente busca pacotes diretamente de repositórios Git (por exemplo, GitHub, GitLab). Se o seu tráfego Git precisa passar por um proxy, você deve configurar o próprio Git.

# Set HTTP proxy for Git
git config --global http.proxy http://user:[email protected]:8080

# Set HTTPS proxy for Git
git config --global https.proxy http://user:[email protected]:8080

# To unset
git config --global --unset http.proxy
git config --global --unset https.proxy

# Verify
git config --global --get http.proxy
git config --global --get https.proxy

Isso é especialmente importante se o seu composer.json usa repositórios vcs ou URLs Git diretas.

Problemas com certificados SSL

O Composer, como outras ferramentas, pode enfrentar problemas de SSL.
1. Adicione o certificado CA do proxy ao repositório de confiança do sistema.
2. Configure o Git para desativar a verificação SSL (não recomendado):
bash git config --global http.sslVerify false
Isso deve ser o último recurso e usado com extrema cautela.

Solução de problemas comuns de proxy

• Endereço/porta de proxy incorretos: confira o hostname, o endereço IP e a porta. Um erro comum é usar HTTP para um proxy HTTPS ou o contrário.
• Falha de autenticação: verifique se o usuário e a senha na URL do proxy estão corretos e codificados em URL caso contenham caracteres especiais.
• Erros de certificado SSL: se você encontrar SSL_ERROR_SYSCALL, certificate verify failed ou erros semelhantes, o seu proxy pode estar fazendo interceptação SSL. Instale o certificado CA raiz do proxy no repositório de confiança do sistema ou configure o gerenciador de pacotes para confiar em um bundle CA específico (como detalhado acima).
• Problemas com NO_PROXY: se serviços internos ainda tentam passar pelo proxy, verifique se a sua configuração de NO_PROXY está correta e completa. Garanta que ela inclua localhost, 127.0.0.1 e quaisquer sufixos de domínio interno relevantes.
• Bloqueio de firewall: confirme que o firewall da sua máquina ou os grupos de segurança de rede permitem conexões de saída para o IP e a porta do servidor proxy.
• Configuração mista de HTTP/HTTPS: alguns proxies tratam HTTP e HTTPS de formas diferentes. Certifique-se de ter configurado tanto HTTP_PROXY quanto HTTPS_PROXY, quando aplicável, ou seus equivalentes específicos no gerenciador de pacotes.

Comparação dos métodos de configuração de proxy