AllinSSL/frontend/.doc/plugin-sftp.md

Vite 自动部署插件（FTP/SFTP）开发辅助方案

该方案专注于为开发者提供便捷、可靠的前端项目自动部署工具，通过 Vite 插件形式集成，实现构建完成后自动上传到远程服务器，减少手动部署的重复劳动与出错概率。

一、核心价值（开发辅助定位）

1. 无缝集成开发流程：与 Vite 构建流程深度融合，无需离开开发环境即可完成部署
2. 降低环境切换成本：统一本地配置与远程部署规则，避免"本地正常，线上出错"的环境差异问题
3. 安全管理敏感信息：通过环境变量隔离认证信息，防止密钥泄露
4. 可视化部署反馈：实时展示上传进度与结果，问题定位更高效
5. 支持多环境部署：一键切换开发/测试/生产环境配置，适配不同阶段部署需求

二、功能模块设计

1. 基础配置模块

• 核心参数（必选）：

  • 协议类型（protocol: 'ftp' | 'sftp'）
  • 服务器地址（host）、端口（port）
  • 认证信息（用户名+密码/私钥）
  • 本地目录（localDir）与远程目录（remoteDir）

• 环境区分配置：

  // 示例：多环境配置
  environments: {
    dev: { host: 'dev.server.com', remoteDir: '/dev' },
    test: { host: 'test.server.com', remoteDir: '/test' },
    prod: { host: 'prod.server.com', remoteDir: '/prod' }
  }
  

  支持通过命令行参数（--env=prod）快速切换环境

2. 智能上传模块

• 增量上传机制：

  • 基于文件哈希比对（默认 MD5），仅上传变更文件
  • 本地缓存已上传文件信息（.upload-cache目录），提速二次部署
  • 支持强制全量上传（--force命令行参数）

• 文件过滤系统：

  • 基础过滤：glob 模式匹配（include/exclude）
  • 高级过滤：自定义函数（如根据文件大小/类型过滤）
  • 内置排除项：.git、.DS_Store、.map等开发相关文件

• 传输优化：

  • 并发控制（默认 5 个文件同时上传，可配置）
  • 大文件分片传输（>10MB 自动分片，支持断点续传）
  • 传输模式自动选择（文本/二进制）

3. 开发友好特性

• 实时反馈机制：

  • 进度条展示：总进度、当前文件、传输速度
  • 详细日志输出：包含文件名、大小、状态（成功/失败）
  • 错误提示：明确指出失败原因（权限不足/文件不存在等）

• 调试辅助：

  • 模拟上传模式（dryRun: true）：仅展示上传列表，不实际传输
  • 调试日志（verbose: 'debug'）：输出完整协议交互信息
  • 本地文件校验：上传前检查本地文件完整性

• 快捷操作：

  • 独立部署命令：vite deploy（无需重新构建）
  • 配置验证命令：vite deploy --validate（检查配置合法性）
  • VS Code 插件集成：提供部署按钮与状态显示

4. 安全与容错模块

• 敏感信息保护：

  • 环境变量注入：process.env.SFTP_PASSWORD
  • 配置加密：支持对敏感字段加密存储
  • 日志脱敏：密码/私钥在日志中显示为***

• 容错机制：

  • 自动重试：连接失败/传输超时自动重试（默认 3 次）
  • 断线续传：网络中断恢复后继续未完成的上传
  • 部分失败处理：单个文件失败不阻断整体流程，最终汇总失败列表

5. 扩展能力

• 生命周期钩子：

  hooks: {
    beforeDeploy: (config) => { /* 部署前执行，如备份远程文件 */ },
    afterDeploy: (result) => { /* 部署后执行，如发送通知 */ },
    onFileUploaded: (file) => { /* 单个文件上传完成 */ }
  }
  

• 自定义处理器：

  • 上传前文件处理（如压缩、替换环境变量）
  • 自定义远程操作（如上传后执行远程命令）

三、使用流程（开发视角）

1. 安装配置：

   npm i vite-plugin-deploy --save-dev
   

   // vite.config.js
   import deploy from 'vite-plugin-deploy';
   
   export default {
     plugins: [
       deploy({
         protocol: 'sftp',
         host: 'your.server.com',
         username: 'deploy',
         privateKey: process.env.SSH_PRIVATE_KEY,
         localDir: 'dist',
         remoteDir: '/var/www/html',
         environments: { /* 多环境配置 */ }
       })
     ]
   }
   

2. 日常开发部署：

   # 构建并部署到默认环境
   npm run build
   
   # 构建并部署到测试环境
   npm run build -- --env=test
   
   # 仅部署（使用上次构建结果）
   npx vite deploy --env=prod
   
   # 模拟部署（不实际上传）
   npx vite deploy --dry-run
   

3. 问题排查：

   • 查看终端输出的错误信息
   • 启用调试模式：npx vite deploy --verbose=debug
   • 检查.upload-cache目录的缓存文件与远程文件差异

四、优势总结（开发体验）

1. 零学习成本：配置简洁直观，符合前端开发者习惯
2. 减少重复工作：一次配置，后续部署无需重复操作
3. 安全可靠：避免手动操作导致的误删文件/配置错误
4. 适配多场景：从个人开发调试到团队生产部署均适用
5. 可扩展性：支持根据团队流程定制化扩展

该方案通过聚焦开发效率与使用体验，将部署环节从"手动操作负担"转化为"自动化辅助工具"，让开发者更专注于代码开发而非部署流程。