【调整】增加部署雨云

2026-03-08 07:41:10 +08:00 · 2026-01-13 17:47:39 +08:00
parent 4e49ca075a
commit 367c1a1096
1094 changed files with 179074 additions and 45 deletions
--- a/frontend/.doc/plugin-replace-name.md
+++ b/frontend/.doc/plugin-replace-name.md
@@ -0,0 +1,73 @@
+### Vite 文件名称替换插件设计方案
+
+#### 一、插件核心目标
+实现一个基于 Vite 的文件名称替换插件，通过 Node.js 文件系统 API，在开发或构建过程中根据预设规则自动重命名指定文件，支持灵活的匹配与替换逻辑。
+
+#### 二、核心功能设计
+1. **规则配置系统**
+   - 支持多组替换规则（从字符串/正则到目标字符串的映射）
+   - 支持路径过滤（include 包含规则、exclude 排除规则）
+   - 可配置执行时机（开发模式/构建模式/Watch 模式）
+
+2. **文件处理流程**
+   - 基于 Vite 插件钩子（configureServer、buildStart、watchChange 等）触发文件扫描
+   - 递归遍历目标目录，收集符合匹配规则的文件路径
+   - 对文件路径应用替换规则，生成新文件名
+   - 执行文件重命名操作（含冲突检测）
+
+3. **冲突处理机制**
+   - 重命名前检查目标路径是否已存在
+   - 提供冲突处理策略配置（跳过/覆盖/报错）
+   - 记录操作日志，便于问题追踪
+
+#### 三、实现架构
+1. **配置解析层**
+   - 定义配置schema（规则格式、匹配模式、执行时机等）
+   - 合并默认配置与用户配置
+   - 验证配置有效性
+
+2. **文件扫描层**
+   - 基于 glob 模式匹配文件
+   - 处理 include/exclude 过滤逻辑
+   - 区分文件/目录类型
+
+3. **规则应用层**
+   - 实现字符串替换引擎（支持普通字符串和正则表达式）
+   - 处理路径分割与重组（区分目录名和文件名）
+   - 支持链式规则应用（多规则依次执行）
+
+4. **文件操作层**
+   - 封装 Node.js fs 模块（rename、stat、access 等）
+   - 实现异步操作队列（避免并发冲突）
+   - 添加操作事务支持（失败可回滚）
+
+#### 四、Vite 集成点
+1. **开发模式集成**
+   - 通过 configureServer 钩子初始化插件
+   - 监听 server.watcher 事件处理文件新增/修改
+   - 在服务器启动完成后执行初始扫描
+
+2. **构建模式集成**
+   - 在 buildStart 钩子触发预处理扫描
+   - 通过 writeBundle 钩子处理输出目录文件
+   - 配合 rollup 的 asset 处理钩子拦截资源生成
+
+3. **插件生命周期**
+   - 初始化：解析配置、注册钩子
+   - 运行时：响应文件变化、执行重命名
+   - 销毁：清理缓存、释放资源
+
+#### 五、使用场景
+1. 统一文件命名规范（如驼峰转下划线）
+2. 批量添加/移除文件前缀/后缀
+3. 根据环境变量动态调整文件名
+4. 处理国际化资源文件命名
+5. 构建时生成带哈希值的文件名（补充 Vite 内置功能）
+
+#### 六、扩展能力
+1. 支持自定义替换函数（用户可编写复杂逻辑）
+2. 提供预览模式（仅显示替换结果不执行实际操作）
+3. 支持配置文件导出/导入
+4. 集成 Vite 配置的 resolve.alias 路径解析
+
+该方案通过分层设计保证了插件的灵活性和可扩展性，既满足基础的文件名替换需求，又能应对复杂的自定义场景，同时遵循 Vite 插件开发最佳实践确保良好的兼容性。
--- a/frontend/.doc/plugin-sftp.md
+++ b/frontend/.doc/plugin-sftp.md
@@ -0,0 +1,150 @@
+### 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. **可扩展性**：支持根据团队流程定制化扩展
+
+
+该方案通过聚焦开发效率与使用体验，将部署环节从"手动操作负担"转化为"自动化辅助工具"，让开发者更专注于代码开发而非部署流程。