Valuor SFTP — sincronização SFTP/FTP para o VS Code

Mantido pela Valuor.
Fork do vscode-sftp do @Natizyskunk, que por sua vez é um fork do plugin SFTP original do liximomo (não mais mantido). Todo o crédito aos autores originais.

• Marketplace do VS Code: https://marketplace.visualstudio.com/items?itemName=Valuor.valuor-sftp
  
• Código-fonte e releases: https://github.com/wandersonmaracaipe/vscode-sftp

✳ Contribuições são bem-vindas — abra uma issue ou um pull request no repositório.

Sobre este fork

Esta é uma versão modernizada da extensão SFTP: o toolchain foi atualizado (TypeScript 5, ESLint, @types atualizados), as dependências foram atualizadas e todas as vulnerabilidades conhecidas do npm audit foram resolvidas, além de alguns bugs de build/execução corrigidos. O conjunto de recursos e a configuração permanecem compatíveis com a extensão de origem.

Novidades da 1.23.0:

• Remote Explorer: busca de arquivos remotos, favoritos, arrastar-e-soltar para enviar, e "Comparar Pasta com o Remoto".
• Preview de Sincronização (Remoto → Local) — o dry-run agora nos dois sentidos.
• Exclusões por perfil (ignore do perfil é somado ao da raiz).

Novidades da 1.22.2:

• Conexão morta no SFTP — mesma correção da 1.22.1, agora para SFTP: uma conexão encerrada continuava parecendo válida.
• sync com delete: true — o sync terminava com as exclusões ainda em andamento, e uma exclusão que falhava parecia bem-sucedida. Agora são aguardadas.
• Testes do algoritmo de sync — o código que apaga arquivos remotos passou a ter cobertura (foi ela que encontrou o bug acima).

Novidades da 1.22.1:

• Correção crítica — "para de fazer upload": bastava um erro para a extensão parar de enviar até recarregar a janela. Quando o cliente FTP caía, o pool continuava entregando a conexão morta indefinidamente, e tudo falhava com "Client is closed". Agora uma conexão morta é detectada e substituída automaticamente.
• Arquivos temporários de editor (*.tmp.*, *.vsctmp, *.swp, *~) passam a ser ignorados por padrão — eram o gatilho do problema acima.

Novidades da 1.22.0:

• ⚠️ Verificação da chave do servidor (known_hosts) — correção de segurança importante: a extensão aceitava a chave de qualquer servidor SSH sem verificar, deixando toda conexão SFTP exposta a um ataque man-in-the-middle. Agora a chave é verificada; um host desconhecido mostra a impressão digital e pede confirmação, e uma chave alterada é sempre recusada. Configurável por hostKeyChecking ("prompt" | "strict" | "off").
• Migração de senhas em texto plano do sftp.json para o cofre do sistema.
• Passphrase da chave privada no cofre — não é mais pedida a cada conexão.
• ssh-agent automático via SSH_AUTH_SOCK quando nenhuma credencial é configurada.
• Retry automático por arquivo em falhas transitórias — uma queda de conexão não perde mais os arquivos da fila.
• Limite de concorrência no envio automático — um git checkout grande não satura mais a conexão.
• Painel "Histórico de Transferências" com "Repetir" nas que falharam.

Novidades da 1.21.1:

• Correção crítica no watcher — o envio automático não consultava as regras de ignore antes de enfileirar arquivos: pastas como node_modules eram enviadas e um arquivo temporário que sumia no meio da transferência (por exemplo, durante um npm install) derrubava a conexão FTP, gerando uma cascata de erros "Client is closed". Agora o ignore é respeitado tanto no envio quanto na exclusão.
• Padrão de ignore mais seguro — quando você não define ignore no sftp.json, o padrão passa a ser [".vscode", ".git", ".DS_Store", "node_modules"] (antes era vazio), evitando sincronizar pastas pesadas ou transitórias por acidente. Definir a sua própria lista continua substituindo o padrão.
• Resiliência a arquivos transitórios — arquivos que deixam de existir entre o evento do sistema de arquivos e o envio são ignorados, em vez de falharem no meio da transferência e encerrarem a conexão.

Novidades da 1.21.0:

• Preview de Sincronização (dry-run) — veja o que será enviado/excluído antes de aplicar.
• Aviso de conflito (warnRemoteNewer) ao enviar por cima de um arquivo remoto mais recente.
• Progresso por bytes com porcentagem, velocidade e tempo restante estimado.
• Renomear / Mover itens remotos pelo Remote Explorer.
• Indicador de transferências em andamento na barra de status (clique para cancelar).

Novidades da 1.20.0:

• Biblioteca FTP abandonada (ftp) substituída pela moderna basic-ftp.
• Correção do travamento "isDate is not a function" em versões recentes do VS Code (atualização do ssh2).
• Correções de bugs do projeto de origem: "Config Not Found" ao salvar/enviar (#428), sobrescrita silenciosa ao criar arquivo (#228) e symlinks para diretórios agora navegáveis (#177).
• Confirmação modal antes de excluir itens remotos.
• Comando "SFTP: Toggle Upload On Save" para pausar/retomar o envio automático ao salvar.
• Indicador de conexão na barra de status.
• Barra de progresso cancelável em transferências com vários arquivos.

O Valuor SFTP permite adicionar, editar ou excluir arquivos em um diretório local e sincronizá-los com um diretório de servidor remoto usando diferentes protocolos de transferência, como FTP ou SSH. A configuração mais básica exige apenas algumas linhas, e há uma ampla gama de opções específicas para atender às necessidades de qualquer usuário. Poderoso e rápido, ele ajuda desenvolvedores a economizar tempo permitindo o uso de um editor e ambiente familiares.

• Recursos
  • Navegar no remoto com o Remote Explorer
  • Buscar arquivos no remoto, favoritos e arrastar-e-soltar para enviar
  • Diff entre local e remoto (arquivo e pasta)
  • Sincronizar diretórios (com preview dry-run nos dois sentidos)
  • Enviar/Baixar (Upload/Download)
  • Enviar ao salvar (upload on save)
  • File Watcher
  • Múltiplas configurações
  • Perfis alternáveis (com exclusões por perfil)
  • Suporte a arquivo temporário
  • Verificação de host key (known_hosts) e senhas/passphrases no cofre
  • Confirmação modal antes de excluir no remoto
  • Barra de progresso cancelável em transferências
  • Histórico de transferências com "Repetir"
  • Indicador de conexão na barra de status
• Comandos
• Depuração
• FAQ

Instalação

Método 1 (Recomendado: atualização automática)

1. Abra as Extensões (Ctrl + Shift + X).
2. Desinstale qualquer outra extensão sftp que você tenha instalado.
3. Instale esta extensão diretamente pelo Marketplace do VS Code: https://marketplace.visualstudio.com/items?itemName=Valuor.valuor-sftp.
4. Pronto!

Método 2 (Instalação manual via VSIX)

Para instalar, siga estes passos dentro do VS Code:

1. Abra as Extensões (Ctrl + Shift + X).
2. Desinstale qualquer outra extensão sftp que você tenha instalado.
3. Abra o menu "Mais Ações" (as reticências no topo) e clique em "Instalar do VSIX…".
4. Localize o arquivo .vsix e selecione.
5. Recarregue o VS Code.
6. Pronto!

Documentação

• Início
• Configurações (Settings)
• Configuração comum
• Configuração SFTP
• Configuração FTP
• Comandos

Uso

Se os arquivos mais recentes já estão no servidor remoto, você pode começar com uma pasta local vazia, baixar seu projeto e, a partir daí, sincronizar.

1. No VS Code, abra o diretório local que deseja sincronizar com o servidor remoto (ou crie um diretório vazio no qual deseja primeiro baixar o conteúdo de uma pasta remota para editar localmente).
2. Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no Mac para abrir a paleta de comandos e execute o comando SFTP: Config.
3. Um arquivo de configuração básico chamado sftp.json aparecerá na pasta .vscode. Abra-o e edite os parâmetros com as informações do seu servidor remoto.

Por exemplo:

{
    "name": "Nome do Perfil",
    "host": "endereco_do_host_remoto",
    "protocol": "ftp",
    "port": 21,
    "secure": true,
    "username": "usuario",
    "remotePath": "/public_html/projeto", // <--- Este é o caminho que será baixado ao usar "Download Project"
    "password": "senha",
    "uploadOnSave": false
}

O parâmetro password no sftp.json é opcional; se omitido, a senha será solicitada na sincronização. Observação: barras invertidas e outros caracteres especiais devem ser escapados com uma barra invertida.

4. Salve e feche o arquivo sftp.json.
5. Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no Mac para abrir a paleta de comandos.
6. Digite sftp e você verá diversos outros comandos. Muitos deles também estão disponíveis nos menus de contexto do explorador de arquivos do projeto.
7. Um bom começo, se você quer sincronizar com uma pasta remota, é SFTP: Download Project. Isso baixa o diretório indicado em remotePath no sftp.json para o diretório local aberto.
8. Pronto — agora você pode editar localmente e, a cada salvamento, o arquivo remoto será sincronizado com a cópia local.
9. Aproveite!

Para explicações detalhadas, consulte a documentação.

Configurações de exemplo

Você pode ver a lista completa de opções de configuração aqui.

• Valuor SFTP
  • Sobre este fork
  • Instalação
  • Documentação
  • Uso
  • Configurações de exemplo
    • Simples
    • Perfis
    • Múltiplos contextos
    • Conexão via salto (hopping)
      • Salto único
      • Múltiplos saltos
    • Configuração nas User Settings
  • Remote Explorer
    • Seleção múltipla
    • Ordenação
  • Depuração
  • FAQ
  • Créditos

Simples

{
  "host": "host",
  "username": "usuario",
  "remotePath": "/remoto/workspace"
}

Perfis

{
  "username": "usuario",
  "password": "senha",
  "remotePath": "/remoto/workspace/a",
  "watcher": {
    "files": "dist/*.{js,css}",
    "autoUpload": false,
    "autoDelete": false
  },
  "profiles": {
    "dev": {
      "host": "dev-host",
      "remotePath": "/dev",
      "uploadOnSave": true
    },
    "prod": {
      "host": "prod-host",
      "remotePath": "/prod"
    }
  },
  "defaultProfile": "dev"
}

Observação: context e watcher só estão disponíveis no nível raiz.

Use SFTP: Set Profile para alternar de perfil.

Exclusões por perfil: um perfil pode definir seu próprio ignore — ele é somado ao ignore da raiz (não substitui). Assim dá para excluir algo apenas em prod, por exemplo, mantendo as exclusões comuns na raiz.

Múltiplos contextos

Os contextos não podem ser iguais.

[
  {
    "name": "servidor1",
    "context": "projeto/build",
    "host": "host",
    "username": "usuario",
    "password": "senha",
    "remotePath": "/remoto/projeto/build"
  },
  {
    "name": "servidor2",
    "context": "projeto/src",
    "host": "host",
    "username": "usuario",
    "password": "senha",
    "remotePath": "/remoto/projeto/src"
  }
]

Observação: name é obrigatório neste modo.

Conexão via salto (hopping)

Você pode se conectar a um servidor de destino através de um proxy usando o protocolo ssh.

Observação: a substituição de variáveis não funciona em uma configuração de salto.

Salto único

local -> salto -> destino

{
  "name": "destino",
  "remotePath": "/caminho/no/destino",

  // salto
  "host": "hostDoSalto",
  "username": "usuarioDoSalto",
  "privateKeyPath": "/Users/usuarioLocal/.ssh/id_rsa", // <-- A chave é assumida como estando na máquina local.

  "hop": {
    // destino
    "host": "hostDestino",
    "username": "usuarioDestino",
    "privateKeyPath": "/Users/usuarioSalto/.ssh/id_rsa", // <-- A chave é assumida como estando no salto.
  }
}

Múltiplos saltos

local -> saltoA -> saltoB -> destino

{
  "name": "destino",
  "remotePath": "/caminho/no/destino",

  // saltoA
  "host": "hostSaltoA",
  "username": "usuarioSaltoA",
  "privateKeyPath": "/Users/usuarioSaltoA/.ssh/id_rsa" // <-- A chave é assumida como estando na máquina local.

  "hop": [
    // saltoB
    {
      "host": "hostSaltoB",
      "username": "usuarioSaltoB",
      "privateKeyPath": "/Users/usuarioSaltoA/.ssh/id_rsa" // <-- A chave é assumida como estando no saltoA.
    },

    // destino
    {
      "host": "hostDestino",
      "username": "usuarioDestino",
      "privateKeyPath": "/Users/usuarioSaltoB/.ssh/id_rsa", // <-- A chave é assumida como estando no saltoB.
    }
  ]
}

Configuração nas User Settings

Você pode usar remote para dizer ao sftp para obter a configuração do remote-fs.

Nas User Settings:

"remotefs.remote": {
  "dev": {
    "scheme": "sftp",
    "host": "host",
    "username": "usuario",
    "rootPath": "/caminho/para/algum/lugar"
  },
  "projectX": {
    "scheme": "sftp",
    "host": "host",
    "username": "usuario",
    "privateKeyPath": "/Users/xx/.ssh/id_rsa",
    "rootPath": "/home/foo/algum/projectx"
  }
}

No sftp.json:

{
  "remote": "dev",
  "remotePath": "/home/xx/",
  "uploadOnSave": false,
  "ignore": [".vscode", ".git", ".DS_Store"]
}

Remote Explorer

O Remote Explorer permite explorar os arquivos no remoto. Você pode abri-lo de duas formas:

1. Execute o comando View: Show SFTP.
2. Clique na visão SFTP na Barra de Atividades.

Pelo Remote Explorer você só visualiza o conteúdo de um arquivo. Execute o comando SFTP: Edit in Local para editá-lo localmente.

Buscar arquivos remotos

Clique no ícone de lupa na barra do Remote Explorer (ou use "Buscar Arquivos Remotos" no menu de uma conexão) para percorrer a árvore remota e abrir um seletor filtrável — escolher um resultado abre o arquivo. A varredura é limitada (5000 entradas, 12 níveis) para não travar em remotos muito grandes; se o limite for atingido, navegue até uma subpasta e busque a partir dela.

Favoritos

Use "Adicionar aos Favoritos" no menu de qualquer arquivo ou pasta remota para guardá-lo. A estrela na barra do Remote Explorer abre um favorito: um arquivo abre no editor, uma pasta é revelada e expandida na árvore. Os favoritos são salvos por workspace.

Arrastar e soltar para enviar

Arraste arquivos ou pastas do gerenciador de arquivos do sistema (ou do próprio Explorer do VS Code) e solte sobre uma pasta remota para enviá-los ali. Soltar sobre um arquivo envia para a pasta que o contém.

Comparar pasta com o remoto

Clique com o botão direito em uma pasta local e escolha "Comparar Pasta com o Remoto" para listar as diferenças (arquivos diferentes, só locais, só remotos) sem alterar nada. Escolher um arquivo diferente abre o diff lado a lado.

Seleção múltipla

Você pode selecionar vários arquivos/pastas de uma vez no servidor remoto para baixar e enviar. Basta segurar Ctrl ou Shift enquanto seleciona os itens desejados, como no explorador de arquivos comum.

Observação: pode ser necessário atualizar manualmente a pasta pai depois de excluir um arquivo, caso o explorador não seja atualizado corretamente.

Ordenação

Você pode ordenar o Remote Explorer adicionando o parâmetro remoteExplorer.order no seu arquivo sftp.json.

No sftp.json:

{
  "remoteExplorer": {
    "order": 1 // <-- O valor padrão é 0.
  }
}

Depuração

1. Abra as User Settings.

• No Windows/Linux — File > Preferences > Settings
• No macOS — Code > Preferences > Settings

2. Defina sftp.debug como true e recarregue o VS Code.
3. Veja os logs em View > Output > sftp.

Problemas comuns

• A extensão parou de enviar e tudo falha com "Client is closed" — corrigido na 1.22.1; detalhes.
• Arquivos .tmp. / .vsctmp sendo enviados e falhando com ENOENT — são temporários do editor, ignorados por padrão desde a 1.22.1; detalhes.

⚠️ Se você define ignore no seu sftp.json, a sua lista substitui a padrão (não é mesclada). Veja o padrão atual em ignore.

FAQ

Você pode ver todas as Perguntas Frequentes aqui.

Créditos

Esta extensão se apoia no trabalho de liximomo (autor original) e Natizyskunk (mantenedor de longa data do fork em que esta se baseia). Obrigado pelo trabalho de vocês.