vscode-sftp-config

VSCode SFTP 配置

配置 VSCode SFTP，以将静态网站部署到生产服务器。提供完整工作流，包括带有安全标头、缓存策略和性能优化的生产就绪型 Nginx 配置模板。

核心工作流

步骤 1：分析项目结构

确定要部署的静态文件：

• 纯静态项目：位于根目录中的 HTML、CSS、JS
• 基于构建的项目：查找 dist/、build/ 或 public/ 输出目录
• 静态网站生成器：检查 package.json 或文档中的构建命令

向用户询问部署详情：

1. 远程服务器地址（IP 或主机名）
2. 远程路径（例如 /var/www/sitename）
3. SSH 身份验证方式（密码或 SSH 密钥路径）
4. Nginx 配置所需的域名
5. 这是主域名还是子域名

步骤 2：生成 SFTP 配置

VSCode 扩展：此技能使用 Satiro Marra 开发的 code-sftp 扩展。

步骤 2A：配置 SSH Config（推荐最佳实践）

创建 sftp.json 之前，先在 ~/.ssh/config 中设置 SSH 主机别名，便于管理：

Host project-prod
    HostName 82.157.29.215
    User root
    Port 22
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

SSH config 的优点：

• ✅ 消除 SFTP 扩展警告（Section for 'IP' not found）
• ✅ 在终端中使用主机别名：ssh project-prod
• ✅ 集中管理 SSH 设置（连接保活、压缩等）
• ✅ 更轻松地管理多个环境（开发、预发布、生产）

检查 ~/.ssh/config 中是否已有该服务器：

cat ~/.ssh/config | grep -A 5 "82.157.29.215"

如果找到，则使用现有主机别名；如果没有，则添加新条目。

步骤 2B：创建 SFTP 配置

使用 assets/sftp.json.template 中的模板创建 .vscode/sftp.json。

必要的配置字段：

• name：便于识别的配置名称
• host：SSH 主机别名（例如 "Tencent_Pro"）或 IP 地址
• protocol：SFTP 使用 "sftp"（安全），FTP 使用 "ftp"
• port：SFTP 使用 22，FTP 使用 21
• username：SSH/FTP 用户名
• privateKeyPath：SSH 私钥路径（例如 /Users/username/.ssh/id_rsa）
• remotePath：远程目录路径（例如 /var/www/sitename）
• uploadOnSave：建议设为 false（手动同步更安全）

可选高级字段：

• ignore：要排除在上传之外的文件/文件夹数组
• watcher：自动上传的文件监视配置
• syncOption：同步行为（删除、更新、跳过现有文件）
• useTempFile：上传时使用临时文件
• downloadOnOpen：打开文件时自动下载

根据项目进行自定义：

• 将 {{HOST_ALIAS}} 替换为 SSH config 别名（推荐）或 IP 地址
• 将其他 {{PLACEHOLDERS}} 替换为实际值
• 将项目专属文件添加到 ignore 数组（.claude、nginx.conf、构建产物等）
• 对于基于构建的项目：保留 uploadOnSave: false，构建后手动同步
• 对于纯静态项目：可选择启用 uploadOnSave: true，以即时部署

步骤 3：生成 Nginx 配置

选择合适的模板：

• 主域名：主网站使用 assets/nginx-static.conf.template
• 子域名：类似 slides.example.com 的子域名使用 assets/nginx-subdomain.conf.template

自定义配置：

1. 将 {{DOMAIN}} 替换为实际域名
2. 将 {{DOCUMENT_ROOT}} 替换为远程路径（例如 /var/www/aiseed）
3. 如果使用自定义证书，调整 SSL 证书路径
4. 根据需要配置子域名专属设置

加入 references/nginx-best-practices.md 中的必要功能：

• HTTP → HTTPS 重定向
• HTTP/2 支持
• Gzip 压缩
• 静态资源缓存（JS/CSS/图片缓存 1 年，HTML 缓存 1 小时）
• 安全标头（HSTS、X-Frame-Options、CSP 等）
• 访问日志和错误日志

第 4 步：提供部署说明

根据 assets/deploy-checklist.md 生成部署检查清单：

1. 初始设置（一次性）：

   • 安装 VSCode 扩展：Satiro Marra 开发的 code-sftp
   • 打开命令面板（Cmd/Ctrl+Shift+P）→ SFTP: Config，创建 .vscode/sftp.json
   • 验证 SSH 服务器访问权限：ssh user@host
   • 确保远程目录存在：ssh user@host "mkdir -p /var/www/sitename"
   • 设置适当的权限：ssh user@host "chmod 755 /var/www/sitename"

2. 文件部署：

   • 对于构建项目：先运行构建命令（例如 npm run build）
   • 打开 VSCode 命令面板 → SFTP: Sync Local → Remote，上传所有文件
   • 或者在资源管理器中右键点击文件夹 → “上传文件夹”
   • 在 VSCode 输出面板中监控上传进度（视图 → 输出 → SFTP）
   • 验证文件是否已上传：ssh user@host "ls -la /var/www/sitename"

3. Nginx 配置：

   • 将生成的配置上传到 /etc/nginx/sites-available/
   • 创建符号链接：ln -s /etc/nginx/sites-available/site.conf /etc/nginx/sites-enabled/
   • 测试配置：sudo nginx -t
   • 重新加载：sudo systemctl reload nginx

4. SSL/TLS 设置（如果尚未配置）：

   • 参阅 references/ssl-security.md 了解证书设置
   • 使用 Let's Encrypt 获取免费证书：certbot --nginx -d example.com

5. 验证：

   • 测试 HTTPS：curl -I https://example.com
   • 检查安全标头：使用 securityheaders.com
   • 测试性能：使用 PageSpeed Insights

第 5 步：记录设置

在项目文档（README.md 或 CLAUDE.md）中更新以下内容：

• 部署方式（通过 SFTP 部署到 /var/www/path）
• SFTP 配置位置（.vscode/sftp.json）
• Nginx 配置参考
• 构建命令（如适用）
• 后续更新的部署工作流

此架构的优势

向用户说明静态文件 + SFTP 部署的优势：

1. 简单：编辑 → 上传 → 上线（无需构建流水线或容器）
2. 性能：Nginx 提供静态文件的速度比 Node.js/Python 后端更快
3. 可靠：无需担心后端进程崩溃或挂起
4. 资源效率：降低服务器内存和 CPU 使用量
5. 经济实惠：可托管在配置最低的 VPS 或共享主机上
6. 轻松回滚：从备份目录复制之前的版本

不适用此架构的情况

以下情况不适合采用静态文件 + SFTP 部署：

• 需要后端 API 端点
• 需要服务器端表单处理（除非使用 n8n、FormSpree 等外部服务）
• 需要用户身份验证或会话
• 需要与数据库交互
• 需要服务器端渲染（SSR）

资源

references/

• ssh-config.md - SSH 配置文件设置与最佳实践（主机别名、跳转主机、安全性）
• nginx-best-practices.md - 面向静态网站的全面 Nginx 优化指南
• ssl-security.md - SSL/TLS 证书设置与安全配置

assets/

• sftp.json.template - VSCode SFTP 配置模板（数组格式，使用 SSH 主机别名）
• nginx-static.conf.template - 主域名 Nginx 配置模板
• nginx-subdomain.conf.template - 子域名 Nginx 配置模板
• deploy-checklist.md - 逐步部署验证检查清单