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：使用 fileHeader
generateRouter({ fileHeader: true })

// v0.2.5：替换为 headerTemplate
generateRouter({ 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_143000

2.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 })

// ✅ 使用 headerTemplate
generateRouter({ 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)

---

四、完整配置项

interface GenerateRouterOptions extends BasePluginOptions {
	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 // 包含子包，默认 true
	watch?: boolean // 监听变化，默认 true
	metaMapping?: Record<string, string> // meta 字段映射
	exportTypes?: boolean // 导出类型，默认 true
	preserveRouteChanges?: boolean // 保留用户修改，默认 true
	dts?: string | boolean // 类型声明文件，默认 false
	headerTemplate?: boolean | string // 文件注释头模板，默认 false
	customFields?: Record<string, string> // 自定义字段键值对，默认 {}
}

---

五、实战场景

5.1 团队协作：注释头标注作者和项目

// vite.config.ts
import { generateRouter } from '@meng-xi/vite-plugin'

export default defineConfig({
	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
 */

import type { RouteConfig } from '@meng-xi/uni-router'

export const routes: RouteConfig[] = [
	{
		path: '/pages/index/index',
		name: 'Home',
		meta: { title: '首页', isTab: true }
	}
]

export default routes

5.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>）