Vite插件v0.2.5：注释头模板化升级
版本：0.2.5 | 协议：MIT | 依赖：Vite >=5.0.0 <8.0.0
写在前面
v0.2.5 的主题是：让注释头从"开关"变为"模板"。
本次更新将generateRouter的fileHeader参数升级为headerTemplate，从简单的布尔开关进化为支持占位符的字符串模板系统。你可以自由组合{name}、{date}、{date:格式}、{version}、{custom:键名}
等占位符，按需定制注释头内容、顺序和日期格式。同时新增customFields选项，支持注入自定义字段。
此外，移除了已废弃且无消费者的serializeValueCompact函数。
本版重点：
| 能力 | 一句话说明 | 你需要做什么 |
|---|---|---|
headerTemplate模板系统 | 字符串模板 + 占位符，自由组合注释头内容和顺序 | 替换fileHeader为新参数 |
| 自定义日期格式 | {date:YYYY-MM-DD}等灵活格式化 | 在模板中使用{date:格式} |
自定义字段customFields | {custom:键名}占位符注入自定义内容 | 配置customFields选项 |
移除serializeValueCompact | 已废弃且无消费者，使用serializeValue(value, true)替代 | 检查是否有直接调用 |
升级方式：修改devDependencies中版本号为^0.2.5。有 Breaking Change，需将fileHeader替换为headerTemplate。
一、5 分钟快速上手
1.1 安装与升级
{"devDependencies":{"@meng-xi/vite-plugin":"^0.2.5"}}1.2 迁移 fileHeader → headerTemplate
// v0.2.4：使用 fileHeadergenerateRouter({fileHeader:true})// v0.2.5：替换为 headerTemplategenerateRouter({headerTemplate:true})| 0.2.4 | 0.2.5 | 说明 |
|---|---|---|
fileHeader: true | headerTemplate: true | 生成默认注释头 |
fileHeader: false | headerTemplate: false/ 不传 | 不生成注释头 |
| - | headerTemplate: '{name} {date:YYYY-MM-DD} {version}' | 自定义模板（新增） |
1.3 自定义模板
// 默认注释头（与 0.2.4 fileHeader: true 输出一致）generateRouter({headerTemplate:true})// 生成：/**// * generate-router 2026-06-24 14:30:00 0.2.5// */// 自定义日期格式generateRouter({headerTemplate:'{name} {date:YYYY-MM-DD} {version}'})// 生成：/**// * generate-router 2026-06-24 0.2.5// */// 自定义字段generateRouter({headerTemplate:'{name} {custom:author} {date} {version}',customFields:{author:'MengXi Studio'}})// 生成：/**// * generate-router MengXi Studio 2026-06-24 14:30:00 0.2.5// */二、headerTemplate 模板系统
2.1 占位符一览
| 占位符 | 替换值 | 示例 |
|---|---|---|
{name} | 插件名称 | generate-router |
{date} | 生成日期时间（默认格式YYYY-MM-DD HH:mm:ss） | 2026-06-24 14:30:00 |
{date:格式} | 按指定格式输出日期时间 | {date:YYYY-MM-DD}→2026-06-24 |
{version} | 插件版本号 | 0.2.5 |
{custom:键名} | 自定义字段，值从customFields读取 | {custom:author}→MengXi Studio |
2.2 顺序由模板决定
占位符在模板中的位置决定了注释头中的输出顺序：
// 日期在前generateRouter({headerTemplate:'{date:YYYY-MM-DD} {name} {version}'})// 生成：/**// * 2026-06-24 generate-router 0.2.5// */// 版本在前generateRouter({headerTemplate:'{version} {name} {date}'})// 生成：/**// * 0.2.5 generate-router 2026-06-24 14:30:00// */2.3 日期格式化
{date:格式}支持与formatDate一致的格式符：
| 格式符 | 含义 | 示例 |
|---|---|---|
YYYY | 四位年份 | 2026 |
MM | 两位月份 | 06 |
DD | 两位日期 | 24 |
HH | 两位小时 | 14 |
mm | 两位分钟 | 30 |
ss | 两位秒数 | 00 |
// 仅日期generateRouter({headerTemplate:'{name} {date:YYYY-MM-DD}'})// → generate-router 2026-06-24// 紧凑格式generateRouter({headerTemplate:'{name} {date:YYYYMMDD_HHmmss}'})// → generate-router 20260624_1430002.4 自定义字段
通过customFields选项为{custom:键名}占位符提供值：
generateRouter({headerTemplate:'{name} {custom:author} {custom:project} {date:YYYY-MM-DD} {version}',customFields:{author:'MengXi Studio',project:'MyApp'}})// 生成：/**// * generate-router MengXi Studio MyApp 2026-06-24 0.2.5// */如果{custom:键名}对应的键在customFields中不存在，占位符将原样保留。
三、Breaking Changes 详解
3.1 fileHeader → headerTemplate
fileHeader参数已完全移除，替换为headerTemplate：
// ❌ 0.2.5 不再支持generateRouter({fileHeader:true})// ✅ 使用 headerTemplategenerateRouter({headerTemplate:true})重命名理由：参数从boolean升级为boolean | string后，核心能力是模板，headerTemplate更准确描述字符串模板功能。
3.2 serializeValueCompact 移除
serializeValueCompact已废弃且无消费者，直接使用serializeValue(value, true)替代：
// ❌ 已移除import{serializeValueCompact}from'@meng-xi/vite-plugin/common/code-manipulation'// ✅ 替代方案import{serializeValue}from'@meng-xi/vite-plugin/common/code-manipulation'serializeValue(value,true)四、完整配置项
interfaceGenerateRouterOptionsextendsBasePluginOptions{pagesJsonPath?:string// pages.json 路径，默认 'src/pages.json'outputPath?:string// 输出文件路径，默认 'src/router.config.ts'outputFormat?:'ts'|'js'// 输出格式，默认 'ts'nameStrategy?:NameStrategy// 命名策略，默认 'camelCase'customNameGenerator?:(path:string)=>string// 自定义命名函数includeSubPackages?:boolean// 包含子包，默认 truewatch?:boolean// 监听变化，默认 truemetaMapping?:Record<string,string>// meta 字段映射exportTypes?:boolean// 导出类型，默认 truepreserveRouteChanges?:boolean// 保留用户修改，默认 truedts?:string|boolean// 类型声明文件，默认 falseheaderTemplate?:boolean|string// 文件注释头模板，默认 falsecustomFields?:Record<string,string>// 自定义字段键值对，默认 {}}五、实战场景
5.1 团队协作：注释头标注作者和项目
// vite.config.tsimport{generateRouter}from'@meng-xi/vite-plugin'exportdefaultdefineConfig({plugins:[generateRouter({headerTemplate:'{name} {custom:author} {custom:project} {date:YYYY-MM-DD} {version}',customFields:{author:'MengXi Studio',project:'MyApp'},preserveRouteChanges:true,dts:true})]})生成的文件：
/** * generate-router MengXi Studio MyApp 2026-06-24 0.2.5 */importtype{RouteConfig}from'@meng-xi/uni-router'exportconstroutes:RouteConfig[]=[{path:'/pages/index/index',name:'Home',meta:{title:'首页',isTab:true}}]exportdefaultroutes5.2 精简注释头：仅保留日期和版本
generateRouter({headerTemplate:'{date:YYYY-MM-DD} v{version}'})// 生成：/**// * 2026-06-24 v0.2.5// */5.3 CI/CD 友好：紧凑时间戳
generateRouter({headerTemplate:'{name} {date:YYYYMMDD_HHmmss} {version}'})// 生成：/**// * generate-router 20260624_143000 0.2.5// */六、内置插件全景
v0.2.5 共包含15 个实用插件，覆盖构建优化的各个方面：
| 插件 | enforce | 描述 |
|---|---|---|
assetManifest | post | 构建后生成资源映射清单，支持 Vite/Webpack/自定义格式、按入口分组和运行时注入 |
autoImport | pre | 自动导入，支持预设映射、通配符（'*'）、目录扫描、Vue 模板自动导入和类型声明生成 |
buildProgress | - | 终端实时构建进度条，支持 bar / spinner / minimal |
bundleAnalyzer | post | 构建产物体积分析，支持 JSON/HTML 报告、gzip 计算和阈值告警 |
compressAssets | post | 构建产物压缩，支持 gzip / brotli / both，并发压缩和统计报告 |
copyFile | post | 构建完成后复制文件或目录，支持增量复制 |
envGuard | post | 环境变量校验，支持类型检查、范围验证、自定义规则和运行时守卫 |
faviconManager | post | 管理网站图标链接注入和文件复制 |
generateRouter | post | 根据 pages.json 自动生成路由配置与类型声明（uni-app） |
generateVersion | post | 自动生成版本号，支持文件输出和全局变量注入 |
htmlInject | post | HTML 内容注入，支持多种位置、选择器定位、条件注入和安全过滤 |
imageOptimizer | post | 图片优化压缩与格式转换，支持 WebP/AVIF 转换、SVG 优化、并发处理 |
loadingManager | post | 全局 Loading 状态管理，支持请求拦截、防抖、过渡动画 |
proxyManager | - | 开发代理管理，支持环境切换、规则文件、请求日志、延迟模拟和响应修改 |
versionUpdateChecker | post | 运行时版本更新检查，支持多种提示样式和自定义回调 |
七、子路径导出变更
移除
@meng-xi/vite-plugin/plugins/generate-router移除配置选项：fileHeader@meng-xi/vite-plugin/common/code-manipulation移除导出函数：serializeValueCompact
新增
@meng-xi/vite-plugin/plugins/generate-router新增配置选项：headerTemplate（boolean | string）@meng-xi/vite-plugin/plugins/generate-router新增配置选项：customFields（Record<string, string>）