@meng-xi/vite-plugin 0.1.0 → 0.1.2

package/dist/plugins/generateVersion/index.d.mts

@@ -0,0 +1,184 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.mjs';
+import '../../shared/vite-plugin.DRRlWY8P.mjs';
+
+/**
+ * 版本号格式类型
+ *
+ * @description
+ * - 'timestamp': 时间戳格式，如 '20260203153000'
+ * - 'date': 日期格式，如 '2026.02.03'
+ * - 'datetime': 日期时间格式，如 '2026.02.03.153000'
+ * - 'semver': 语义化版本格式，如 '1.0.0'
+ * - 'hash': 随机哈希格式，如 'a1b2c3d4'
+ * - 'custom': 自定义格式，需要配合 customFormat 使用
+ */
+type VersionFormat = 'timestamp' | 'date' | 'datetime' | 'semver' | 'hash' | 'custom';
+/**
+ * 版本号输出类型
+ *
+ * @description
+ * - 'file': 输出到文件
+ * - 'define': 通过 Vite 的 define 注入到代码中
+ * - 'both': 同时输出到文件和注入代码
+ */
+type OutputType = 'file' | 'define' | 'both';
+/**
+ * 版本信息接口
+ *
+ * @description generateVersion 插件生成的版本信息对象类型，
+ * 通过 define 注入到代码中后可通过 `__APP_VERSION___INFO` 全局变量访问
+ */
+interface VersionInfo {
+    /** 版本号字符串 */
+    version: string;
+    /** 构建时间（ISO 8601 格式） */
+    buildTime: string;
+    /** 构建时间戳（毫秒） */
+    timestamp: number;
+    /** 版本号格式 */
+    format: VersionFormat;
+    /** 通过 extra 选项附加的自定义字段 */
+    [key: string]: unknown;
+}
+/**
+ * 自动生成版本号插件的配置选项接口
+ *
+ * @interface GenerateVersionOptions
+ */
+interface GenerateVersionOptions extends BasePluginOptions {
+    /**
+     * 版本号格式
+     *
+     * @default 'timestamp'
+     */
+    format?: VersionFormat;
+    /**
+     * 自定义格式模板，仅当 format 为 'custom' 时有效
+     *
+     * @description 支持以下占位符：
+     * - {YYYY}: 四位年份
+     * - {MM}: 两位月份
+     * - {DD}: 两位日期
+     * - {HH}: 两位小时
+     * - {mm}: 两位分钟
+     * - {ss}: 两位秒数
+     * - {timestamp}: 时间戳
+     * - {hash}: 随机哈希
+     * - {major}: 主版本号（需配合 semverBase）
+     * - {minor}: 次版本号（需配合 semverBase）
+     * - {patch}: 补丁版本号（需配合 semverBase）
+     *
+     * @example '{YYYY}.{MM}.{DD}-{hash}'
+     */
+    customFormat?: string;
+    /**
+     * 语义化版本基础值，用于 semver 格式
+     *
+     * @default '1.0.0'
+     */
+    semverBase?: string;
+    /**
+     * 输出类型
+     *
+     * @default 'file'
+     */
+    outputType?: OutputType;
+    /**
+     * 输出文件路径（相对于构建输出目录）
+     *
+     * @default 'version.json'
+     */
+    outputFile?: string;
+    /**
+     * 注入到代码中的全局变量名
+     *
+     * @default '__APP_VERSION__'
+     */
+    defineName?: string;
+    /**
+     * 哈希长度
+     *
+     * @default 8
+     */
+    hashLength?: number;
+    /**
+     * 版本号前缀
+     *
+     * @example 'v'
+     */
+    prefix?: string;
+    /**
+     * 版本号后缀
+     *
+     * @example '-beta'
+     */
+    suffix?: string;
+    /**
+     * 额外的版本信息，会包含在输出的 JSON 文件中
+     */
+    extra?: Record<string, any>;
+}
+
+/**
+ * 自动生成版本号插件
+ *
+ * @param {GenerateVersionOptions} options - 插件配置选项
+ * @returns {Plugin} 一个 Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // 基本使用 - 时间戳格式
+ * generateVersion()
+ *
+ * // 日期格式
+ * generateVersion({
+ *   format: 'date'
+ * })
+ *
+ * // 语义化版本格式
+ * generateVersion({
+ *   format: 'semver',
+ *   semverBase: '2.0.0',
+ *   prefix: 'v'
+ * })
+ *
+ * // 自定义格式
+ * generateVersion({
+ *   format: 'custom',
+ *   customFormat: '{YYYY}.{MM}.{DD}-{hash}',
+ *   hashLength: 6
+ * })
+ *
+ * // 注入到代码中
+ * generateVersion({
+ *   outputType: 'define',
+ *   defineName: '__VERSION__'
+ * })
+ *
+ * // 同时输出文件和注入代码
+ * generateVersion({
+ *   outputType: 'both',
+ *   outputFile: 'build-info.json',
+ *   defineName: '__BUILD_VERSION__',
+ *   extra: {
+ *     environment: 'production',
+ *     author: 'MengXi Studio'
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * 该插件会在 Vite 构建过程中自动生成版本号，支持多种格式：
+ * - timestamp: 时间戳格式 (20260203153000)
+ * - date: 日期格式 (2026.02.03)
+ * - datetime: 日期时间格式 (2026.02.03.153000)
+ * - semver: 语义化版本格式 (1.0.0)
+ * - hash: 随机哈希格式 (a1b2c3d4)
+ * - custom: 自定义格式
+ */
+declare const generateVersion: PluginFactory<GenerateVersionOptions, GenerateVersionOptions>;
+
+export { generateVersion };
+export type { GenerateVersionOptions, OutputType, VersionFormat, VersionInfo };

package/dist/plugins/generateVersion/index.d.ts

@@ -0,0 +1,184 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.js';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.js';
+import '../../shared/vite-plugin.DRRlWY8P.js';
+
+/**
+ * 版本号格式类型
+ *
+ * @description
+ * - 'timestamp': 时间戳格式，如 '20260203153000'
+ * - 'date': 日期格式，如 '2026.02.03'
+ * - 'datetime': 日期时间格式，如 '2026.02.03.153000'
+ * - 'semver': 语义化版本格式，如 '1.0.0'
+ * - 'hash': 随机哈希格式，如 'a1b2c3d4'
+ * - 'custom': 自定义格式，需要配合 customFormat 使用
+ */
+type VersionFormat = 'timestamp' | 'date' | 'datetime' | 'semver' | 'hash' | 'custom';
+/**
+ * 版本号输出类型
+ *
+ * @description
+ * - 'file': 输出到文件
+ * - 'define': 通过 Vite 的 define 注入到代码中
+ * - 'both': 同时输出到文件和注入代码
+ */
+type OutputType = 'file' | 'define' | 'both';
+/**
+ * 版本信息接口
+ *
+ * @description generateVersion 插件生成的版本信息对象类型，
+ * 通过 define 注入到代码中后可通过 `__APP_VERSION___INFO` 全局变量访问
+ */
+interface VersionInfo {
+    /** 版本号字符串 */
+    version: string;
+    /** 构建时间（ISO 8601 格式） */
+    buildTime: string;
+    /** 构建时间戳（毫秒） */
+    timestamp: number;
+    /** 版本号格式 */
+    format: VersionFormat;
+    /** 通过 extra 选项附加的自定义字段 */
+    [key: string]: unknown;
+}
+/**
+ * 自动生成版本号插件的配置选项接口
+ *
+ * @interface GenerateVersionOptions
+ */
+interface GenerateVersionOptions extends BasePluginOptions {
+    /**
+     * 版本号格式
+     *
+     * @default 'timestamp'
+     */
+    format?: VersionFormat;
+    /**
+     * 自定义格式模板，仅当 format 为 'custom' 时有效
+     *
+     * @description 支持以下占位符：
+     * - {YYYY}: 四位年份
+     * - {MM}: 两位月份
+     * - {DD}: 两位日期
+     * - {HH}: 两位小时
+     * - {mm}: 两位分钟
+     * - {ss}: 两位秒数
+     * - {timestamp}: 时间戳
+     * - {hash}: 随机哈希
+     * - {major}: 主版本号（需配合 semverBase）
+     * - {minor}: 次版本号（需配合 semverBase）
+     * - {patch}: 补丁版本号（需配合 semverBase）
+     *
+     * @example '{YYYY}.{MM}.{DD}-{hash}'
+     */
+    customFormat?: string;
+    /**
+     * 语义化版本基础值，用于 semver 格式
+     *
+     * @default '1.0.0'
+     */
+    semverBase?: string;
+    /**
+     * 输出类型
+     *
+     * @default 'file'
+     */
+    outputType?: OutputType;
+    /**
+     * 输出文件路径（相对于构建输出目录）
+     *
+     * @default 'version.json'
+     */
+    outputFile?: string;
+    /**
+     * 注入到代码中的全局变量名
+     *
+     * @default '__APP_VERSION__'
+     */
+    defineName?: string;
+    /**
+     * 哈希长度
+     *
+     * @default 8
+     */
+    hashLength?: number;
+    /**
+     * 版本号前缀
+     *
+     * @example 'v'
+     */
+    prefix?: string;
+    /**
+     * 版本号后缀
+     *
+     * @example '-beta'
+     */
+    suffix?: string;
+    /**
+     * 额外的版本信息，会包含在输出的 JSON 文件中
+     */
+    extra?: Record<string, any>;
+}
+
+/**
+ * 自动生成版本号插件
+ *
+ * @param {GenerateVersionOptions} options - 插件配置选项
+ * @returns {Plugin} 一个 Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // 基本使用 - 时间戳格式
+ * generateVersion()
+ *
+ * // 日期格式
+ * generateVersion({
+ *   format: 'date'
+ * })
+ *
+ * // 语义化版本格式
+ * generateVersion({
+ *   format: 'semver',
+ *   semverBase: '2.0.0',
+ *   prefix: 'v'
+ * })
+ *
+ * // 自定义格式
+ * generateVersion({
+ *   format: 'custom',
+ *   customFormat: '{YYYY}.{MM}.{DD}-{hash}',
+ *   hashLength: 6
+ * })
+ *
+ * // 注入到代码中
+ * generateVersion({
+ *   outputType: 'define',
+ *   defineName: '__VERSION__'
+ * })
+ *
+ * // 同时输出文件和注入代码
+ * generateVersion({
+ *   outputType: 'both',
+ *   outputFile: 'build-info.json',
+ *   defineName: '__BUILD_VERSION__',
+ *   extra: {
+ *     environment: 'production',
+ *     author: 'MengXi Studio'
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * 该插件会在 Vite 构建过程中自动生成版本号，支持多种格式：
+ * - timestamp: 时间戳格式 (20260203153000)
+ * - date: 日期格式 (2026.02.03)
+ * - datetime: 日期时间格式 (2026.02.03.153000)
+ * - semver: 语义化版本格式 (1.0.0)
+ * - hash: 随机哈希格式 (a1b2c3d4)
+ * - custom: 自定义格式
+ */
+declare const generateVersion: PluginFactory<GenerateVersionOptions, GenerateVersionOptions>;
+
+export { generateVersion };
+export type { GenerateVersionOptions, OutputType, VersionFormat, VersionInfo };

package/dist/plugins/generateVersion/index.mjs

@@ -0,0 +1 @@
+import{createPluginFactory as n,BasePlugin as r}from"../../factory/index.mjs";import{getDateFormatParams as a,generateRandomHash as u,parseTemplate as m}from"../../common/format/index.mjs";import{writeFileContent as h}from"../../common/fs/index.mjs";import{join as p}from"path";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"../../shared/vite-plugin.DcExl6jd.mjs";import"crypto";import"fs";class f extends r{version="";buildTime=new Date;getDefaultOptions(){return{format:"timestamp",semverBase:"1.0.0",outputType:"file",outputFile:"version.json",defineName:"__APP_VERSION__",hashLength:8,prefix:"",suffix:""}}validateOptions(){if(this.validator.field("format").enum(["timestamp","date","datetime","semver","hash","custom"]).field("outputType").enum(["file","define","both"]).field("hashLength").number().minValue(1).maxValue(32).validate(),this.options.format==="custom"&&!this.options.customFormat)throw new Error("\u5F53 format \u4E3A custom \u65F6\uFF0C\u5FC5\u987B\u63D0\u4F9B customFormat")}getPluginName(){return"generate-version"}generateVersion(){const t=a(this.buildTime),e=u(this.options.hashLength);let i;switch(this.options.format){case"timestamp":i=`${t.YYYY}${t.MM}${t.DD}${t.HH}${t.mm}${t.ss}`;break;case"date":i=`${t.YYYY}.${t.MM}.${t.DD}`;break;case"datetime":i=`${t.YYYY}.${t.MM}.${t.DD}.${t.HH}${t.mm}${t.ss}`;break;case"semver":i=this.options.semverBase||"1.0.0";break;case"hash":i=e;break;case"custom":i=this.parseCustomFormat({...t,hash:e});break;default:i=t.timestamp}const s=this.options.prefix||"",o=this.options.suffix||"";return`${s}${i}${o}`}parseCustomFormat(t){const e={...t};if(this.options.semverBase){const[i,s,o]=this.options.semverBase.split(".");e.major=i||"1",e.minor=s||"0",e.patch=o||"0"}return m(this.options.customFormat||"",e)}generateVersionInfo(){return{version:this.version,buildTime:this.buildTime.toISOString(),timestamp:this.buildTime.getTime(),format:this.options.format,...this.options.extra}}async writeVersionFile(t){const e=p(t,this.options.outputFile||"version.json"),i=this.generateVersionInfo();await h(e,JSON.stringify(i,null,2)),this.logger.success(`\u7248\u672C\u6587\u4EF6\u5DF2\u751F\u6210: ${e}`)}addPluginHooks(t){t.configResolved=()=>{this.buildTime=new Date,this.version=this.generateVersion(),this.logger.info(`\u751F\u6210\u7248\u672C\u53F7: ${this.version}`)},(this.options.outputType==="define"||this.options.outputType==="both")&&(t.config=()=>{this.version||(this.buildTime=new Date,this.version=this.generateVersion());const e=this.options.defineName||"__APP_VERSION__";return this.logger.info(`\u6CE8\u5165\u5168\u5C40\u53D8\u91CF: ${e} = "${this.version}"`),{define:{[e]:JSON.stringify(this.version),[`${e}_INFO`]:JSON.stringify(this.generateVersionInfo())}}}),(this.options.outputType==="file"||this.options.outputType==="both")&&(t.writeBundle=async()=>{this.viteConfig&&await this.safeExecute(async()=>{const e=this.viteConfig.build.outDir;await this.writeVersionFile(e)},"\u5199\u5165\u7248\u672C\u6587\u4EF6")})}}const l=n(f);export{l as generateVersion};

package/dist/plugins/htmlInject/index.cjs

@@ -0,0 +1,7 @@
+"use strict";const factory_index=require("../../factory/index.cjs"),common_script_index=require("../../common/script/index.cjs"),o=require("node:path");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs");function _interopDefaultCompat(e){return e&&typeof e=="object"&&"default"in e?e.default:e}const o__default=_interopDefaultCompat(o),g$1=["script","iframe","object","embed","applet","form","input","textarea","select","button"],b=["onclick","ondblclick","onmouseover","onmouseout","onmousemove","onmousedown","onmouseup","onkeydown","onkeyup","onkeypress","onload","onerror","onfocus","onblur","onsubmit","onchange","oninput","oncontextmenu","ondrag","ondrop","onanimationend","ontransitionend"];function validateRules(e){if(!e.rules||!Array.isArray(e.rules))throw new Error("rules \u5FC5\u987B\u662F\u975E\u7A7A\u6570\u7EC4");if(e.rules.length===0)throw new Error("rules \u4E0D\u80FD\u4E3A\u7A7A\u6570\u7EC4");for(let t=0;t<e.rules.length;t++)m(e.rules[t],t)}function m(e,t){if(!e.content||typeof e.content!="string")throw new Error(`rules[${t}].content \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);if(!e.position||typeof e.position!="string")throw new Error(`rules[${t}].position \u5FC5\u987B\u662F\u6709\u6548\u7684\u6CE8\u5165\u4F4D\u7F6E`);const n=["head-start","head-end","body-start","body-end","before-selector","after-selector","replace-selector"];if(!n.includes(e.position))throw new Error(`rules[${t}].position \u5FC5\u987B\u662F ${n.join(", ")} \u4E4B\u4E00`);if(e.position.includes("selector")&&!e.selector)throw new Error(`rules[${t}].position \u4E3A "${e.position}" \u65F6\uFF0Cselector \u4E3A\u5FC5\u586B\u9879`);if(e.priority!==void 0&&(typeof e.priority!="number"||e.priority<0))throw new Error(`rules[${t}].priority \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);e.condition&&y(e.condition,t)}function y(e,t){if(!e)return;const n=["env","file-contains","custom"];if(!n.includes(e.type))throw new Error(`rules[${t}].condition.type \u5FC5\u987B\u662F ${n.join(", ")} \u4E4B\u4E00`);if(e.type==="custom"&&typeof e.value!="function")throw new Error(`rules[${t}].condition.type \u4E3A "custom" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u51FD\u6570`);if(e.type!=="custom"&&typeof e.value!="string")throw new Error(`rules[${t}].condition.type \u4E3A "${e.type}" \u65F6\uFF0Cvalue \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`)}function validateSecurityConfig(e){if(e){if(e.blockedTags&&!Array.isArray(e.blockedTags))throw new Error("security.blockedTags \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4");if(e.allowedTags&&!Array.isArray(e.allowedTags))throw new Error("security.allowedTags \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4");if(e.blockedAttributes&&!Array.isArray(e.blockedAttributes))throw new Error("security.blockedAttributes \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4")}}function validateAll(e){validateRules(e),validateSecurityConfig(e.security)}function sanitizeContent(e,t,n,i){const c=n?.blockDangerousTags!==!1,r=n?.blockDangerousAttributes!==!1,s=n?.blockedTags||g$1,f=n?.allowedTags,a=n?.blockedAttributes||b;let l=e;if(c){const E=f?s.filter(d=>!f.includes(d)):s;if(common_script_index.containsScriptTag(e))if(t.allowScriptInjection)i?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5DF2\u542F\u7528\u811A\u672C\u6CE8\u5165(allowScriptInjection=true)\uFF0C\u8BF7\u786E\u4FDD\u6CE8\u5165\u5185\u5BB9\u6765\u6E90\u53EF\u4FE1\u3002\u6CE8\u5165\u811A\u672C\u53EF\u80FD\u5E26\u6765 XSS \u653B\u51FB\u98CE\u9669\u3002`);else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B <script> \u6807\u7B7E\uFF0C\u9ED8\u8BA4\u88AB\u963B\u6B62\u3002\u5982\u9700\u6CE8\u5165\u811A\u672C\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true`);for(const d of E){if(d==="script")continue;const F=new RegExp(`<${d}\\b[^>]*>[\\s\\S]*?<\\/${d}>`,"gi"),h=new RegExp(`<${d}\\b[^>]*/?>`,"gi");if(F.test(l)||h.test(l))if(t.allowScriptInjection){i?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5305\u542B\u88AB\u963B\u6B62\u7684\u6807\u7B7E <${d}>\uFF0C\u5DF2\u901A\u8FC7 allowScriptInjection \u8DF3\u8FC7\u5B89\u5168\u68C0\u67E5\uFF0C\u8BF7\u786E\u4FDD\u5185\u5BB9\u53EF\u4FE1\u3002`);continue}else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B\u88AB\u963B\u6B62\u7684\u6807\u7B7E <${d}>\u3002\u5982\u9700\u6CE8\u5165\u6B64\u6807\u7B7E\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true \u6216\u5728 security.allowedTags \u4E2D\u6DFB\u52A0 "${d}"`);l=l.replace(F,""),l=l.replace(h,"")}}if(r)for(const E of a){const d=new RegExp(`\\s${E}\\s*=\\s*["'][^"']*["']`,"gi");if(d.test(l))if(t.allowScriptInjection){i?.warn(`[\u5B89\u5168\u8B66\u544A] \u89C4\u5219 "${t.id||"unnamed"}" \u5305\u542B\u5371\u9669\u5C5E\u6027 ${E}\uFF0C\u5DF2\u901A\u8FC7 allowScriptInjection \u8DF3\u8FC7\u5B89\u5168\u68C0\u67E5\uFF0C\u8BF7\u786E\u4FDD\u5185\u5BB9\u53EF\u4FE1\u3002`);continue}else throw new Error(`\u89C4\u5219 "${t.id||"unnamed"}" \u7684\u5185\u5BB9\u5305\u542B\u5371\u9669\u5C5E\u6027 ${E}\u3002\u5982\u9700\u6CE8\u5165\u6B64\u5C5E\u6027\uFF0C\u8BF7\u8BBE\u7F6E allowScriptInjection: true`);l=l.replace(d,"")}return l}function g(e,t,n){if(n==="regex"){try{const c=new RegExp(t),r=e.match(c);if(r&&r.index!==void 0)return{index:r.index,length:r[0].length}}catch{return null}return null}const i=e.indexOf(t);return i===-1?null:{index:i,length:t.length}}function applyTemplateVars(e,t,n){let i=e;const c={...n,...t};for(const[r,s]of Object.entries(c)){const f=r.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),a=s.replace(/\$/g,"$$$$");i=i.replace(new RegExp(`\\{\\{${f}\\}\\}`,"g"),a)}return i}function evaluateCondition(e,t){let n=!1;switch(e.type){case"env":{const i=e.value,c=process.env[i];n=!!c&&c!=="false"&&c!=="0";break}case"file-contains":{const i=e.value;n=t.includes(i);break}case"custom":{const i=e.value;try{n=!!i()}catch{n=!1}break}}return e.negate?!n:n}function sortRulesByPriority(e){return[...e].sort((t,n)=>(t.priority??100)-(n.priority??100))}function injectAtPosition(e,t,n,i,c){switch(n){case"head-start":{const r=e.match(/<head\b[^>]*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 <head> \u6807\u7B7E"};const s=(r.index??0)+r[0].length;return{html:e.slice(0,s)+`
+`+t+e.slice(s),injected:!0}}case"head-end":{const r=e.match(/<\/head\s*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 </head> \u6807\u7B7E"};const s=r.index;return{html:e.slice(0,s)+t+`
+`+e.slice(s),injected:!0}}case"body-start":{const r=e.match(/<body\b[^>]*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 <body> \u6807\u7B7E"};const s=(r.index??0)+r[0].length;return{html:e.slice(0,s)+`
+`+t+e.slice(s),injected:!0}}case"body-end":{const r=e.match(/<\/body\s*>/i);if(!r)return{html:e,injected:!1,reason:"\u672A\u627E\u5230 </body> \u6807\u7B7E"};const s=r.index;return{html:e.slice(0,s)+t+`
+`+e.slice(s),injected:!0}}case"before-selector":{if(!i)return{html:e,injected:!1,reason:"before-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,i,c);return r?{html:e.slice(0,r.index)+t+`
+`+e.slice(r.index),injected:!0}:{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${i}"`}}case"after-selector":{if(!i)return{html:e,injected:!1,reason:"after-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,i,c);if(!r)return{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${i}"`};const s=r.index+r.length;return{html:e.slice(0,s)+`
+`+t+e.slice(s),injected:!0}}case"replace-selector":{if(!i)return{html:e,injected:!1,reason:"replace-selector \u9700\u8981 selector \u53C2\u6570"};const r=g(e,i,c);if(!r)return{html:e,injected:!1,reason:`\u672A\u627E\u5230\u9009\u62E9\u5668 "${i}"`};const s=r.index+r.length;return{html:e.slice(0,r.index)+t+e.slice(s),injected:!0}}default:return{html:e,injected:!1,reason:`\u4E0D\u652F\u6301\u7684\u6CE8\u5165\u4F4D\u7F6E: ${n}`}}}function processRules(e,t,n,i,c){let r=e;const s=[],f=sortRulesByPriority(t);for(const a of f){const l={ruleId:a.id||"unnamed",position:a.position,selector:a.selector,injected:!1,timestamp:Date.now()};if(a.condition&&!evaluateCondition(a.condition,r)){l.injected=!1,l.reason="\u6761\u4EF6\u4E0D\u6EE1\u8DB3\uFF0C\u8DF3\u8FC7\u6CE8\u5165",s.push(l);continue}let E=applyTemplateVars(a.content,a.templateVars,n);try{E=sanitizeContent(E,a,i,c)}catch(F){l.injected=!1,l.reason=F.message,s.push(l),c?.warn(`\u89C4\u5219 "${a.id||"unnamed"}" \u5B89\u5168\u68C0\u67E5\u5931\u8D25: ${F.message}`);continue}const d=injectAtPosition(r,E,a.position,a.selector,a.selectorMatch);r=d.html,l.injected=d.injected,l.reason=d.reason,s.push(l)}return{html:r,logs:s}}class u extends factory_index.BasePlugin{injectionLogs=[];getDefaultOptions(){return{targetFile:"index.html",logInjection:!0,security:{blockDangerousTags:!0,blockDangerousAttributes:!0}}}validateOptions(){this.validator.field("targetFile").string().field("rules").required().field("logInjection").boolean().validate(),validateAll(this.options)}getPluginName(){return"html-inject"}isTargetFile(t,n){if(n==="index.html")return t.endsWith("index.html")||t.endsWith("index.htm");const i=n.replace(/\\/g,"/"),c=t.replace(/\\/g,"/");return c.endsWith(i)?!0:o__default.basename(c)===o__default.basename(i)}addPluginHooks(t){t.transformIndexHtml={order:"post",handler:(n,i)=>{const c=i.filename||"",r=this.options.targetFile||"index.html";if(!this.isTargetFile(c,r))return n;const s={warn:a=>this.logger.warn(a)},f=processRules(n,this.options.rules,this.options.templateVars,this.options.security,s);return this.injectionLogs=f.logs,this.options.logInjection&&this.logInjectionResults(f.logs),f.html}},t.buildEnd=()=>{this.options.logInjection&&this.injectionLogs.length>0&&this.logger.info(`\u6CE8\u5165\u5B8C\u6210\uFF0C\u5171\u5904\u7406 ${this.injectionLogs.length} \u6761\u89C4\u5219`)}}logInjectionResults(t){for(const n of t)n.injected?this.logger.success(`\u89C4\u5219 "${n.ruleId}" \u6CE8\u5165\u6210\u529F (\u4F4D\u7F6E: ${n.position}${n.selector?`, \u9009\u62E9\u5668: ${n.selector}`:""})`):this.logger.warn(`\u89C4\u5219 "${n.ruleId}" \u6CE8\u5165\u5931\u8D25: ${n.reason||"\u672A\u77E5\u539F\u56E0"}`)}getInjectionLogs(){return[...this.injectionLogs]}}const htmlInject=factory_index.createPluginFactory(u);exports.htmlInject=htmlInject;

package/dist/plugins/htmlInject/index.d.cts

@@ -0,0 +1,278 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.cjs';
+import '../../shared/vite-plugin.DRRlWY8P.cjs';
+
+/**
+ * 选择器匹配模式
+ *
+ * @description
+ * - 'string': 使用字符串精确匹配（默认）
+ * - 'regex': 使用正则表达式匹配，支持更灵活的模式
+ */
+type SelectorMatch = 'string' | 'regex';
+/**
+ * HTML 内容注入位置
+ *
+ * @description
+ * - 'head-start': 注入到 `<head>` 标签开始之后
+ * - 'head-end': 注入到 `</head>` 标签之前
+ * - 'body-start': 注入到 `<body>` 标签开始之后
+ * - 'body-end': 注入到 `</body>` 标签之前
+ * - 'before-selector': 注入到指定选择器之前
+ * - 'after-selector': 注入到指定选择器之后
+ * - 'replace-selector': 替换指定选择器匹配的内容
+ */
+type InjectPosition = 'head-start' | 'head-end' | 'body-start' | 'body-end' | 'before-selector' | 'after-selector' | 'replace-selector';
+/**
+ * 条件类型
+ *
+ * @description
+ * - 'env': 基于环境变量判断
+ * - 'file-contains': 基于 HTML 文件内容判断
+ * - 'custom': 基于自定义函数判断
+ */
+type ConditionType = 'env' | 'file-contains' | 'custom';
+/**
+ * 注入条件接口
+ *
+ * @interface InjectCondition
+ * @description 定义内容注入的触发条件，支持环境变量检测、文件内容检测和自定义函数
+ */
+interface InjectCondition {
+    /**
+     * 条件类型
+     */
+    type: ConditionType;
+    /**
+     * 条件值
+     *
+     * @description
+     * - 当 type 为 'env' 时，为环境变量名（字符串）
+     * - 当 type 为 'file-contains' 时，为要搜索的字符串（字符串）
+     * - 当 type 为 'custom' 时，为返回布尔值的判断函数
+     */
+    value: string | ((...args: any[]) => boolean);
+    /**
+     * 是否对条件结果取反
+     *
+     * @default false
+     */
+    negate?: boolean;
+}
+/**
+ * 注入规则接口
+ *
+ * @interface InjectRule
+ * @description 定义单条 HTML 内容注入规则，包括注入内容、位置、条件、优先级等
+ */
+interface InjectRule {
+    /**
+     * 规则唯一标识符，用于日志记录和调试
+     */
+    id?: string;
+    /**
+     * 要注入的 HTML 内容
+     *
+     * @example '<meta name="description" content="My App">'
+     */
+    content: string;
+    /**
+     * 注入位置
+     */
+    position: InjectPosition;
+    /**
+     * 选择器字符串，当 position 为 selector 相关位置时必填
+     *
+     * @description 当 selectorMatch 为 'string' 时，使用字符串精确匹配；
+     * 当 selectorMatch 为 'regex' 时，使用正则表达式匹配
+     *
+     * @example '<div id="app">'
+     */
+    selector?: string;
+    /**
+     * 选择器匹配模式
+     *
+     * @default 'string'
+     */
+    selectorMatch?: SelectorMatch;
+    /**
+     * 规则优先级，数值越小优先级越高，越先执行
+     *
+     * @default 100
+     */
+    priority?: number;
+    /**
+     * 注入条件，满足条件时才执行注入
+     */
+    condition?: InjectCondition;
+    /**
+     * 规则级模板变量，会覆盖全局模板变量
+     *
+     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
+     *
+     * @example { greeting: 'Hello', name: 'World' }
+     */
+    templateVars?: Record<string, string>;
+    /**
+     * 是否允许注入脚本等危险内容
+     *
+     * @default false
+     * @remarks 启用此选项将跳过安全检查，请确保注入内容来源可信
+     */
+    allowScriptInjection?: boolean;
+}
+/**
+ * 安全配置接口
+ *
+ * @interface SecurityConfig
+ * @description 控制 HTML 注入内容的安全过滤行为，防止 XSS 攻击
+ */
+interface SecurityConfig {
+    /**
+     * 是否阻止危险标签（script、iframe、object 等）
+     *
+     * @default true
+     */
+    blockDangerousTags?: boolean;
+    /**
+     * 是否阻止危险属性（onclick、onload 等事件处理器）
+     *
+     * @default true
+     */
+    blockDangerousAttributes?: boolean;
+    /**
+     * 允许通过的标签白名单，白名单中的标签不会被阻止
+     *
+     * @example ['iframe', 'object']
+     */
+    allowedTags?: string[];
+    /**
+     * 自定义阻止标签列表，覆盖默认阻止列表
+     *
+     * @example ['div', 'span']
+     */
+    blockedTags?: string[];
+    /**
+     * 自定义阻止属性列表，覆盖默认阻止列表
+     *
+     * @example ['data-custom', 'data-track']
+     */
+    blockedAttributes?: string[];
+}
+/**
+ * 注入日志条目接口
+ *
+ * @interface InjectionLogEntry
+ * @description 记录单条注入规则的执行结果，用于调试和问题排查
+ */
+interface InjectionLogEntry {
+    /**
+     * 规则标识符
+     */
+    ruleId: string;
+    /**
+     * 注入位置
+     */
+    position: InjectPosition;
+    /**
+     * 使用的选择器
+     */
+    selector?: string;
+    /**
+     * 是否注入成功
+     */
+    injected: boolean;
+    /**
+     * 注入失败原因
+     */
+    reason?: string;
+    /**
+     * 日志时间戳
+     */
+    timestamp: number;
+}
+/**
+ * HTML 注入插件的配置选项接口
+ *
+ * @interface HtmlInjectOptions
+ * @extends {BasePluginOptions}
+ */
+interface HtmlInjectOptions extends BasePluginOptions {
+    /**
+     * 目标 HTML 文件路径或文件名
+     *
+     * @default 'index.html'
+     * @description 支持相对路径和文件名匹配，默认匹配所有 index.html 文件
+     *
+     * @example 'index.html'
+     * @example 'src/views/home.html'
+     */
+    targetFile?: string;
+    /**
+     * 注入规则数组
+     *
+     * @description 定义要注入的 HTML 内容及其注入位置和条件，规则按 priority 升序执行
+     */
+    rules: InjectRule[];
+    /**
+     * 安全配置
+     *
+     * @description 控制注入内容的安全过滤行为，防止 XSS 攻击
+     */
+    security?: SecurityConfig;
+    /**
+     * 全局模板变量，可被规则级 templateVars 覆盖
+     *
+     * @description 使用 `{{变量名}}` 语法在 content 中引用变量
+     *
+     * @example { appName: 'My App', version: '1.0.0' }
+     */
+    templateVars?: Record<string, string>;
+    /**
+     * 是否在控制台输出注入日志
+     *
+     * @default true
+     */
+    logInjection?: boolean;
+}
+
+/**
+ * HTML 内容注入插件工厂函数
+ *
+ * @description 创建 htmlInject Vite 插件实例，用于在构建过程中将自定义 HTML 内容注入到目标 HTML 文件中
+ *
+ * @param {HtmlInjectOptions} options - 插件配置选项
+ * @returns {Plugin} Vite 插件实例
+ *
+ * @example
+ * ```ts
+ * import { htmlInject } from '@mengxi-studio/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     htmlInject({
+ *       rules: [
+ *         {
+ *           id: 'meta-description',
+ *           content: '<meta name="description" content="{{appName}}">',
+ *           position: 'head-end',
+ *           templateVars: { appName: 'My Application' }
+ *         },
+ *         {
+ *           id: 'analytics',
+ *           content: '<script src="/analytics.js"></script>',
+ *           position: 'body-end',
+ *           condition: { type: 'env', value: 'PRODUCTION' },
+ *           allowScriptInjection: true
+ *         }
+ *       ]
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare const htmlInject: PluginFactory<HtmlInjectOptions, HtmlInjectOptions>;
+
+export { htmlInject };
+export type { ConditionType, HtmlInjectOptions, InjectCondition, InjectPosition, InjectRule, InjectionLogEntry, SecurityConfig, SelectorMatch };