AllinSSL/frontend/.doc/plugin-replace-name.md

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 插件开发最佳实践确保良好的兼容性。