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

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


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


#### 二、功能模块设计

##### 1. 基础配置模块
- **核心参数**（必选）：
  - 协议类型（`protocol: 'ftp' | 'sftp'`）
  - 服务器地址（`host`）、端口（`port`）
  - 认证信息（用户名+密码/私钥）
  - 本地目录（`localDir`）与远程目录（`remoteDir`）

- **环境区分配置**：
  ```javascript
  // 示例：多环境配置
  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. 扩展能力
- **生命周期钩子**：
  ```javascript
  hooks: {
    beforeDeploy: (config) => { /* 部署前执行，如备份远程文件 */ },
    afterDeploy: (result) => { /* 部署后执行，如发送通知 */ },
    onFileUploaded: (file) => { /* 单个文件上传完成 */ }
  }
  ```

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


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

1. **安装配置**：
   ```bash
   npm i vite-plugin-deploy --save-dev
   ```
   ```javascript
   // 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. **日常开发部署**：
   ```bash
   # 构建并部署到默认环境
   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. **可扩展性**：支持根据团队流程定制化扩展


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