VSCode SFTP 同步流程指南

适用场景：在本地使用 VSCode 编辑代码，保存后自动上传到远程 Linux 服务器（如阿里云、腾讯云、AutoDL 等），或手动下载/上传文件。

1️⃣ 安装 SFTP 扩展

1. 打开 VSCode，点击左侧活动栏的扩展图标 （或按 Ctrl+Shift+X）。
2. 在搜索框中输入 SFTP。
3. 找到由 Natizyskunk 维护的版本（图标通常为蓝色文件夹），点击 Install。
4. 安装完成后，可能需要重新加载 VSCode（部分版本会自动重新加载）。

✅ 推荐原因：该扩展维护活跃，支持 uploadOnSave、watcher 等高级功能，兼容性较好。

2️⃣ 初始化 SFTP 配置文件

1. 打开你本地项目的根文件夹（File → Open Folder）。
2. 按 Ctrl+Shift+P 打开命令面板，输入 SFTP: Config，回车。
3. VSCode 会自动在项目根目录下创建 .vscode 文件夹，并在其中生成 sftp.json 配置文件。

3️⃣ 编辑配置文件（连接你的服务器）

打开 .vscode/sftp.json，将默认内容替换为以下模板，并根据你的服务器信息修改。

{
  "name": "My Server",                // 连接名称，随便写
  "host": "your-server.com",          // 服务器 IP 或域名
  "port": 22,                         // SSH 端口，通常是 22
  "username": "root",                 // 登录用户名
  "password": "your-password",        // 密码（与私钥二选一）
  "privateKeyPath": null,             // 私钥路径，如 "C:/Users/YourName/.ssh/id_rsa"
  "remotePath": "/var/www/html",      // 远程同步目录（绝对路径）
  "uploadOnSave": true,               // 保存时自动上传
  "ignore": [                         // 忽略不同步的文件/文件夹
    ".vscode",
    ".git",
    "node_modules",
    "__pycache__"
  ]
}

关键字段说明

字段	说明
host	服务器公网 IP 或域名（如 example.com 或 connect.westc.seetacloud.com）
port	SSH 端口，默认 22。如果服务器用了非标准端口（如 29347），填写实际端口
username	SSH 登录用户名（常见 root、ubuntu 等）
password / privateKeyPath	二选一：密码登录或密钥登录（推荐密钥）
remotePath	远程目录，末尾不要加斜杠 ，例如 /home/user/project
uploadOnSave	true 时，每次保存文件（Ctrl+S）自动上传到远程对应路径
ignore	不同步的本地文件/文件夹，支持 glob 模式

💡 密钥登录示例：

"privateKeyPath": "C:/Users/你的用户名/.ssh/id_rsa",
"passphrase": null   // 如果私钥有密码，则填写

🖥️ 特殊场景：AutoDL 等云服务

如果使用 AutoDL、算力云等平台，其 SSH 地址通常是 connect.xxx.com 加一个动态端口。请从控制台复制 完整的 SSH 命令，例如：

ssh -p 29347 root@connect.westc.seetacloud.com

那么配置为：

"host": "connect.westc.seetacloud.com",
"port": 29347,
"username": "root",
"password": "你的密码"

⚠️ 注意：这些平台的 IP/端口有时会变化，若连接失败请重新检查控制台信息。

4️⃣ 保存配置并测试连接

1. 保存 sftp.json 文件（Ctrl+S）。
2. 在 VSCode 左侧资源管理器中，右键点击任意文件或文件夹 → 选择 SFTP: Download（下载远程内容）或 SFTP: Upload（上传本地内容）。
3. 如果首次连接，会提示保存服务器指纹，选择 Continue。
4. 若操作成功，说明配置正确；若失败，请查看第 6 步的常见问题。

5️⃣ 日常同步操作

✅ 自动同步（推荐）

• 确保配置中 "uploadOnSave": true。
• 之后每次按 Ctrl+S 保存文件，修改会自动上传到远程服务器的相同相对路径下。

🖱️ 手动同步

在 VSCode 的文件管理器（资源管理器）中，右键点击任意文件或文件夹，可以看到以下 SFTP 菜单：

菜单项	作用
Download	从远程下载选中文件/文件夹到本地（覆盖本地）
Upload	将本地文件/文件夹上传到远程（覆盖远程）
Sync Local -> Remote	同步本地 → 远程（上传）
Sync Remote -> Local	同步远程 → 本地（下载）
Sync Both Directions	双向同步（谨慎使用，可能覆盖最新改动）

💡 建议：日常开发使用 uploadOnSave 自动上传；如果远程已有更新，先手动 Download 再编辑。

6️⃣ 高级配置（可选）

📁 多服务器切换

sftp.json 支持数组格式，可配置多个服务器，然后用命令切换。

[
  {
    "name": "生产服务器",
    "host": "prod.example.com",
    ...
  },
  {
    "name": "测试服务器",
    "host": "test.example.com",
    ...
  }
]

切换方式：Ctrl+Shift+P → SFTP: Set Profile → 选择需要的服务器。

🔁 监听文件变动（watcher）

若需要同步删除、重命名等操作，可配置 watcher（会占用更多系统资源）。

{
  ...,
  "watcher": {
    "files": "**/*",      // 监听所有文件
    "autoUpload": true,   // 自动上传
    "autoDelete": true    // 本地删除时自动删除远程
  }
}

⚠️ 注意：watcher 可能与 uploadOnSave 冲突，建议二选一 ，优先使用 uploadOnSave。

7️⃣ 常见问题与解决方法

❌ 错误：ECONNREFUSED（连接被拒绝）

原因 ：网络不通或 SSH 服务未运行。
解决：

1. 检查服务器是否开机，SSH 服务是否运行（systemctl status ssh）。
2. 确认防火墙允许端口（如 ufw allow 22）。
3. 如果是云服务（AutoDL 等），重新从控制台获取正确的 IP 和端口。
4. 用 telnet 或 Test-NetConnection 测试端口是否可达。

❌ 错误：Permission denied（认证失败）

原因 ：用户名、密码或密钥错误。
解决：

• 确认用户名（如 root 或 ubuntu）。
• 使用密码登录时，确保密码正确（可尝试用 SSH 客户端连接测试）。
• 使用密钥登录时，确保私钥路径正确，且私钥权限为 600（Windows 默认无此限制）。

❌ 保存后没有自动上传

原因：

1. uploadOnSave 未设为 true。
2. 远程路径 remotePath 不正确或没有写权限。
3. 文件或文件夹在 ignore 列表中。
4. 扩展出现异常。
   解决：

• 查看 SFTP 日志：Ctrl+Shift+P → SFTP: Open Log，根据日志定位错误。
• 尝试手动右键 Upload 测试能否成功。

❌ 上传的文件位置不对（路径错误）

原因 ：remotePath 配置了错误的根路径。
解决：

• remotePath 是远程同步的根目录。本地文件 src/index.js 会同步到 remotePath/src/index.js。
• 检查 remotePath 是否正确，末尾不要有斜杠。

❌ 文件被忽略，不同步

检查配置中的 ignore 列表，如果文件/文件夹匹配了忽略模式，则不会同步。可以临时删除忽略项测试。

8️⃣ 完整示例：从零配置一个 Python 项目同步

1. 本地项目结构

   C:/my_project/
   ├── .vscode/
   │   └── sftp.json
   ├── src/
   │   └── train.py
   └── data/

2. 服务器信息

   • IP：123.45.67.89
   • 端口：22
   • 用户名：root
   • 密码：123456
   • 远程目录：/root/projects/my_project

3. sftp.json 配置

   {
       "name": "My Python Server",
       "host": "123.45.67.89",
       "port": 22,
       "username": "root",
       "password": "123456",
       "remotePath": "/root/projects/my_project",
       "uploadOnSave": true,
       "ignore": [".vscode", "__pycache__", ".git", "data/large_file.csv"]
   }

4. 开始使用

   • 保存配置后，右键项目根目录 → Upload 上传所有文件。
   • 编辑 src/train.py，按 Ctrl+S，文件自动上传到远程 /root/projects/my_project/src/train.py。
   • 删除本地 data/old.txt，远程不会自动删除（如需删除需手动操作或配置 watcher）。

📌 总结

通过以上 8 个步骤，你可以轻松实现 VSCode 与远程服务器的文件同步。核心要点：

• 安装扩展 → 生成配置 → 填写服务器信息 → 测试连接。
• 日常使用 uploadOnSave 实现自动同步。
• 遇到问题先查看日志 （SFTP: Open Log），再根据错误类型排查。