搞开发最怕的不是写不出代码而是写完了代码传不上服务器。我最早在Windows上写项目程序却部署在远程的Ubuntu机器上每次改动要么用命令行一点点传要么干脆打开远程编辑器重新改一遍效率低不说本地和远程还经常版本不一致。后来我彻底转向VS Code的SFTP插件去做Windows与Ubuntu的文件同步才真正把这条链路理顺了。这篇东西专门写给正在被“本地改代码、远程跑程序”困扰的开发者不管你是做前后端、跑算法实验还是维护小项目只要你想让本地和Ubuntu之间的文件保持一致这套配置思路基本都能直接落地。我会从“为什么选这个方案”讲起然后把服务器端的准备、Windows端的密钥配置、SFTP插件的核心配置项全部拆开说清楚最后再把我这几年实际踩过的坑整理成排查清单。整个过程不需要额外付费工具只需要VS Code和一台能SSH登录的Ubuntu机器就行。1. 为什么选SFTP插件做Windows与Ubuntu文件同步1.1 这个插件解决的到底是什么痛点先说场景。很多人的开发环境是“Windows办公机 Ubuntu服务器”的组合代码在Windows上写好运行环境在Ubuntu上日志、模型文件、数据集也在服务器上。这种情况下你每天要做的事情就是反复在两端搬运文件。最原始的做法是手动执行scp或者ssh到服务器里改文件但改一个文件传一次漏传是家常便饭。更麻烦的是一旦涉及前端打包产物、静态资源、配置文件这些多目录的东西手动同步几乎不可能保证一致性。VS Code SFTP插件本质上是在编辑器里集成了一个“远程文件管理窗口”它基于SFTP协议连接服务器把本地工作区看成一个待同步目录通过保存、监听、手动命令等方式把文件推到远端或者把远端文件拉回本地。这正好解决了几个核心痛点第一不用离开编辑器第二可以按文件、按目录精确操作第三能自动触发上传减少人为遗漏。1.2 和Git、网盘、rsync比为什么SFTP插件更适合很多人会问明明有Git为什么还要单独做文件同步这里有个场景差异。Git解决的是源码版本管理但它要求你先提交、再推送而且构建产物、依赖目录、数据集这些东西通常不在版本管理里。如果你只是想快速把当前目录下的东西和服务器同步用Git就太重了。网盘方案的问题在于双向同步逻辑不透明。你改了本地文件网盘上传后再从服务器端下载中间会产生临时副本、冲突文件而且英文文件名、软链接、特殊权限这些“开发环境特产”很容易在网盘同步中丢失。最关键的网盘同步不基于SSH说明你还要在服务器上安装额外客户端安全性也相对弱一些。传统rsync确实强大增量同步、权限保留都能做但问题在于它需要Windows端额外搭建环境而且没有可视化界面。对于大多数开发场景来说我需要的是一个“改完文件自动传到服务器”的轻量通道而不是一套完整的运维工具链。VS Code SFTP插件正好卡在两者之间既保留了SSH的安全通道又不需要离开编辑器配置妥当之后基本做到无感同步。2. 环境准备与插件安装2.1 Ubuntu侧先把SSH服务准备好SFTP可不是什么独立服务它是在SSH协议之上工作的文件传输协议所以Ubuntu端首先要保证SSH服务是正常的。我习惯拿到新机器先执行这三步检查sudo apt update sudo apt install openssh-server sudo systemctl status ssh如果状态显示active (running)说明服务正常。没启动就执行sudo systemctl enable --now ssh这里顺手解释一下为什么要enable和start一起做。enable是设置开机自启start是立即启动。只start不enable机器重启后服务会消失你会以为是配置坏了其实是没设自启。接着确认机器的IP地址hostname -I我通常记下内网地址比如192.168.x.x后面配置host字段要用。如果服务器是云厂商提供的公网机器那直接用它的公网地址或者绑定域名即可。还有一个很容易忽略的地方是防火墙。Ubuntu默认的ufw如果开着22端口可能被挡在外面。检查一下sudo ufw status如果是active而22端口没有放行就执行sudo ufw allow 22/tcp另外务必要确认你要登录的用户对目标目录有写权限。很多人用root登录确实能省事但我不推荐直接拿root跑日常同步风险太高。我的习惯是单独建一个部署用户把项目目录归属给它比如sudo adduser dev sudo mkdir -p /home/dev/projects/myapp sudo chown -R dev:dev /home/dev/projects这里有个常见误解SFTP插件的remotePath必须是一个已存在的目录插件不会自动帮你创建多级目录。所以务必先在服务器上把工作目录建好。2.2 Windows侧安装插件并生成SSH密钥Windows端要做的第一件事是在VS Code扩展市场里搜索SFTP认准那个下载量最高、维护比较活跃的插件安装即可。装完记得重载窗口有时候不重载插件不会激活。接下来是生成SSH密钥。Windows 10及以上系统自带OpenSSH客户端不需要额外安装。在PowerShell里执行ssh-keygen -t ed25519 -C 用于开发机文件同步我推荐ed25519原因很直接密钥短、生成快、安全性不低于RSA而且现代OpenSSH都支持。生成过程会问你保存路径和口令口令可以留空但如果你很在意密钥泄露风险设置一个口令更稳妥。公私钥生成后要把公钥内容写入Ubuntu的~/.ssh/authorized_keys文件。Windows没有现成的ssh-copy-id命令但可以用一行命令实现type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh dev192.168.x.x mkdir -p ~/.ssh cat ~/.ssh/authorized_keys执行后输入一次用户密码之后SSH登录就不再需要密码了。这里记住一个关键点SSH公钥登录对文件权限非常敏感。服务器端的~/.ssh目录权限应该是700authorized_keys文件权限应该是600。权限放太宽SSH服务端会为了安全拒绝使用该公钥而你看到的现象就是“明明公钥添加了还是要求密码登录”。修复方式chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys全部搞完后先手动验证一下ssh dev192.168.x.x如果直接登进去没让你输密码说明SSH密钥链路已经通了后面配置SFTP插件会顺畅很多。3. 核心配置sftp.json逐字段拆解3.1 一条命令生成配置文件在VS Code里用CtrlShiftP打开命令面板输入SFTP: Config插件会在当前工作区的.vscode目录下生成一个sftp.json模板。这里有个很重要的细节这个配置是工作区级的也就是说每个项目会有自己独立的配置文件互不影响。你打开的这个文件夹应该就是你想同步到服务器的那套代码的根目录。比如我的项目结构是myapp含src、public、package.json等那就在VS Code里直接打开myapp然后执行SFTP: Config生成的配置就落在这个项目的.vscode目录下了。3.2 我的实用模板与关键字段注释下面是我一直在用的配置文件版本删掉了一大堆用不到的默认字段只留下实际能派上用场的{ name: ubuntu-dev, host: 192.168.x.x, protocol: sftp, port: 22, username: dev, privateKeyPath: C:/Users/你的用户名/.ssh/id_ed25519, remotePath: /home/dev/projects/myapp, uploadOnSave: true, ignore: [ **/.vscode/**, **/.git/**, **/node_modules/**, **/dist/**, **/__pycache__/**, **/*.log ], watcher: { files: **/*, autoUpload: false, autoDelete: false }, syncOption: { delete: false, update: true }, concurrency: 4, keepalive: 120 }逐个字段说说我的理解。name连接别名主要用来在多个配置间做区分。host就是Ubuntu的IP或域名。内网开发机填内网IP云服务器填公网IP。protocol一定要写成sftp别用ftpftp是明文传输密码和文件内容都是裸奔的。port默认22除非你改了sshd_config里的Port。username登录用户对应服务器上那个有目录权限的账号。privateKeyPathWindows本机私钥的绝对路径。路径分隔符建议用正斜杠/反斜杠容易出转义问题。如果你想用密码登录也可以写password字段但我不建议一旦配置提交到Git仓库等于把密码也提交了。remotePath远端项目绝对路径提前在服务器创建好。uploadOnSave保存后自动上传。这是最核心的自动化开关后面我会详细说。ignore排除目录。这个太好用了凡是本地和远程不需要同步的东西都写进去。watcher监听远端变化控制是否把远端改动自动下载回本地。syncOption.delete本地删除文件时同步删除远端文件。这是一个有破坏性的选项我建议先设为false。concurrency同时传输的文件数量4到8是合理区间太大反而容易把服务器的SSH连接压垮。keepalive保持连接的间隔秒数。如果你挂机一会儿再回来就容易断线重连设置keepalive能缓解这个问题。3.3 多环境切换与团队协作细节如果你的项目同时对接开发机和正式服务器比如同一个代码在开发环境联调在线上环境部署一份sftp.json只配置一个host就不够用了。SFTP插件支持context上下文配置我常用的写法是这样的{ context: dev, contextList: [ { context: dev, host: 192.168.x.x, remotePath: /home/dev/projects/myapp, username: dev }, { context: prod, host: 你的正式服务器地址, remotePath: /var/www/myapp, username: deploy } ] }切换方式很简单命令面板里搜索Context选择对应的环境即可。这样同一个项目开发时传开发机上线时切到正式环境不需要维护两份配置。团队协作方面还有个容易炸的点sftp.json里的私钥路径和用户名是个人相关的不同人主机名不同、密钥路径不同如果大家都往Git仓库提交这个配置文件必然互相覆盖。我的处理方式是把.vscode/sftp.json加进.gitignore让团队成员各自保留自己的本地配置。远程服务器的目录结构保持一致就好不要求配置文件一致。4. 同步操作实战与自动化工作流4.1 五条高频命令分别干什么用SFTP插件在命令面板里提供了不少操作但我真正频繁用到的只有五条我按使用频率排个序SFTP: Sync Local - Remote把本地所有文件推送到远端以本地为准。这个命令适合初始化或者你信不过远端内容时强制覆盖一次。SFTP: Sync Remote - Local把远端所有文件拉取到本地以远端为准。适合你想在全新电脑上继续工作时先把服务器上最新代码拉下来。SFTP: Upload / Download单文件级别上传和下载。如果你只改了某一个文件不想触发全量同步右键文件菜单或者命令面板里选这两个就行。SFTP: List All列出远端目录检查连接是否正常也帮你确认remotePath对不对。SFTP: Diff Local vs Remote对比本地和远端的差异列出所有不一致的文件。这个命令每次大规模同步前我都建议跑一遍心里有数再动手。我自己的操作节奏一般是首次连接先用List All确认路径通再Diff一下看看远端和本地差多少最后执行Sync Local - Remote。日常改代码只依赖保存自动上传偶尔操作个别文件用Upload/Download。4.2 保存即上传和远程监听怎么配合uploadOnSave和watcher是SFTP插件最像“同步盘”的两个功能但它们的逻辑方向不同。uploadOnSave你按CtrlS保存本地文件插件立刻把文件上传到远端对应路径。这个是本地发起、推送远端的单向操作。watcher监听远端目录变化。比如你在服务器上直接改了某个文件或者服务器上跑的服务生成了新的日志、输出文件插件检测到后可以按规则自动下载到本地这就是远端发起的拉取操作。我在配置里把watcher的autoUpload和autoDelete都设为了false并不是说这个功能没用而是因为双向自动同步在多人协作场景里非常容易造成误覆盖。如果只有你一个人在服务器上改文件那你可以尝试开启watcher的autoUpload体验确实好但如果是团队共用服务器开着双向自动同步等于把“不确定”的变更全部吞进本地很容易丢了其他成员刚更新到远端的改动。最稳妥的方案是本地保存自动上传打开远端监听不自动同步需要手动下拉时用Sync Remote - Local或者直接Diff之后按文件下载。4.3 用ignore和同步策略避开重灾区ignore字段是避免同步事故的关键防线。如果你在做前端项目node_modules动辄几千个文件本地安装和服务器安装的依赖版本还可能不一致把它同步过去纯属浪费带宽和时间。同理.git目录、构建产物dist、Python缓存__pycache__、日志文件都不需要同步。我见过一个同事把整个项目同步过去结果把服务器上的node_modules覆盖成了Windows版本的里面一堆c语言编译的二进制文件全部失效最后只能删了重装。这就是ignore没配对好的典型翻车现场。除了ignoresyncOption.delete这个选项更要谨慎。delete为true表示本地删了某个文件同步上传时远端也删掉。听起来合理但危险在于如果你的本地目录暂时缺失某些内容比如你忘了拉取远端最新文件此时执行Sync Local - Remote远端那些“最新文件”就会因为本地没有而被误删。所以我建议首次使用阶段delete保持false只做新增和覆盖不做删除。等你对整个同步逻辑都熟悉了再考虑开启delete。5. 踩坑复盘连接失败、文件错乱与性能问题5.1 连不上服务器的排查顺序SFTP插件报错信息有时候比较笼统尤其是“Failed to connect”这种说了等于没说。我总结了一套排查顺序按这个步骤走基本能找到问题。首先排查SSH服务本身。在Windows端命令行直接执行ssh dev192.168.x.x如果能登录说明SSH链路正常问题在插件配置如果这里就失败那就要往下查。如果提示Connection timed out优先检查IP地址是否写错、Ubuntu的SSH服务是否启动、防火墙是否放行22端口。我遇到最多的情况根本不是防火墙而是IP地址写成了另一台机器因为内网DHCP有时候会换IP。如果提示Permission denied检查用户名是否正确、公钥是否真的追加到了authorized_keys里、.ssh目录和文件权限是否合规。可以用ssh -v看详细输出它会告诉你认证过程哪一步出了问题。如果提示Host key verification failed通常是因为服务器系统重装过指纹变了。清理一下Windows端known_hosts里对应IP的旧记录即可known_hosts位于C:/Users/你的用户名/.ssh/known_hosts。插件配置层面的问题可以打开输出面板下拉框选SFTP能看到插件自己的日志。日志里会给出更具体的连接过程和错误位置排查效率高很多。5.2 保存后不同步、中文乱码与权限报错保存后文件没有自动上传这种现象第一次遇到会很疑惑。实际上原因无非三种一是uploadOnSave没设成true二是你要上传的文件命中了ignore规则三是项目工作区不对你打开的文件夹不是当前配置对应的项目根目录。我自己踩过的坑是ignore写得太宽比如写了**/.vscode/**结果把整个.vscode目录都排除了包括sftp.json本身也传不上去后来发现远端根本没有配置文件才反应过来。注意ignore排除的是文件内容不是sftp.json这个文件本身的加载。中文乱码是Windows开发者特别容易遇到的问题。Windows记事本保存文件时默认带BOMUTF-8带BOM的文件传到服务器上用Linux工具处理时开头会多出不可见字符导致脚本执行报错或者内容显示异常。VS Code默认使用UTF-8无BOM所以问题通常不从VS Code来而是来自你用其他编辑器改过的文件。解决思路是全链路统一UTF-8保存文件时留意VS Code右下角编码标识避免混用。还有换行符问题。Windows文件的CRLF换行传到Linux上bash脚本会报“$\r: command not found”之类的错。我在VS Code设置里固定了files.eol: \n这样新文件的换行符统一是LF。对于已有文件可以点右下角CRLF/LF标识手动切换。很多人最后发现服务器上跑脚本失败原因根本不是代码逻辑而是看不见的\r。上传报Permission denied的解决办法比较直接。去服务器上看目标目录的属主和权限ls -ld /home/dev/projects/myapp如果不属于当前登录用户用chown修改归属sudo chown -R dev:dev /home/dev/projects/myapp5.3 大目录同步的提速经验首次同步整个项目时如果远程目录内容很大网速又一般那过程确实很煎熬。几个提速技巧比较实用。第一善用ignore。把node_modules、vendor、.git这些大规模目录排除掉之后需要同步的文件数量可能直接减少七八成。第二concurrency可以适当调高我的经验是4到8比较合适太高了会在服务器端创建过多SSH会话反而变慢。如果你对服务器性能有信心也可以临时调到10跑首次同步跑完再调回来。第三不要反复全量同步。日常开发中Diff Local vs Remote比无脑Sync效率高得多因为它能告诉你哪些文件真正有差异。一次全量同步之后后续增量同步的速度非常快因为插件会走增量比较。第四处理超大二进制文件时比如数据集或者打包产物不要指望插件能像专用工具一样做断点续传。SFTP插件擅长处理源码和小文件如果是几十GB的数据同步还是考虑专门的文件传输方案更合适。6. 几点个人体会与后续扩展最后分享一个我最初犯过的错有一回我拿一个正在运行的服务目录直接做首次Sync当时没想清楚同步策略把delete开成了true结果远端有几个我本地没有的配置文件被当成“过期文件”清掉了服务当时就异常了。那次之后我养成了一个习惯凡是拿真实环境做同步第一步先在服务器上备份目标目录至少也打个压缩包tar -czf myapp_backup.tar.gz myapp成本很低但心里有底。后来我的流程稳定下来是这样的本地写代码CtrlS自动上传每天下班前跑一次Diff Local vs Remote看一眼差异每周手动Sync Remote - Local拉一次远端生成的最新文件。这套规则保证了大多数时候两端是一致的又避免了双向自动同步带来的隐患。如果你后续的项目规模变大团队协作更频繁那确实可以考虑把部署流程迁到流水线或者容器方案文件同步会慢慢退居次要位置。但对于个人开发、小团队快速迭代、临时联调这些场景VS Code SFTP插件就是Windows和Ubuntu之间成本最低、逻辑最直观的同步方案。调整好配置养好操作习惯这个组合能让你少跑无数次命令行也确实值得花一个下午把原理和配置摸透。
搞开发最怕的不是写不出代码而是写完了代码传不上服务器。我最早在Windows上写项目程序却部署在远程的Ubuntu机器上每次改动要么用命令行一点点传要么干脆打开远程编辑器重新改一遍效率低不说本地和远程还经常版本不一致。后来我彻底转向VS Code的SFTP插件去做Windows与Ubuntu的文件同步才真正把这条链路理顺了。这篇东西专门写给正在被“本地改代码、远程跑程序”困扰的开发者不管你是做前后端、跑算法实验还是维护小项目只要你想让本地和Ubuntu之间的文件保持一致这套配置思路基本都能直接落地。我会从“为什么选这个方案”讲起然后把服务器端的准备、Windows端的密钥配置、SFTP插件的核心配置项全部拆开说清楚最后再把我这几年实际踩过的坑整理成排查清单。整个过程不需要额外付费工具只需要VS Code和一台能SSH登录的Ubuntu机器就行。1. 为什么选SFTP插件做Windows与Ubuntu文件同步1.1 这个插件解决的到底是什么痛点先说场景。很多人的开发环境是“Windows办公机 Ubuntu服务器”的组合代码在Windows上写好运行环境在Ubuntu上日志、模型文件、数据集也在服务器上。这种情况下你每天要做的事情就是反复在两端搬运文件。最原始的做法是手动执行scp或者ssh到服务器里改文件但改一个文件传一次漏传是家常便饭。更麻烦的是一旦涉及前端打包产物、静态资源、配置文件这些多目录的东西手动同步几乎不可能保证一致性。VS Code SFTP插件本质上是在编辑器里集成了一个“远程文件管理窗口”它基于SFTP协议连接服务器把本地工作区看成一个待同步目录通过保存、监听、手动命令等方式把文件推到远端或者把远端文件拉回本地。这正好解决了几个核心痛点第一不用离开编辑器第二可以按文件、按目录精确操作第三能自动触发上传减少人为遗漏。1.2 和Git、网盘、rsync比为什么SFTP插件更适合很多人会问明明有Git为什么还要单独做文件同步这里有个场景差异。Git解决的是源码版本管理但它要求你先提交、再推送而且构建产物、依赖目录、数据集这些东西通常不在版本管理里。如果你只是想快速把当前目录下的东西和服务器同步用Git就太重了。网盘方案的问题在于双向同步逻辑不透明。你改了本地文件网盘上传后再从服务器端下载中间会产生临时副本、冲突文件而且英文文件名、软链接、特殊权限这些“开发环境特产”很容易在网盘同步中丢失。最关键的网盘同步不基于SSH说明你还要在服务器上安装额外客户端安全性也相对弱一些。传统rsync确实强大增量同步、权限保留都能做但问题在于它需要Windows端额外搭建环境而且没有可视化界面。对于大多数开发场景来说我需要的是一个“改完文件自动传到服务器”的轻量通道而不是一套完整的运维工具链。VS Code SFTP插件正好卡在两者之间既保留了SSH的安全通道又不需要离开编辑器配置妥当之后基本做到无感同步。2. 环境准备与插件安装2.1 Ubuntu侧先把SSH服务准备好SFTP可不是什么独立服务它是在SSH协议之上工作的文件传输协议所以Ubuntu端首先要保证SSH服务是正常的。我习惯拿到新机器先执行这三步检查sudo apt update sudo apt install openssh-server sudo systemctl status ssh如果状态显示active (running)说明服务正常。没启动就执行sudo systemctl enable --now ssh这里顺手解释一下为什么要enable和start一起做。enable是设置开机自启start是立即启动。只start不enable机器重启后服务会消失你会以为是配置坏了其实是没设自启。接着确认机器的IP地址hostname -I我通常记下内网地址比如192.168.x.x后面配置host字段要用。如果服务器是云厂商提供的公网机器那直接用它的公网地址或者绑定域名即可。还有一个很容易忽略的地方是防火墙。Ubuntu默认的ufw如果开着22端口可能被挡在外面。检查一下sudo ufw status如果是active而22端口没有放行就执行sudo ufw allow 22/tcp另外务必要确认你要登录的用户对目标目录有写权限。很多人用root登录确实能省事但我不推荐直接拿root跑日常同步风险太高。我的习惯是单独建一个部署用户把项目目录归属给它比如sudo adduser dev sudo mkdir -p /home/dev/projects/myapp sudo chown -R dev:dev /home/dev/projects这里有个常见误解SFTP插件的remotePath必须是一个已存在的目录插件不会自动帮你创建多级目录。所以务必先在服务器上把工作目录建好。2.2 Windows侧安装插件并生成SSH密钥Windows端要做的第一件事是在VS Code扩展市场里搜索SFTP认准那个下载量最高、维护比较活跃的插件安装即可。装完记得重载窗口有时候不重载插件不会激活。接下来是生成SSH密钥。Windows 10及以上系统自带OpenSSH客户端不需要额外安装。在PowerShell里执行ssh-keygen -t ed25519 -C 用于开发机文件同步我推荐ed25519原因很直接密钥短、生成快、安全性不低于RSA而且现代OpenSSH都支持。生成过程会问你保存路径和口令口令可以留空但如果你很在意密钥泄露风险设置一个口令更稳妥。公私钥生成后要把公钥内容写入Ubuntu的~/.ssh/authorized_keys文件。Windows没有现成的ssh-copy-id命令但可以用一行命令实现type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh dev192.168.x.x mkdir -p ~/.ssh cat ~/.ssh/authorized_keys执行后输入一次用户密码之后SSH登录就不再需要密码了。这里记住一个关键点SSH公钥登录对文件权限非常敏感。服务器端的~/.ssh目录权限应该是700authorized_keys文件权限应该是600。权限放太宽SSH服务端会为了安全拒绝使用该公钥而你看到的现象就是“明明公钥添加了还是要求密码登录”。修复方式chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys全部搞完后先手动验证一下ssh dev192.168.x.x如果直接登进去没让你输密码说明SSH密钥链路已经通了后面配置SFTP插件会顺畅很多。3. 核心配置sftp.json逐字段拆解3.1 一条命令生成配置文件在VS Code里用CtrlShiftP打开命令面板输入SFTP: Config插件会在当前工作区的.vscode目录下生成一个sftp.json模板。这里有个很重要的细节这个配置是工作区级的也就是说每个项目会有自己独立的配置文件互不影响。你打开的这个文件夹应该就是你想同步到服务器的那套代码的根目录。比如我的项目结构是myapp含src、public、package.json等那就在VS Code里直接打开myapp然后执行SFTP: Config生成的配置就落在这个项目的.vscode目录下了。3.2 我的实用模板与关键字段注释下面是我一直在用的配置文件版本删掉了一大堆用不到的默认字段只留下实际能派上用场的{ name: ubuntu-dev, host: 192.168.x.x, protocol: sftp, port: 22, username: dev, privateKeyPath: C:/Users/你的用户名/.ssh/id_ed25519, remotePath: /home/dev/projects/myapp, uploadOnSave: true, ignore: [ **/.vscode/**, **/.git/**, **/node_modules/**, **/dist/**, **/__pycache__/**, **/*.log ], watcher: { files: **/*, autoUpload: false, autoDelete: false }, syncOption: { delete: false, update: true }, concurrency: 4, keepalive: 120 }逐个字段说说我的理解。name连接别名主要用来在多个配置间做区分。host就是Ubuntu的IP或域名。内网开发机填内网IP云服务器填公网IP。protocol一定要写成sftp别用ftpftp是明文传输密码和文件内容都是裸奔的。port默认22除非你改了sshd_config里的Port。username登录用户对应服务器上那个有目录权限的账号。privateKeyPathWindows本机私钥的绝对路径。路径分隔符建议用正斜杠/反斜杠容易出转义问题。如果你想用密码登录也可以写password字段但我不建议一旦配置提交到Git仓库等于把密码也提交了。remotePath远端项目绝对路径提前在服务器创建好。uploadOnSave保存后自动上传。这是最核心的自动化开关后面我会详细说。ignore排除目录。这个太好用了凡是本地和远程不需要同步的东西都写进去。watcher监听远端变化控制是否把远端改动自动下载回本地。syncOption.delete本地删除文件时同步删除远端文件。这是一个有破坏性的选项我建议先设为false。concurrency同时传输的文件数量4到8是合理区间太大反而容易把服务器的SSH连接压垮。keepalive保持连接的间隔秒数。如果你挂机一会儿再回来就容易断线重连设置keepalive能缓解这个问题。3.3 多环境切换与团队协作细节如果你的项目同时对接开发机和正式服务器比如同一个代码在开发环境联调在线上环境部署一份sftp.json只配置一个host就不够用了。SFTP插件支持context上下文配置我常用的写法是这样的{ context: dev, contextList: [ { context: dev, host: 192.168.x.x, remotePath: /home/dev/projects/myapp, username: dev }, { context: prod, host: 你的正式服务器地址, remotePath: /var/www/myapp, username: deploy } ] }切换方式很简单命令面板里搜索Context选择对应的环境即可。这样同一个项目开发时传开发机上线时切到正式环境不需要维护两份配置。团队协作方面还有个容易炸的点sftp.json里的私钥路径和用户名是个人相关的不同人主机名不同、密钥路径不同如果大家都往Git仓库提交这个配置文件必然互相覆盖。我的处理方式是把.vscode/sftp.json加进.gitignore让团队成员各自保留自己的本地配置。远程服务器的目录结构保持一致就好不要求配置文件一致。4. 同步操作实战与自动化工作流4.1 五条高频命令分别干什么用SFTP插件在命令面板里提供了不少操作但我真正频繁用到的只有五条我按使用频率排个序SFTP: Sync Local - Remote把本地所有文件推送到远端以本地为准。这个命令适合初始化或者你信不过远端内容时强制覆盖一次。SFTP: Sync Remote - Local把远端所有文件拉取到本地以远端为准。适合你想在全新电脑上继续工作时先把服务器上最新代码拉下来。SFTP: Upload / Download单文件级别上传和下载。如果你只改了某一个文件不想触发全量同步右键文件菜单或者命令面板里选这两个就行。SFTP: List All列出远端目录检查连接是否正常也帮你确认remotePath对不对。SFTP: Diff Local vs Remote对比本地和远端的差异列出所有不一致的文件。这个命令每次大规模同步前我都建议跑一遍心里有数再动手。我自己的操作节奏一般是首次连接先用List All确认路径通再Diff一下看看远端和本地差多少最后执行Sync Local - Remote。日常改代码只依赖保存自动上传偶尔操作个别文件用Upload/Download。4.2 保存即上传和远程监听怎么配合uploadOnSave和watcher是SFTP插件最像“同步盘”的两个功能但它们的逻辑方向不同。uploadOnSave你按CtrlS保存本地文件插件立刻把文件上传到远端对应路径。这个是本地发起、推送远端的单向操作。watcher监听远端目录变化。比如你在服务器上直接改了某个文件或者服务器上跑的服务生成了新的日志、输出文件插件检测到后可以按规则自动下载到本地这就是远端发起的拉取操作。我在配置里把watcher的autoUpload和autoDelete都设为了false并不是说这个功能没用而是因为双向自动同步在多人协作场景里非常容易造成误覆盖。如果只有你一个人在服务器上改文件那你可以尝试开启watcher的autoUpload体验确实好但如果是团队共用服务器开着双向自动同步等于把“不确定”的变更全部吞进本地很容易丢了其他成员刚更新到远端的改动。最稳妥的方案是本地保存自动上传打开远端监听不自动同步需要手动下拉时用Sync Remote - Local或者直接Diff之后按文件下载。4.3 用ignore和同步策略避开重灾区ignore字段是避免同步事故的关键防线。如果你在做前端项目node_modules动辄几千个文件本地安装和服务器安装的依赖版本还可能不一致把它同步过去纯属浪费带宽和时间。同理.git目录、构建产物dist、Python缓存__pycache__、日志文件都不需要同步。我见过一个同事把整个项目同步过去结果把服务器上的node_modules覆盖成了Windows版本的里面一堆c语言编译的二进制文件全部失效最后只能删了重装。这就是ignore没配对好的典型翻车现场。除了ignoresyncOption.delete这个选项更要谨慎。delete为true表示本地删了某个文件同步上传时远端也删掉。听起来合理但危险在于如果你的本地目录暂时缺失某些内容比如你忘了拉取远端最新文件此时执行Sync Local - Remote远端那些“最新文件”就会因为本地没有而被误删。所以我建议首次使用阶段delete保持false只做新增和覆盖不做删除。等你对整个同步逻辑都熟悉了再考虑开启delete。5. 踩坑复盘连接失败、文件错乱与性能问题5.1 连不上服务器的排查顺序SFTP插件报错信息有时候比较笼统尤其是“Failed to connect”这种说了等于没说。我总结了一套排查顺序按这个步骤走基本能找到问题。首先排查SSH服务本身。在Windows端命令行直接执行ssh dev192.168.x.x如果能登录说明SSH链路正常问题在插件配置如果这里就失败那就要往下查。如果提示Connection timed out优先检查IP地址是否写错、Ubuntu的SSH服务是否启动、防火墙是否放行22端口。我遇到最多的情况根本不是防火墙而是IP地址写成了另一台机器因为内网DHCP有时候会换IP。如果提示Permission denied检查用户名是否正确、公钥是否真的追加到了authorized_keys里、.ssh目录和文件权限是否合规。可以用ssh -v看详细输出它会告诉你认证过程哪一步出了问题。如果提示Host key verification failed通常是因为服务器系统重装过指纹变了。清理一下Windows端known_hosts里对应IP的旧记录即可known_hosts位于C:/Users/你的用户名/.ssh/known_hosts。插件配置层面的问题可以打开输出面板下拉框选SFTP能看到插件自己的日志。日志里会给出更具体的连接过程和错误位置排查效率高很多。5.2 保存后不同步、中文乱码与权限报错保存后文件没有自动上传这种现象第一次遇到会很疑惑。实际上原因无非三种一是uploadOnSave没设成true二是你要上传的文件命中了ignore规则三是项目工作区不对你打开的文件夹不是当前配置对应的项目根目录。我自己踩过的坑是ignore写得太宽比如写了**/.vscode/**结果把整个.vscode目录都排除了包括sftp.json本身也传不上去后来发现远端根本没有配置文件才反应过来。注意ignore排除的是文件内容不是sftp.json这个文件本身的加载。中文乱码是Windows开发者特别容易遇到的问题。Windows记事本保存文件时默认带BOMUTF-8带BOM的文件传到服务器上用Linux工具处理时开头会多出不可见字符导致脚本执行报错或者内容显示异常。VS Code默认使用UTF-8无BOM所以问题通常不从VS Code来而是来自你用其他编辑器改过的文件。解决思路是全链路统一UTF-8保存文件时留意VS Code右下角编码标识避免混用。还有换行符问题。Windows文件的CRLF换行传到Linux上bash脚本会报“$\r: command not found”之类的错。我在VS Code设置里固定了files.eol: \n这样新文件的换行符统一是LF。对于已有文件可以点右下角CRLF/LF标识手动切换。很多人最后发现服务器上跑脚本失败原因根本不是代码逻辑而是看不见的\r。上传报Permission denied的解决办法比较直接。去服务器上看目标目录的属主和权限ls -ld /home/dev/projects/myapp如果不属于当前登录用户用chown修改归属sudo chown -R dev:dev /home/dev/projects/myapp5.3 大目录同步的提速经验首次同步整个项目时如果远程目录内容很大网速又一般那过程确实很煎熬。几个提速技巧比较实用。第一善用ignore。把node_modules、vendor、.git这些大规模目录排除掉之后需要同步的文件数量可能直接减少七八成。第二concurrency可以适当调高我的经验是4到8比较合适太高了会在服务器端创建过多SSH会话反而变慢。如果你对服务器性能有信心也可以临时调到10跑首次同步跑完再调回来。第三不要反复全量同步。日常开发中Diff Local vs Remote比无脑Sync效率高得多因为它能告诉你哪些文件真正有差异。一次全量同步之后后续增量同步的速度非常快因为插件会走增量比较。第四处理超大二进制文件时比如数据集或者打包产物不要指望插件能像专用工具一样做断点续传。SFTP插件擅长处理源码和小文件如果是几十GB的数据同步还是考虑专门的文件传输方案更合适。6. 几点个人体会与后续扩展最后分享一个我最初犯过的错有一回我拿一个正在运行的服务目录直接做首次Sync当时没想清楚同步策略把delete开成了true结果远端有几个我本地没有的配置文件被当成“过期文件”清掉了服务当时就异常了。那次之后我养成了一个习惯凡是拿真实环境做同步第一步先在服务器上备份目标目录至少也打个压缩包tar -czf myapp_backup.tar.gz myapp成本很低但心里有底。后来我的流程稳定下来是这样的本地写代码CtrlS自动上传每天下班前跑一次Diff Local vs Remote看一眼差异每周手动Sync Remote - Local拉一次远端生成的最新文件。这套规则保证了大多数时候两端是一致的又避免了双向自动同步带来的隐患。如果你后续的项目规模变大团队协作更频繁那确实可以考虑把部署流程迁到流水线或者容器方案文件同步会慢慢退居次要位置。但对于个人开发、小团队快速迭代、临时联调这些场景VS Code SFTP插件就是Windows和Ubuntu之间成本最低、逻辑最直观的同步方案。调整好配置养好操作习惯这个组合能让你少跑无数次命令行也确实值得花一个下午把原理和配置摸透。
