WS SFTP Sync

通过 SSH/SFTP 在本地工作区与远程服务器之间同步文件的 VS Code 扩展。

商店 ID： zhangnuli.ws-sftp-sync
版本 0.3.0

上架商店步骤见 PUBLISH.md。也可只打包 .vsix 本地安装。

功能

能力	说明
上传 / 下载	单文件、文件夹、整个工作区
保存自动上传	`uploadOnSave: true` 时，保存后自动上传
差异列表	扫描仅本地 / 仅远程 / 有差异 / 相同，勾选后批量上传或下载
mtime/size 比较	`compareBeforeSync`（默认 true），相同则跳过传输
连接复用	空闲 `idleTimeout` 毫秒后自动断开
远程资源管理器	活动栏浏览远程目录，下载 / 打开
JSON Schema	编辑 `.vscode/sftp.json` 时自动补全与校验
认证	私钥或密码
ignore	minimatch 规则

快速开始

1. 安装依赖并编译

npm install
npm run compile

2. 调试运行

打开本项目，按 F5 启动扩展开发宿主，在新窗口打开业务项目。

3. 生成配置

命令面板 → SFTP: 生成配置示例，编辑 .vscode/sftp.json：

{
  "name": "default",
  "host": "192.168.1.100",
  "port": 22,
  "username": "root",
  "password": "",
  "privateKeyPath": "~/.ssh/id_rsa",
  "passphrase": "",
  "remotePath": "/var/www/project",
  "uploadOnSave": false,
  "compareBeforeSync": true,
  "idleTimeout": 30000,
  "ignore": [
    ".git/**",
    "node_modules/**",
    ".vscode/**",
    "**/*.log"
  ],
  "concurrency": 4
}

安全：密码/口令为明文，建议优先私钥，并将 sftp.json 加入 .gitignore。

4. 常用命令

命令	说明
SFTP: 测试连接	验证 SSH 与 remotePath
SFTP: 上传/下载当前文件	单文件
SFTP: 上传/下载文件夹	递归
SFTP: 上传/下载工作区	整包
SFTP: 差异列表	对比并勾选同步
SFTP: 断开连接	立即关闭连接池
SFTP: 刷新远程资源管理器	刷新侧边栏

活动栏打开 SFTP Sync → 远程资源管理器 可浏览远程文件。

路径映射

本地:  {工作区}/src/app.ts
远程:  {remotePath}/src/app.ts

配置字段

字段	默认	说明
`uploadOnSave`	`false`	保存后自动上传
`compareBeforeSync`	`true`	size/mtime 相同则跳过
`idleTimeout`	`30000`	空闲断开毫秒数，`0` 表示用完即断
`concurrency`	`4`	批量上传并发
`ignore`	见模板	忽略规则

认证优先级：配置了可读 privateKeyPath → 私钥；否则 password。

打包与 CI

本地打包 VSIX

npm install
npm run compile
npm run package

生成 sftp-sync-0.2.0.vsix，在 VS Code 中「从 VSIX 安装」。

package 使用 vsce package --no-dependencies，依赖会按打包规则处理。若需完整打包可试 npm run package:full。

GitHub Actions

仓库已包含 .github/workflows/ci.yml：

push / PR：编译 + 打包 VSIX，上传 Artifact
tag v*：创建 GitHub Release 并附带 .vsix

打标签发布示例：

git tag v0.2.0
git push origin v0.2.0

常见问题

问题	处理
认证失败	检查用户名、私钥路径/口令、密码及服务器策略
连接超时	检查 host/port、防火墙、VPN
自动上传未触发	确认 `uploadOnSave: true` 且文件不在 ignore 内
差异列表全是「相同」	正常；可取消勾选「相同」项后操作
远程树为空	先测试连接；确认 `remotePath` 存在且有权限

技术栈

TypeScript / VS Code Extension API
ssh2
minimatch
JSON Schema 校验

版本记录

0.2.0

保存自动上传
差异列表（QuickPick 多选 + 批量上传/下载）
size/mtime 比较跳过
连接复用 + 空闲断开
远程资源管理器
sftp.json JSON Schema
vsce 打包脚本与 GitHub Actions CI

0.1.0

手动上传/下载、私钥/密码、基础配置