Proxies para VS Code: Configuração de Sincronização de Extensões e Settings Sync via Proxy Corporativo ou Residencial

```html

O Visual Studio Code pode sincronizar extensões, configurações e snippets entre dispositivos — mas tudo isso funciona através dos servidores da Microsoft, que muitas vezes ficam indisponíveis atrás de um firewall corporativo, em redes de escritório com filtragem rigorosa ou em regiões com acesso restrito. O resultado — o Marketplace de Extensões trava, o Settings Sync não se conecta, as atualizações não são baixadas. Neste artigo, vamos explorar como configurar corretamente um proxy no VS Code para que todos esses problemas desapareçam de uma vez por todas.

Por que o VS Code não funciona sem proxy em algumas redes

O Visual Studio Code não é apenas um editor de texto. Sob o capô, ele constantemente se conecta a servidores externos: baixa atualizações de extensões de marketplace.visualstudio.com, sincroniza configurações através de vscode.dev e servidores da Conta Microsoft/GitHub, verifica atualizações do próprio editor, envia telemetria (se não estiver desativada).

Todas essas solicitações são feitas através de conexões HTTPS padrão. E é aqui que os problemas começam:

• Redes corporativas — os administradores de sistema bloqueiam o acesso direto à internet, exigindo que todo o tráfego passe pelo servidor proxy corporativo. O VS Code "não sabe" disso e simplesmente não consegue se conectar.
• Firewalls de escritório com lista branca — apenas domínios específicos são permitidos, e marketplace.visualstudio.com não está nessa lista.
• Restrições regionais — em vários países e regiões, o acesso aos serviços da Microsoft é restrito ou instável. Um proxy com IP do país necessário resolve o problema.
• Conflitos de VPN — algumas VPNs corporativas interceptam o tráfego, mas não o transmitem corretamente, fazendo com que o VS Code perca a conexão com o Marketplace.
• Internet instável + proxy com cache — o servidor proxy pode armazenar em cache pacotes de extensões e acelerar a instalação em equipes com conexão lenta.

Os sintomas de todos esses problemas são semelhantes: as extensões não são instaladas ou ficam travadas no carregamento, o Settings Sync apresenta erro de autenticação ou "não foi possível conectar", as atualizações do VS Code não são baixadas, e no painel de Output aparecem erros ECONNREFUSED ou ETIMEDOUT.

Como o VS Code lida com proxies: o que é importante saber

O VS Code é construído sobre o Electron, que usa o motor Chromium para solicitações de rede. Isso significa que as configurações de proxy funcionam de maneira semelhante às do navegador — o editor suporta proxies HTTP, HTTPS e SOCKS5.

É importante entender a hierarquia pela qual o VS Code procura as configurações de proxy:

1. Configurações de proxy do sistema — se um proxy de sistema estiver configurado no Windows/macOS/Linux, o VS Code o capturará automaticamente (parâmetro http.systemProxy).
2. Variáveis de ambiente — HTTP_PROXY, HTTPS_PROXY, NO_PROXY — método padrão para Linux/macOS.
3. Configurações no settings.json — especificação explícita do proxy através dos parâmetros http.proxy e opções relacionadas.
4. Argumentos de linha de comando — é possível iniciar o VS Code com flags de proxy diretamente.

Prioridade: configurações explícitas em settings.json substituem variáveis de ambiente, que por sua vez substituem configurações do sistema. Se algo não funcionar — verifique nessa ordem.

Configuração de proxy através do settings.json: passo a passo

Este é o método mais confiável e recomendado. As configurações em settings.json se aplicam globalmente a todas as solicitações de rede do VS Code.

Passo 1: Abra o settings.json

Pressione Ctrl+Shift+P (ou Cmd+Shift+P no Mac), digite “Open User Settings (JSON)” e selecione essa opção. O arquivo de configurações do usuário será aberto.

Passo 2: Adicione os parâmetros de proxy

Cole as linhas necessárias dentro do objeto JSON. Exemplos para diferentes tipos de proxy:

Proxy HTTP/HTTPS (sem autenticação):

{
  "http.proxy": "http://192.168.1.100:3128",
  "http.proxyStrictSSL": false
}

Proxy HTTP/HTTPS com login e senha:

{
  "http.proxy": "http://username:password@proxy-host:3128",
  "http.proxyStrictSSL": false
}

Proxy SOCKS5:

{
  "http.proxy": "socks5://username:password@proxy-host:1080",
  "http.proxyStrictSSL": false
}

Passo 3: Entenda os parâmetros

Parâmetro	Valor	Quando usar
http.proxy	URL do proxy	Parâmetro principal, obrigatório
http.proxyStrictSSL	true / false	false — se o proxy usar um certificado autoassinado
http.proxyAuthorization	String Base64	Método alternativo para passar login/senha
http.noProxy	Lista de domínios	Domínios que devem contornar o proxy (localhost, hosts internos)
http.systemProxy	on / off / override	Gerenciar proxy do sistema (novo parâmetro no VS Code 1.87+)

Passo 4: Reinicie o VS Code

Após salvar o settings.json, feche completamente e abra novamente o VS Code. Reinicializações parciais (Reload Window) às vezes não aplicam as novas configurações de rede.

Proxy através de variáveis de ambiente (HTTP_PROXY / HTTPS_PROXY)

Este método é especialmente conveniente no Linux e macOS, bem como em equipes onde o proxy é configurado no nível do sistema e deve ser aplicado a todas as ferramentas de desenvolvimento — não apenas ao VS Code, mas também ao npm, pip, git, etc.

Linux / macOS — configuração permanente

Adicione ao ~/.bashrc, ~/.zshrc ou ~/.profile:

export HTTP_PROXY="http://username:password@proxy-host:3128"
export HTTPS_PROXY="http://username:password@proxy-host:3128"
export NO_PROXY="localhost,127.0.0.1,*.local,*.internal"

Depois disso, execute source ~/.bashrc (ou reinicie a sessão) e inicie o VS Code a partir do terminal com o comando code . — as variáveis serão herdadas.

Windows — através de variáveis do sistema

Abra "Configurações do Sistema" → "Configurações Avançadas do Sistema" → "Variáveis de Ambiente". Adicione as variáveis HTTP_PROXY e HTTPS_PROXY na seção "Variáveis do Usuário" (ou "Variáveis do Sistema" para aplicar a todos os usuários). Após salvar, reinicie o VS Code.

Executando o VS Code com proxy diretamente da linha de comando

Se você precisa verificar rapidamente sem configuração permanente:

# Linux/macOS
HTTP_PROXY=http://proxy-host:3128 HTTPS_PROXY=http://proxy-host:3128 code .

# Windows PowerShell
$env:HTTP_PROXY="http://proxy-host:3128"; $env:HTTPS_PROXY="http://proxy-host:3128"; code .

Settings Sync através de proxy: diagnóstico e resolução de problemas

O Settings Sync é uma função integrada do VS Code que sincroniza configurações, extensões, snippets, atalhos de teclado e perfis entre dispositivos através de uma conta Microsoft ou GitHub. Ele funciona através de solicitações HTTPS para os servidores da Microsoft e GitHub, e é aqui que o proxy é criticamente importante.

Erros típicos do Settings Sync através de proxy

Erro	Causa	Solução
“Cannot connect to the server”	Proxy não configurado ou bloqueado	Configurar http.proxy no settings.json
“Authentication failed”	Proxy intercepta o token OAuth	Desativar a inspeção SSL para *.microsoft.com
“Sync is turned on but not syncing”	Proxy corporativo bloqueia WebSocket	Usar proxy com suporte a WebSocket
Sincronização trava em “Syncing...”	Timeout de conexão através de proxy lento	Mudar para um proxy mais rápido

Diagnóstico através do Output

Abra View → Output e no menu suspenso selecione “Settings Sync”. Aqui você verá todas as tentativas de conexão e códigos de erro. Procure por linhas com ECONNREFUSED, 407 Proxy Authentication Required ou CERT_UNTRUSTED — cada um desses códigos indica um problema específico com o proxy.

Se você ver o erro 407 — o proxy requer autenticação, adicione login e senha na URL do proxy. Se CERT_UNTRUSTED — defina "http.proxyStrictSSL": false ou adicione o certificado raiz da CA corporativa.

Domínios que devem estar acessíveis para o Settings Sync

Certifique-se de que os seguintes hosts estão acessíveis através do seu proxy:

• login.microsoftonline.com — autenticação através da Conta Microsoft
• github.com — autenticação através do GitHub
• api.github.com — API do GitHub para sincronização através do Gist
• vscode.dev — serviço de sincronização do VS Code
• *.vscode-cdn.net — CDN para recursos do VS Code

Marketplace de Extensões: por que as extensões não são instaladas e como corrigir

O Marketplace do VS Code funciona através do domínio marketplace.visualstudio.com e servidores CDN da Microsoft. Se o proxy estiver configurado corretamente, a instalação de extensões funciona de forma transparente. Mas há alguns problemas específicos.

A extensão é instalada, mas não funciona

Muitas extensões fazem suas próprias solicitações de rede ao serem iniciadas — por exemplo, baixam servidores de linguagem (LSP), dependências binárias ou atualizações de bancos de dados. Essas solicitações vão através do Node.js dentro da extensão, e elas obedecem às configurações de proxy do VS Code, mas apenas se a extensão for escrita levando em conta as variáveis HTTP_PROXY.

Se a extensão ainda não funcionar atrás do proxy — verifique a documentação dela. Muitas extensões populares têm suas próprias configurações de proxy. Por exemplo:

• Python (Pylance/Pylint) — usa variáveis de ambiente do sistema
• ESLint, Prettier — funcionam localmente, não precisam de proxy
• GitHub Copilot — requer acesso a api.github.com, captura o proxy do settings.json
• Remote - SSH — proxy é necessário para o túnel SSH, configurado separadamente no arquivo de configuração SSH
• Docker — usa o proxy do daemon Docker do sistema

Instalação manual de extensões (offline)

Se o proxy estiver indisponível ou instável, as extensões podem ser instaladas manualmente através do arquivo .vsix. Baixe o arquivo da extensão de marketplace.visualstudio.com em uma máquina com acesso à internet, depois no VS Code: Extensions → ··· → Install from VSIX.

Qual tipo de proxy escolher para o VS Code

A escolha do tipo de proxy depende da tarefa. Vamos considerar as principais opções em relação ao desenvolvimento.

Tipo de proxy	Velocidade	Confiabilidade	Quando é adequado para o VS Code
Proxy de data center	⚡ Alta	✅ Estáveis	Contornar restrições corporativas, baixar extensões, pipelines de CI/CD
Proxies residenciais	🔄 Média	✅ Alta confiança	Acesso a recursos geobloqueados, testes de uma região específica
Proxies móveis	🔄 Média	✅ Máxima confiança	Raramente necessários para o VS Code, mas úteis no desenvolvimento de aplicativos móveis com testes geográficos
Proxy corporativo (Squid, ISA)	⚡ Alta	⚠️ Depende das configurações	Ambiente de escritório, obrigatório por política da empresa

Para a maioria dos desenvolvedores que precisam apenas contornar restrições corporativas ou trabalhar de um país com acesso instável aos servidores da Microsoft, a escolha ideal será proxies de data center — eles são rápidos, estáveis e adequados para tarefas técnicas como baixar pacotes e sincronizar configurações.

Se a tarefa for testar um aplicativo de uma região geográfica específica (por exemplo, verificar como seu serviço funciona para usuários na Alemanha ou EUA), então proxies residenciais com IPs reais de usuários domésticos do país necessário serão úteis.

Proxy corporativo com inspeção SSL: um caso especial

Proxies corporativos com a função de inspeção SSL (man-in-the-middle) são uma dor de cabeça separada para os desenvolvedores. Esse proxy descriptografa o tráfego HTTPS, verifica e recriptografa, assinando com seu certificado corporativo. Como resultado, o VS Code vê um certificado "desconhecido" e se recusa a funcionar.

Sintomas

• Erro CERT_UNTRUSTED ou unable to verify the first certificate no Output
• Extensões não são instaladas, embora o proxy esteja configurado corretamente
• Settings Sync não se autentica
• npm e pip também reclamam sobre certificados

Solução 1: Desativar a verificação SSL (rápido, mas menos seguro)

{
  "http.proxyStrictSSL": false
}

Esta é uma solução rápida que desativa a verificação do certificado SSL do proxy. Adequada para redes corporativas internas onde o proxy é confiável.

Solução 2: Adicionar o certificado CA corporativo (caminho correto)

Obtenha do administrador de sistema o certificado raiz corporativo (arquivo .pem ou .crt) e adicione-o às configurações:

{
  "http.proxy": "http://corporate-proxy:3128",
  "http.proxyStrictSSL": true,
  "http.proxyCertificates": true
}

Também adicione o certificado ao armazenamento de certificados do sistema — o VS Code usa certificados do sistema a partir da versão 1.40. No Windows, basta instalar o certificado nos "Centros de Certificação Raiz Confiáveis" através do certmgr.msc. No Linux, adicione o certificado em /usr/local/share/ca-certificates/ e execute update-ca-certificates.

Solução 3: Variável NODE_EXTRA_CA_CERTS

O VS Code e suas extensões funcionam no Node.js, portanto, você pode especificar certificados CA adicionais através de uma variável de ambiente:

# Linux/macOS
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem"

# Windows PowerShell
$env:NODE_EXTRA_CA_CERTS="C:\certs\corporate-ca.pem"

Checklist: VS Code + proxy funciona corretamente

Use este checklist para garantir que tudo está configurado corretamente ou para rapidamente encontrar a causa do problema.

Conclusão

Configurar um proxy no VS Code é uma tarefa que, uma vez resolvida, elimina problemas com o Marketplace travado, Settings Sync não funcional e extensões que não conseguem baixar dependências. Principais conclusões deste artigo:

• A maneira mais confiável é definir http.proxy no settings.json: funciona tanto para o editor quanto para a maioria das extensões.
• Variáveis de ambiente (HTTP_PROXY, HTTPS_PROXY) — convenientes para unificar as configurações de proxy para todo o ambiente de desenvolvimento.
• Proxy corporativo com inspeção SSL requer ou a desativação de proxyStrictSSL, ou a instalação do certificado CA corporativo.
• Settings Sync funciona através do proxy sem configurações adicionais — o principal é que os domínios da Microsoft e GitHub estejam acessíveis.
• Diagnóstico sempre começa com Output → Settings Sync e Output → Extensions — lá você verá todos os erros de rede com códigos.

Se você trabalha em um ambiente com acesso restrito à internet ou precisa testar um aplicativo de uma região geográfica específica, recomendamos usar proxies de data center para um trabalho estável e rápido com ferramentas de desenvolvimento — eles oferecem alta velocidade de conexão e são ótimos para tarefas técnicas como baixar pacotes, sincronizar configurações e trabalhar com repositórios remotos.