搞开发最怕的不是写不出代码，而是写完了代码传不上服务器。我最早在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 dev@192.168.x.x "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"执行后输入一次用户密码，之后SSH登录就不再需要密码了。这里记住一个关键点：SSH公钥登录对文件权限非常敏感。服务器端的~/.ssh目录权限应该是700，authorized_keys文件权限应该是600。权限放太宽，SSH服务端会为了安全拒绝使用该公钥，而你看到的现象就是“明明公钥添加了，还是要求密码登录”。修复方式：
chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys全部搞完后先手动验证一下：
ssh dev@192.168.x.x如果直接登进去没让你输密码，说明SSH密钥链路已经通了，后面配置SFTP插件会顺畅很多。
3. 核心配置：sftp.json逐字段拆解
3.1 一条命令生成配置文件
在VS Code里，用Ctrl+Shift+P打开命令面板，输入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，别用ftp，ftp是明文传输，密码和文件内容都是裸奔的。
- port：默认22，除非你改了sshd_config里的Port。
- username：登录用户，对应服务器上那个有目录权限的账号。
- privateKeyPath：Windows本机私钥的绝对路径。路径分隔符建议用正斜杠/，反斜杠容易出转义问题。如果你想用密码登录，也可以写"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：你按Ctrl+S保存本地文件，插件立刻把文件上传到远端对应路径。这个是本地发起、推送远端的单向操作。
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没配对好的典型翻车现场。
除了ignore，syncOption.delete这个选项更要谨慎。delete为true表示：本地删了某个文件，同步上传时远端也删掉。听起来合理，但危险在于，如果你的本地目录暂时缺失某些内容，比如你忘了拉取远端最新文件，此时执行Sync Local -> Remote，远端那些“最新文件”就会因为本地没有而被误删。所以我建议首次使用阶段，delete保持false，只做新增和覆盖，不做删除。等你对整个同步逻辑都熟悉了，再考虑开启delete。
5. 踩坑复盘：连接失败、文件错乱与性能问题
5.1 连不上服务器的排查顺序
SFTP插件报错信息有时候比较笼统，尤其是“Failed to connect”这种，说了等于没说。我总结了一套排查顺序，按这个步骤走基本能找到问题。
首先排查SSH服务本身。在Windows端命令行直接执行ssh dev@192.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记事本保存文件时默认带BOM，UTF-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成本很低，但心里有底。
后来我的流程稳定下来是这样的：本地写代码，Ctrl+S自动上传，每天下班前跑一次Diff Local vs Remote看一眼差异，每周手动Sync Remote -> Local拉一次远端生成的最新文件。这套规则保证了大多数时候两端是一致的，又避免了双向自动同步带来的隐患。
如果你后续的项目规模变大，团队协作更频繁，那确实可以考虑把部署流程迁到流水线或者容器方案，文件同步会慢慢退居次要位置。但对于个人开发、小团队快速迭代、临时联调这些场景，VS Code SFTP插件就是Windows和Ubuntu之间成本最低、逻辑最直观的同步方案。调整好配置，养好操作习惯，这个组合能让你少跑无数次命令行，也确实值得花一个下午把原理和配置摸透。
