@meng-xi/vite-plugin 0.0.9 → 0.1.1

package/README.md

@@ -15,7 +15,7 @@
 
 ## 特性
 
-- **开箱即用** - 提供 6 个实用插件，覆盖构建进度展示、文件复制、路由生成、版本管理、图标注入、全局 Loading 状态管理等常见场景
+- **开箱即用** - 提供 8 个实用插件，覆盖构建进度展示、文件复制、路由生成、版本管理、版本更新检查、HTML 注入、图标注入、全局 Loading 状态管理等常见场景
 - **插件开发框架** - 导出 BasePlugin、Logger、Validator 等核心组件，快速构建符合规范的自定义 Vite 插件
 - **完整生命周期** - 支持初始化、配置解析、销毁等生命周期管理，自动组合钩子逻辑
 - **类型安全** - 完整的 TypeScript 类型定义，配置验证器确保参数正确性
@@ -46,7 +46,7 @@ pnpm add @meng-xi/vite-plugin -D
 
 ```typescript
 import { defineConfig } from 'vite'
-import { buildProgress, copyFile, generateRouter, generateVersion, injectIco, injectLoading } from '@meng-xi/vite-plugin'
+import { buildProgress, copyFile, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
 
 export default defineConfig({
 	plugins: [
@@ -71,11 +71,25 @@ export default defineConfig({
 			outputType: 'both'
 		}),
 
+		// 版本更新检查（配合 generateVersion 使用）
+		versionUpdateChecker(),
+
+		// HTML 内容注入
+		htmlInject({
+			rules: [
+				{
+					id: 'meta-description',
+					content: '<meta name="description" content="My App">',
+					position: 'head-end'
+				}
+			]
+		}),
+
 		// 注入网站图标（支持字符串简写）
-		injectIco('/assets'),
+		faviconManager('/assets'),
 
-		// 注入全局 Loading
-		injectLoading({
+		// 全局 Loading 状态管理
+		loadingManager({
 			defaultVisible: true,
 			autoHideOn: 'DOMContentLoaded'
 		})
@@ -97,238 +111,18 @@ const routerPlugin = generateRouter({ watch: true }) as PluginWithInstance<Gener
 console.log(routerPlugin.pluginInstance?.options)
 ```
 
-### 开发自定义插件
-
-```typescript
-import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
-import type { BasePluginOptions, PluginWithInstance } from '@meng-xi/vite-plugin/factory'
-import type { Plugin } from 'vite'
-
-interface MyPluginOptions extends BasePluginOptions {
-	path: string
-}
-
-class MyPlugin extends BasePlugin<MyPluginOptions> {
-	protected getDefaultOptions() {
-		return { path: './default' }
-	}
-
-	protected validateOptions(): void {
-		this.validator.field('path').required().string().validate()
-	}
-
-	protected getPluginName(): string {
-		return 'my-plugin'
-	}
-
-	protected addPluginHooks(plugin: Plugin): void {
-		plugin.buildStart = () => {
-			this.logger.info(`Plugin started with path: ${this.options.path}`)
-		}
-	}
-
-	protected destroy(): void {
-		super.destroy()
-		// 自定义清理逻辑，如关闭连接、停止监听等
-	}
-}
-
-// 基本使用
-export const myPlugin = createPluginFactory(MyPlugin)
-
-// 带标准化器（支持字符串简写配置）
-export const myPluginWithNormalizer = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
-// 使用时支持简写：myPluginWithNormalizer('./custom-path')
-```
-
-## 插件开发框架
-
-### BasePlugin 核心概念
-
-`BasePlugin` 是所有插件的基类，提供了完整的生命周期管理和开发规范：
-
-#### 生命周期
-
-| 阶段     | 方法               | 说明                                   |
-| -------- | ------------------ | -------------------------------------- |
-| 初始化   | `constructor`      | 合并配置、初始化日志和验证器           |
-| 配置解析 | `onConfigResolved` | Vite 配置解析完成时调用                |
-| 钩子注册 | `addPluginHooks`   | 注册 Vite 插件钩子                     |
-| 销毁     | `destroy`          | `closeBundle` 时自动调用，用于清理资源 |
-
-#### 钩子自动组合
-
-`toPlugin()` 方法会自动组合以下钩子：
-
-- **configResolved** - 先执行基类的 `onConfigResolved`，再执行子类注册的钩子
-- **closeBundle** - 先执行子类注册的钩子，再执行基类的 `destroy`
-
-> 子类无需手动注册 `closeBundle` 钩子来清理资源，只需重写 `destroy()` 方法即可。
-
-#### 必须实现的方法
-
-| 方法                     | 说明               |
-| ------------------------ | ------------------ |
-| `getPluginName()`        | 返回插件名称       |
-| `addPluginHooks(plugin)` | 添加 Vite 插件钩子 |
-
-#### 可选重写的方法
-
-| 方法                       | 默认行为    | 说明                               |
-| -------------------------- | ----------- | ---------------------------------- |
-| `getDefaultOptions()`      | 返回 `{}`   | 提供插件默认配置                   |
-| `validateOptions()`        | 无验证      | 验证配置参数                       |
-| `getEnforce()`             | `undefined` | 插件执行时机（`'pre'` / `'post'`） |
-| `onConfigResolved(config)` | 存储配置    | 配置解析完成回调                   |
-| `destroy()`                | 注销日志    | 插件销毁时的清理逻辑               |
-
-#### 内置属性
-
-| 属性         | 类型                     | 说明              |
-| ------------ | ------------------------ | ----------------- |
-| `options`    | `Required<T>`            | 合并后的完整配置  |
-| `logger`     | `PluginLogger`           | 插件日志记录器    |
-| `validator`  | `Validator<T>`           | 配置验证器        |
-| `viteConfig` | `ResolvedConfig \| null` | Vite 解析后的配置 |
-
-#### 错误处理策略
-
-通过 `errorStrategy` 配置项控制错误行为：
-
-- `'throw'`（默认）- 记录错误并抛出异常，中断构建
-- `'log'` - 记录错误但不抛出，继续执行
-- `'ignore'` - 记录错误但不抛出，继续执行
-
-使用 `safeExecute` / `safeExecuteSync` 包裹可能出错的操作：
-
-```typescript
-// 异步安全执行
-const result = await this.safeExecute(async () => {
-	return await someAsyncOperation()
-}, '执行异步操作')
-
-// 同步安全执行
-const value = this.safeExecuteSync(() => {
-	return someSyncOperation()
-}, '执行同步操作')
-```
-
-### createPluginFactory
-
-创建插件工厂函数，支持选项标准化器：
-
-```typescript
-// 基本使用
-const myPlugin = createPluginFactory(MyPlugin)
-
-// 带标准化器（支持字符串简写配置）
-const myPlugin = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
-
-// 使用时支持简写
-myPlugin('./custom-path')
-```
-
-### Validator
-
-流畅的配置验证器，支持链式调用：
-
-```typescript
-import { Validator } from '@meng-xi/vite-plugin/common'
-
-const validator = new Validator(options)
-validator
-	.field('sourceDir')
-	.required()
-	.string()
-	.field('targetDir')
-	.required()
-	.string()
-	.field('overwrite')
-	.boolean()
-	.default(true)
-	.field('port')
-	.number()
-	.field('list')
-	.array()
-	.field('config')
-	.object()
-	.field('name')
-	.custom(val => val.length > 0, 'name 不能为空')
-	.validate()
-```
-
-| 方法         | 说明                                               |
-| ------------ | -------------------------------------------------- |
-| `field()`    | 指定要验证的字段                                   |
-| `required()` | 标记字段为必填                                     |
-| `string()`   | 验证字段值是否为字符串类型                         |
-| `boolean()`  | 验证字段值是否为布尔类型                           |
-| `number()`   | 验证字段值是否为数字类型                           |
-| `array()`    | 验证字段值是否为数组类型                           |
-| `object()`   | 验证字段值是否为对象类型                           |
-| `default()`  | 为字段设置默认值（仅当值为 undefined/null 时生效） |
-| `custom()`   | 使用自定义函数验证字段值                           |
-| `validate()` | 执行验证，失败时抛出错误                           |
-
-### Logger
-
-全局单例日志管理器，为每个插件提供独立的日志控制：
-
-```typescript
-import { Logger } from '@meng-xi/vite-plugin/logger'
-
-// 创建日志记录器（通常由 BasePlugin 自动调用）
-Logger.create({ name: 'my-plugin', enabled: true })
-
-// 注销插件日志配置（插件销毁时自动调用）
-Logger.unregister('my-plugin')
-
-// 销毁单例（测试场景使用）
-Logger.destroy()
-```
-
-日志输出格式：
-
-```
-ℹ️ [@meng-xi/vite-plugin:my-plugin] Info message
-✅ [@meng-xi/vite-plugin:my-plugin] Success message
-⚠️ [@meng-xi/vite-plugin:my-plugin] Warning message
-❌ [@meng-xi/vite-plugin:my-plugin] Error message
-```
-
-### 通用工具函数
-
-通过 `@meng-xi/vite-plugin/common` 导出，可在自定义插件中复用：
-
-```typescript
-import { deepMerge, formatDate, parseTemplate, toCamelCase, toPascalCase, stripJsonComments, generateRandomHash, Validator } from '@meng-xi/vite-plugin/common'
-import { readFileContent, writeFileContent, fileExists, copySourceToTarget } from '@meng-xi/vite-plugin/common'
-```
-
-| 函数                   | 说明                                               |
-| ---------------------- | -------------------------------------------------- |
-| `deepMerge()`          | 深度合并对象（undefined 不覆盖，数组直接覆盖）     |
-| `formatDate()`         | 格式化日期，支持 `{YYYY}`, `{MM}`, `{DD}` 等占位符 |
-| `parseTemplate()`      | 解析模板字符串，替换占位符                         |
-| `toCamelCase()`        | 转换为驼峰命名（camelCase）                        |
-| `toPascalCase()`       | 转换为帕斯卡命名（PascalCase）                     |
-| `stripJsonComments()`  | 移除 JSON 字符串中的注释                           |
-| `generateRandomHash()` | 生成随机哈希字符串（1-64 位）                      |
-| `readFileContent()`    | 异步读取文件内容                                   |
-| `writeFileContent()`   | 异步写入文件内容                                   |
-| `fileExists()`         | 异步检查文件是否存在                               |
-| `copySourceToTarget()` | 复制文件或目录，支持增量复制和并发控制             |
-
 ## 内置插件
 
-| 插件            | 说明                                                  |
-| --------------- | ----------------------------------------------------- |
-| buildProgress   | 终端实时构建进度条，支持 bar / spinner / minimal      |
-| copyFile        | 构建完成后复制文件或目录，支持增量复制                |
-| generateRouter  | 根据 pages.json 自动生成路由配置（uni-app）           |
-| generateVersion | 自动生成版本号，支持文件输出和全局变量注入            |
-| injectIco       | 将网站图标链接注入到 HTML 文件，支持字符串简写配置    |
-| injectLoading   | 注入全局 Loading 状态管理，支持请求拦截和白屏 Loading |
+| 插件                 | 说明                                                            |
+| -------------------- | --------------------------------------------------------------- |
+| buildProgress        | 终端实时构建进度条，支持 bar / spinner / minimal                |
+| copyFile             | 构建完成后复制文件或目录，支持增量复制                          |
+| generateRouter       | 根据 pages.json 自动生成路由配置（uni-app）                     |
+| generateVersion      | 自动生成版本号，支持文件输出和全局变量注入                      |
+| versionUpdateChecker | 运行时版本更新检查，支持多种提示样式和自定义回调                |
+| htmlInject           | HTML 内容注入，支持多种位置、条件注入、模板变量替换和安全过滤   |
+| faviconManager       | 管理网站图标（favicon）链接注入到 HTML 文件，支持字符串简写配置 |
+| loadingManager       | 全局 Loading 状态管理，支持请求拦截和白屏 Loading               |
 
 ### buildProgress
 
@@ -531,7 +325,166 @@ generateVersion({
 })
 ```
 
-### injectIco
+### versionUpdateChecker
+
+在运行时定期检查版本号变更，发现新版本时提示用户刷新页面。通常与 `generateVersion` 插件配合使用。
+
+**工作原理：**
+
+1. `generateVersion` 在构建时生成版本号文件（`version.json`）或注入全局变量
+2. `versionUpdateChecker` 在运行时定期请求版本文件，与当前版本对比
+3. 发现版本不一致时，弹出提示引导用户刷新
+
+| 选项                    | 类型                                 | 默认值                                     | 描述                                 |
+| ----------------------- | ------------------------------------ | ------------------------------------------ | ------------------------------------ |
+| versionSource           | `'define'` \| `'file'` \| `'auto'`   | `'auto'`                                   | 当前版本号来源                       |
+| defineName              | `string`                             | `'__APP_VERSION__'`                        | define 模式下的全局变量名            |
+| checkUrl                | `string`                             | `'/version.json'`                          | 版本检查文件的 URL 路径              |
+| checkInterval           | `number`                             | `300000`                                   | 检查间隔时间（毫秒，默认 5 分钟）    |
+| checkOnVisibilityChange | `boolean`                            | `true`                                     | 页面可见性变化时是否立即检查         |
+| enableInDev             | `boolean`                            | `false`                                    | 是否在开发模式下启用                 |
+| promptStyle             | `'modal'` \| `'banner'` \| `'toast'` | `'modal'`                                  | 更新提示 UI 样式                     |
+| promptMessage           | `string`                             | `'发现新版本，是否立即刷新获取最新内容？'` | 提示消息文本                         |
+| refreshButtonText       | `string`                             | `'立即刷新'`                               | 刷新按钮文本                         |
+| dismissButtonText       | `string`                             | `'稍后再说'`                               | 忽略按钮文本                         |
+| customPromptTemplate    | `string`                             | -                                          | 自定义提示 UI 的 HTML 模板           |
+| customStyle             | `string`                             | -                                          | 自定义 CSS 样式字符串                |
+| onUpdateAvailable       | `string`                             | -                                          | 发现新版本时的回调（函数体字符串）   |
+| onRefresh               | `string`                             | -                                          | 用户选择刷新时的回调（函数体字符串） |
+| onDismiss               | `string`                             | -                                          | 用户选择忽略时的回调（函数体字符串） |
+
+> `versionSource` 说明：`'define'` 从全局变量读取，`'file'` 从版本文件读取，`'auto'` 优先使用 define，回退到 file。自定义模板中可使用
+> `{{message}}`、`{{currentVersion}}`、`{{newVersion}}`、`{{refreshButton}}`、`{{dismissButton}}` 占位符。回调以函数体字符串形式提供，可用变量：`currentVersion`、`newVersion`。
+
+```typescript
+// 基本使用（配合 generateVersion）
+generateVersion({ outputType: 'both' })
+versionUpdateChecker()
+
+// 仅从版本文件读取
+versionUpdateChecker({ versionSource: 'file' })
+
+// 自定义检查间隔和提示样式
+versionUpdateChecker({
+	checkInterval: 60000,
+	promptStyle: 'banner'
+})
+
+// 底部轻提示
+versionUpdateChecker({ promptStyle: 'toast' })
+
+// 自定义提示文本
+versionUpdateChecker({
+	promptMessage: '系统已更新，建议刷新体验新功能',
+	refreshButtonText: '更新',
+	dismissButtonText: '取消'
+})
+
+// 自定义回调
+versionUpdateChecker({
+	onUpdateAvailable: 'console.log("新版本:", newVersion); return true;',
+	onRefresh: 'console.log("用户选择刷新");',
+	onDismiss: 'console.log("用户选择忽略");'
+})
+
+// 开发环境也启用（调试用）
+versionUpdateChecker({ enableInDev: true })
+```
+
+### htmlInject
+
+在 Vite 构建过程中根据配置规则将 HTML 内容注入到目标文件中，支持多种注入位置、条件注入、模板变量替换和安全过滤。
+
+**注入位置：**
+
+| 位置               | 说明                       |
+| ------------------ | -------------------------- |
+| `head-start`       | 注入到 `<head>` 标签开始后 |
+| `head-end`         | 注入到 `</head>` 标签前    |
+| `body-start`       | 注入到 `<body>` 标签开始后 |
+| `body-end`         | 注入到 `</body>` 标签前    |
+| `before-selector`  | 注入到选择器匹配内容前     |
+| `after-selector`   | 注入到选择器匹配内容后     |
+| `replace-selector` | 替换选择器匹配的内容       |
+
+| 选项         | 类型                     | 默认值         | 描述                       |
+| ------------ | ------------------------ | -------------- | -------------------------- |
+| targetFile   | `string`                 | `'index.html'` | 目标 HTML 文件路径或文件名 |
+| rules        | `InjectRule[]`           | -              | 注入规则数组（必填）       |
+| security     | `SecurityConfig`         | -              | 安全过滤配置               |
+| templateVars | `Record<string, string>` | -              | 全局模板变量               |
+| logInjection | `boolean`                | `true`         | 是否输出注入日志           |
+
+**InjectRule**
+
+| 属性                 | 类型                     | 默认值     | 描述                                |
+| -------------------- | ------------------------ | ---------- | ----------------------------------- |
+| id                   | `string`                 | -          | 规则唯一标识，用于日志和调试        |
+| content              | `string`                 | -          | 要注入的 HTML 内容（必填）          |
+| position             | `InjectPosition`         | -          | 注入位置（必填）                    |
+| selector             | `string`                 | -          | 选择器字符串（selector 位置时必填） |
+| selectorMatch        | `'string'` \| `'regex'`  | `'string'` | 选择器匹配模式                      |
+| priority             | `number`                 | `100`      | 优先级，数值越小越先执行            |
+| condition            | `InjectCondition`        | -          | 注入条件                            |
+| templateVars         | `Record<string, string>` | -          | 规则级模板变量（覆盖全局）          |
+| allowScriptInjection | `boolean`                | `false`    | 是否允许注入脚本等危险内容          |
+
+**InjectCondition**
+
+| 属性   | 类型                                        | 默认值  | 描述               |
+| ------ | ------------------------------------------- | ------- | ------------------ |
+| type   | `'env'` \| `'file-contains'` \| `'custom'`  | -       | 条件类型（必填）   |
+| value  | `string` \| `((...args: any[]) => boolean)` | -       | 条件值（必填）     |
+| negate | `boolean`                                   | `false` | 是否对条件结果取反 |
+
+**SecurityConfig**
+
+| 属性                     | 类型       | 默认值 | 描述                 |
+| ------------------------ | ---------- | ------ | -------------------- |
+| blockDangerousTags       | `boolean`  | `true` | 是否阻止危险标签     |
+| blockDangerousAttributes | `boolean`  | `true` | 是否阻止危险属性     |
+| allowedTags              | `string[]` | -      | 允许通过的标签白名单 |
+| blockedTags              | `string[]` | -      | 自定义阻止标签列表   |
+| blockedAttributes        | `string[]` | -      | 自定义阻止属性列表   |
+
+```typescript
+// 基本使用
+htmlInject({
+	rules: [{ id: 'meta-desc', content: '<meta name="description" content="My App">', position: 'head-end' }]
+})
+
+// 条件注入（仅生产环境）
+htmlInject({
+	rules: [
+		{
+			id: 'analytics',
+			content: '<script src="/analytics.js"></script>',
+			position: 'body-end',
+			condition: { type: 'env', value: 'PRODUCTION' },
+			allowScriptInjection: true
+		}
+	]
+})
+
+// 模板变量替换
+htmlInject({
+	templateVars: { appName: 'My App', version: '1.0.0' },
+	rules: [{ id: 'meta', content: '<meta name="description" content="{{appName}}">', position: 'head-end' }]
+})
+
+// 选择器注入
+htmlInject({
+	rules: [{ id: 'replace-title', content: '<title>New Title</title>', position: 'replace-selector', selector: '<title>.*</title>', selectorMatch: 'regex' }]
+})
+
+// 安全配置
+htmlInject({
+	security: { blockDangerousTags: true, allowedTags: ['iframe'] },
+	rules: [{ id: 'embed', content: '<iframe src="https://example.com"></iframe>', position: 'body-end' }]
+})
+```
+
+### faviconManager
 
 在 Vite 构建过程中将网站图标链接注入到 HTML 文件的 head 中。支持字符串简写配置。
 
@@ -565,13 +518,13 @@ generateVersion({
 
 ```typescript
 // 使用默认配置
-injectIco()
+faviconManager()
 
 // 字符串简写（设置 base 路径）
-injectIco('/assets')
+faviconManager('/assets')
 
 // 自定义图标数组
-injectIco({
+faviconManager({
 	base: '/assets',
 	icons: [
 		{ rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
@@ -581,12 +534,12 @@ injectIco({
 })
 
 // 自定义完整 link 标签
-injectIco({
+faviconManager({
 	link: '<link rel="icon" href="/favicon.svg" type="image/svg+xml" />'
 })
 
 // 带文件复制
-injectIco({
+faviconManager({
 	base: '/assets',
 	copyOptions: {
 		sourceDir: 'src/assets/icons',
@@ -595,7 +548,7 @@ injectIco({
 })
 ```
 
-### injectLoading
+### loadingManager
 
 注入全局 Loading 状态管理，支持 XHR/Fetch 请求拦截、白屏 Loading、自定义样式和生命周期回调。
 
@@ -709,30 +662,30 @@ injectIco({
 
 ```typescript
 // 白屏 Loading：页面加载即显示，DOM 就绪后自动隐藏
-injectLoading({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
+loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
 
 // 白屏 Loading：所有资源加载完成后隐藏
-injectLoading({ defaultVisible: true, autoHideOn: 'load' })
+loadingManager({ defaultVisible: true, autoHideOn: 'load' })
 
 // Vue/React SPA：白屏即显示，框架渲染完成后手动隐藏
-injectLoading({ defaultVisible: true, autoHideOn: 'manual' })
+loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
 // 在应用入口处：window.__LOADING_MANAGER__.hide()
 
 // 自动拦截所有请求
-injectLoading({ autoBind: 'all' })
+loadingManager({ autoBind: 'all' })
 
 // 自定义样式 + 请求过滤
-injectLoading({
+loadingManager({
 	style: { overlayColor: 'rgba(0,0,0,0.5)', spinnerColor: '#fff', backdropBlur: true },
 	autoBind: 'fetch',
 	requestFilter: { excludeUrls: [/\/api\/health/], excludeUrlPrefixes: ['http://localhost'] }
 })
 
 // 防抖隐藏（避免快速闪烁）
-injectLoading({ debounceHide: { enabled: true, duration: 100 } })
+loadingManager({ debounceHide: { enabled: true, duration: 100 } })
 
 // 生命周期回调
-injectLoading({
+loadingManager({
 	callbacks: {
 		onBeforeShow: 'if (shouldSkip) return false;',
 		onShow: 'console.log("loading shown")',
@@ -742,31 +695,275 @@ injectLoading({
 })
 
 // 手动控制
-injectLoading()
+loadingManager()
 window.__LOADING_MANAGER__.show('正在保存...')
 window.__LOADING_MANAGER__.hide()
 window.__LOADING_MANAGER__.toggle()
 window.__LOADING_MANAGER__.disablePointerEvents()
 ```
 
+## 通用工具函数
+
+通过 `@meng-xi/vite-plugin/common` 导出，可在自定义插件中复用：
+
+```typescript
+import { deepMerge, formatDate, parseTemplate, toCamelCase, toPascalCase, stripJsonComments, generateRandomHash, escapeHtmlAttr, Validator } from '@meng-xi/vite-plugin/common'
+import { readFileContent, writeFileContent, fileExists, copySourceToTarget } from '@meng-xi/vite-plugin/common/fs'
+import { injectBeforeTag, injectHtmlByPriority, injectBeforeTagWithFallback, injectHeadAndBody } from '@meng-xi/vite-plugin/common/html'
+import { makeCallback, containsScriptTag, validateIdentifierName } from '@meng-xi/vite-plugin/common/script'
+import { validateGlobalName, validateNoScriptInTemplate, validateCallbackFields, validateNonNegativeNumber, validateNestedDuration, validateEnumValue } from '@meng-xi/vite-plugin/common/validation'
+```
+
+| 函数                            | 说明                                                            | 子路径              |
+| ------------------------------- | --------------------------------------------------------------- | ------------------- |
+| `deepMerge()`                   | 深度合并对象（undefined 不覆盖，数组直接覆盖）                  | `common/object`     |
+| `formatDate()`                  | 格式化日期，支持 `{YYYY}`, `{MM}`, `{DD}` 等占位符              | `common/format`     |
+| `parseTemplate()`               | 解析模板字符串，替换占位符                                      | `common/format`     |
+| `toCamelCase()`                 | 转换为驼峰命名（camelCase）                                     | `common/format`     |
+| `toPascalCase()`                | 转换为帕斯卡命名（PascalCase）                                  | `common/format`     |
+| `stripJsonComments()`           | 移除 JSON 字符串中的注释                                        | `common/format`     |
+| `generateRandomHash()`          | 生成随机哈希字符串（1-64 位）                                   | `common/format`     |
+| `escapeHtmlAttr()`              | 转义 HTML 属性值中的特殊字符，防止 XSS 注入                     | `common/format`     |
+| `readFileContent()`             | 异步读取文件内容                                                | `common/fs`         |
+| `writeFileContent()`            | 异步写入文件内容                                                | `common/fs`         |
+| `fileExists()`                  | 异步检查文件是否存在                                            | `common/fs`         |
+| `copySourceToTarget()`          | 复制文件或目录，支持增量复制和并发控制                          | `common/fs`         |
+| `injectBeforeTag()`             | 在 HTML 指定闭合标签前注入代码                                  | `common/html`       |
+| `injectHtmlByPriority()`        | 按优先级向 HTML 中注入代码（`</head>` → `</body>` → `</html>`） | `common/html`       |
+| `injectBeforeTagWithFallback()` | 带回退策略的 HTML 注入（`</body>` → `</html>` → 末尾）          | `common/html`       |
+| `injectHeadAndBody()`           | 双区域 HTML 注入（head + body）                                 | `common/html`       |
+| `makeCallback()`                | 将回调函数体包装为安全的函数表达式（含 try-catch）              | `common/script`     |
+| `containsScriptTag()`           | 检测字符串是否包含 `<script>` 标签                              | `common/script`     |
+| `validateIdentifierName()`      | 验证字符串是否为合法的 JavaScript 标识符，防止原型污染          | `common/script`     |
+| `validateGlobalName()`          | 验证全局变量名的合法性                                          | `common/validation` |
+| `validateNoScriptInTemplate()`  | 验证模板字符串不包含 script 标签（XSS 防护）                    | `common/validation` |
+| `validateCallbackFields()`      | 验证回调字段不包含 script 标签                                  | `common/validation` |
+| `validateNonNegativeNumber()`   | 验证数值为非负数                                                | `common/validation` |
+| `validateNestedDuration()`      | 验证嵌套配置项的 duration 合法性                                | `common/validation` |
+| `validateEnumValue()`           | 验证字符串值是否在允许的枚举列表中                              | `common/validation` |
+
+## 插件开发框架
+
+### BasePlugin 核心概念
+
+`BasePlugin` 是所有插件的基类，提供了完整的生命周期管理和开发规范：
+
+#### 生命周期
+
+| 阶段     | 方法               | 说明                                   |
+| -------- | ------------------ | -------------------------------------- |
+| 初始化   | `constructor`      | 合并配置、初始化日志和验证器           |
+| 配置解析 | `onConfigResolved` | Vite 配置解析完成时调用                |
+| 钩子注册 | `addPluginHooks`   | 注册 Vite 插件钩子                     |
+| 销毁     | `destroy`          | `closeBundle` 时自动调用，用于清理资源 |
+
+#### 钩子自动组合
+
+`toPlugin()` 方法会自动组合以下钩子：
+
+- **configResolved** - 先执行基类的 `onConfigResolved`，再执行子类注册的钩子
+- **closeBundle** - 先执行子类注册的钩子，再执行基类的 `destroy`
+
+> 子类无需手动注册 `closeBundle` 钩子来清理资源，只需重写 `destroy()` 方法即可。
+
+#### 必须实现的方法
+
+| 方法                     | 说明               |
+| ------------------------ | ------------------ |
+| `getPluginName()`        | 返回插件名称       |
+| `addPluginHooks(plugin)` | 添加 Vite 插件钩子 |
+
+#### 可选重写的方法
+
+| 方法                       | 默认行为    | 说明                               |
+| -------------------------- | ----------- | ---------------------------------- |
+| `getDefaultOptions()`      | 返回 `{}`   | 提供插件默认配置                   |
+| `validateOptions()`        | 无验证      | 验证配置参数                       |
+| `getEnforce()`             | `undefined` | 插件执行时机（`'pre'` / `'post'`） |
+| `onConfigResolved(config)` | 存储配置    | 配置解析完成回调                   |
+| `destroy()`                | 注销日志    | 插件销毁时的清理逻辑               |
+
+#### 内置属性
+
+| 属性         | 类型                     | 说明              |
+| ------------ | ------------------------ | ----------------- |
+| `options`    | `Required<T>`            | 合并后的完整配置  |
+| `logger`     | `PluginLogger`           | 插件日志记录器    |
+| `validator`  | `Validator<T>`           | 配置验证器        |
+| `viteConfig` | `ResolvedConfig \| null` | Vite 解析后的配置 |
+
+#### 错误处理策略
+
+通过 `errorStrategy` 配置项控制错误行为：
+
+- `'throw'`（默认）- 记录错误并抛出异常，中断构建
+- `'log'` - 记录错误但不抛出，继续执行
+- `'ignore'` - 记录错误但不抛出，继续执行
+
+使用 `safeExecute` / `safeExecuteSync` 包裹可能出错的操作：
+
+```typescript
+// 异步安全执行
+const result = await this.safeExecute(async () => {
+	return await someAsyncOperation()
+}, '执行异步操作')
+
+// 同步安全执行
+const value = this.safeExecuteSync(() => {
+	return someSyncOperation()
+}, '执行同步操作')
+```
+
+### createPluginFactory
+
+创建插件工厂函数，支持选项标准化器：
+
+```typescript
+// 基本使用
+const myPlugin = createPluginFactory(MyPlugin)
+
+// 带标准化器（支持字符串简写配置）
+const myPlugin = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
+
+// 使用时支持简写
+myPlugin('./custom-path')
+```
+
+### Validator
+
+流畅的配置验证器，支持链式调用：
+
+```typescript
+import { Validator } from '@meng-xi/vite-plugin/common'
+
+const validator = new Validator(options)
+validator
+	.field('sourceDir')
+	.required()
+	.string()
+	.field('targetDir')
+	.required()
+	.string()
+	.field('overwrite')
+	.boolean()
+	.default(true)
+	.field('port')
+	.number()
+	.field('list')
+	.array()
+	.field('config')
+	.object()
+	.field('name')
+	.custom(val => val.length > 0, 'name 不能为空')
+	.validate()
+```
+
+| 方法         | 说明                                               |
+| ------------ | -------------------------------------------------- |
+| `field()`    | 指定要验证的字段                                   |
+| `required()` | 标记字段为必填                                     |
+| `string()`   | 验证字段值是否为字符串类型                         |
+| `boolean()`  | 验证字段值是否为布尔类型                           |
+| `number()`   | 验证字段值是否为数字类型                           |
+| `array()`    | 验证字段值是否为数组类型                           |
+| `object()`   | 验证字段值是否为对象类型                           |
+| `enum()`     | 验证字段值是否在允许的枚举列表中                   |
+| `minValue()` | 验证数字字段值是否不小于指定最小值                 |
+| `maxValue()` | 验证数字字段值是否不大于指定最大值                 |
+| `default()`  | 为字段设置默认值（仅当值为 undefined/null 时生效） |
+| `custom()`   | 使用自定义函数验证字段值                           |
+| `validate()` | 执行验证，失败时抛出错误                           |
+
+### Logger
+
+全局单例日志管理器，为每个插件提供独立的日志控制：
+
+```typescript
+import { Logger } from '@meng-xi/vite-plugin/logger'
+
+// 创建日志记录器（通常由 BasePlugin 自动调用）
+Logger.create({ name: 'my-plugin', enabled: true })
+
+// 注销插件日志配置（插件销毁时自动调用）
+Logger.unregister('my-plugin')
+
+// 销毁单例（测试场景使用）
+Logger.destroy()
+```
+
+日志输出格式：
+
+```
+ℹ️ [@meng-xi/vite-plugin:my-plugin] Info message
+✅ [@meng-xi/vite-plugin:my-plugin] Success message
+⚠️ [@meng-xi/vite-plugin:my-plugin] Warning message
+❌ [@meng-xi/vite-plugin:my-plugin] Error message
+```
+
+### 开发自定义插件示例
+
+```typescript
+import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
+import type { BasePluginOptions, PluginWithInstance } from '@meng-xi/vite-plugin/factory'
+import type { Plugin } from 'vite'
+
+interface MyPluginOptions extends BasePluginOptions {
+	path: string
+}
+
+class MyPlugin extends BasePlugin<MyPluginOptions> {
+	protected getDefaultOptions() {
+		return { path: './default' }
+	}
+
+	protected validateOptions(): void {
+		this.validator.field('path').required().string().validate()
+	}
+
+	protected getPluginName(): string {
+		return 'my-plugin'
+	}
+
+	protected addPluginHooks(plugin: Plugin): void {
+		plugin.buildStart = () => {
+			this.logger.info(`Plugin started with path: ${this.options.path}`)
+		}
+	}
+
+	protected destroy(): void {
+		super.destroy()
+		// 自定义清理逻辑，如关闭连接、停止监听等
+	}
+}
+
+// 基本使用
+export const myPlugin = createPluginFactory(MyPlugin)
+
+// 带标准化器（支持字符串简写配置）
+export const myPluginWithNormalizer = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { path: opt } : opt))
+// 使用时支持简写：myPluginWithNormalizer('./custom-path')
+```
+
 ## 子路径导出
 
 支持按需导入模块，减少打包体积：
 
 ```typescript
 // 完整导入
-import { buildProgress, copyFile, injectLoading, BasePlugin, Logger } from '@meng-xi/vite-plugin'
+import { buildProgress, copyFile, htmlInject, loadingManager, BasePlugin, Logger } from '@meng-xi/vite-plugin'
 
 // 按模块导入
 import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'
 import { Logger } from '@meng-xi/vite-plugin/logger'
-import { buildProgress, copyFile, generateRouter, injectLoading } from '@meng-xi/vite-plugin/plugins'
+import { buildProgress, copyFile, generateRouter, htmlInject, loadingManager } from '@meng-xi/vite-plugin/plugins'
 import { Validator, readFileContent, writeFileContent } from '@meng-xi/vite-plugin/common'
 
 // 类型导入（从子路径按需导入类型定义）
 import type { PluginWithInstance, PluginFactory, BasePluginOptions } from '@meng-xi/vite-plugin/factory'
-import type { BuildProgressOptions, GenerateVersionOptions, InjectIcoOptions, InjectLoadingOptions, Icon } from '@meng-xi/vite-plugin/plugins'
-import type { DateFormatOptions } from '@meng-xi/vite-plugin/common'
+import type { BuildProgressOptions, GenerateVersionOptions, VersionUpdateCheckerOptions, HtmlInjectOptions, InjectRule, FaviconManagerOptions, LoadingManagerOptions, Icon } from '@meng-xi/vite-plugin/plugins'
+import type { DateFormatOptions } from '@meng-xi/vite-plugin/common/format'
+import type { HtmlInjectResult, DualInjectResult } from '@meng-xi/vite-plugin/common/html'
+import type { CopyOptions, CopyResult } from '@meng-xi/vite-plugin/common/fs'
 ```
 
 ## 更新日志