@meng-xi/vite-plugin 0.1.3 → 0.1.5

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

@@ -0,0 +1,255 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.js';
+import 'vite';
+import '../../shared/vite-plugin.B8FuZce1.js';
+import '../../shared/vite-plugin.DRRlWY8P.js';
+
+/**
+ * 环境变量值类型
+ *
+ * @description 定义环境变量支持的所有值类型：
+ * - `string`：普通字符串（默认类型）
+ * - `number`：数字类型
+ * - `url`：URL 地址
+ * - `boolean`：布尔值
+ * - `enum`：枚举值
+ * - `json`：JSON 字符串
+ * - `semver`：语义化版本号
+ * - `path`：文件路径
+ */
+type EnvType = 'string' | 'number' | 'url' | 'boolean' | 'enum' | 'json' | 'semver' | 'path';
+/**
+ * 环境变量字段校验规则
+ *
+ * @description 定义单个环境变量的校验规则，包括类型约束、范围限制、
+ * 自定义验证函数和元数据信息等。
+ *
+ * @example
+ * ```typescript
+ * // 基本字符串字段
+ * const rule: EnvFieldRule = { type: 'string', required: true }
+ *
+ * // 带范围的数字字段
+ * const portRule: EnvFieldRule = { type: 'number', required: true, minValue: 1, maxValue: 65535 }
+ *
+ * // 枚举字段
+ * const envRule: EnvFieldRule = { type: 'enum', required: true, enumValues: ['development', 'staging', 'production'] }
+ *
+ * // 自定义验证
+ * const customRule: EnvFieldRule = {
+ *   type: 'string',
+ *   required: true,
+ *   validator: (v) => v.startsWith('https://') || '必须使用 HTTPS'
+ * }
+ * ```
+ */
+interface EnvFieldRule {
+    /** 值类型，默认为 `'string'` */
+    type?: EnvType;
+    /** 是否为必需字段，默认为 `true` */
+    required?: boolean;
+    /** 正则表达式，值必须匹配此模式 */
+    pattern?: RegExp;
+    /**
+     * 自定义验证函数
+     *
+     * @description 返回 `true` 表示验证通过，返回字符串表示验证失败且字符串为错误消息
+     */
+    validator?: (value: string) => boolean | string;
+    /** 自定义错误消息，覆盖默认的错误提示 */
+    message?: string;
+    /** 当值为空时使用的默认值 */
+    default?: string;
+    /** 枚举值列表（仅 `enum` 类型需要） */
+    enumValues?: string[];
+    /** 数值最小值（仅 `number` 类型） */
+    minValue?: number;
+    /** 数值最大值（仅 `number` 类型） */
+    maxValue?: number;
+    /** 字符串最小长度（仅字符串类类型） */
+    minLength?: number;
+    /** 字符串最大长度（仅字符串类类型） */
+    maxLength?: number;
+    /** 变量分组名称，用于模板生成时的分组显示 */
+    group?: string;
+    /** 变量描述信息，用于模板生成时的说明文本 */
+    description?: string;
+    /** 是否为敏感变量，模板中会隐藏实际值 */
+    sensitive?: boolean;
+}
+/**
+ * 环境变量验证结果
+ *
+ * @description 表示单个环境变量的验证结果，包含验证状态、错误消息和有效值。
+ */
+interface EnvValidationResult {
+    /** 环境变量名 */
+    key: string;
+    /**
+     * 验证状态：
+     * - `pass`：验证通过
+     * - `missing`：必需变量缺失
+     * - `type_error`：类型不匹配
+     * - `custom_error`：自定义验证失败或正则不匹配
+     * - `enum_mismatch`：枚举值不匹配
+     * - `range_error`：数值超出范围
+     * - `length_error`：字符串长度不符合要求
+     */
+    status: 'pass' | 'missing' | 'type_error' | 'custom_error' | 'enum_mismatch' | 'range_error' | 'length_error';
+    /** 验证消息（验证通过时为空字符串，失败时为错误描述） */
+    message: string;
+    /** 环境变量的有效值（缺失时可能为 `undefined` 或默认值） */
+    value: string | undefined;
+    /** 应用的校验规则（含默认值填充后的完整规则） */
+    rule: EnvFieldRule;
+}
+
+/**
+ * 环境变量校验失败时的处理动作
+ *
+ * @description 定义当环境变量校验未通过时的处理策略：
+ * - `error`: 抛出错误，中断构建流程
+ * - `warn`: 输出警告日志，继续构建
+ * - `ignore`: 静默忽略，不输出任何信息
+ */
+type EnvFailAction = 'error' | 'warn' | 'ignore';
+/**
+ * 运行时守卫的行为模式
+ *
+ * @description 定义注入到 HTML 中的运行时守卫代码在检测到
+ * 环境变量缺失或无效时的行为方式：
+ * - `console`: 在浏览器控制台输出警告信息
+ * - `throw`: 抛出运行时错误，阻止应用启动
+ * - `overlay`: 在页面顶部显示警告横幅
+ */
+type RuntimeGuardMode = 'console' | 'throw' | 'overlay';
+/**
+ * 环境变量校验结果汇总
+ *
+ * @interface EnvGuardResult
+ * @description 包含所有环境变量的校验统计信息和详细结果列表，
+ * 用于报告生成和日志输出。
+ */
+interface EnvGuardResult {
+    /** 校验时间戳（ISO 格式） */
+    timestamp: string;
+    /** 校验的环境变量总数 */
+    total: number;
+    /** 校验通过的变量数量 */
+    passed: number;
+    /** 缺失的必需变量数量 */
+    missing: number;
+    /** 校验失败的变量数量（类型不匹配、范围越界等） */
+    invalid: number;
+    /** 所有变量的详细校验结果列表 */
+    results: EnvValidationResult[];
+    /** 是否所有变量均校验通过 */
+    allPassed: boolean;
+}
+/**
+ * 环境变量守卫插件的配置选项
+ *
+ * @interface EnvGuardOptions
+ * @extends {BasePluginOptions}
+ *
+ * @example
+ * ```typescript
+ * envGuard({
+ *   required: {
+ *     VITE_API_URL: { type: 'url', required: true },
+ *     VITE_APP_TITLE: { type: 'string', minLength: 1, maxLength: 50 }
+ *   },
+ *   failAction: 'error',
+ *   generateTemplate: true,
+ *   runtimeGuard: true,
+ *   runtimeGuardMode: 'console'
+ * })
+ * ```
+ */
+interface EnvGuardOptions extends BasePluginOptions {
+    /** 环境变量校验规则映射，键为变量名，值为校验规则 */
+    required?: Record<string, EnvFieldRule>;
+    /** 校验失败时的处理动作 */
+    failAction?: EnvFailAction;
+    /** 是否自动生成 .env 模板文件 */
+    generateTemplate?: boolean;
+    /** .env 模板文件的输出路径 */
+    templateOutput?: string;
+    /** 是否注入运行时环境变量守卫代码到 HTML */
+    runtimeGuard?: boolean;
+    /** 运行时守卫的全局变量名 */
+    runtimeGlobalName?: string;
+    /** 运行时守卫的行为模式 */
+    runtimeGuardMode?: RuntimeGuardMode;
+    /** 需要加载的 .env 文件路径列表 */
+    envFiles?: string[];
+    /** 是否自动加载 .env 文件中的变量到 process.env */
+    autoLoadEnv?: boolean;
+    /** 校验报告输出路径，设为 false 则不生成报告 */
+    reportOutput?: string | false;
+    /** 是否在构建前执行校验 */
+    validateBeforeBuild?: boolean;
+    /** 是否输出校验摘要日志 */
+    showSummary?: boolean;
+}
+
+/**
+ * 创建环境变量守卫插件
+ *
+ * @function envGuard
+ * @param {Partial<EnvGuardOptions>} [options] - 插件配置选项
+ * @returns {Plugin} Vite 插件实例
+ *
+ * @description 在 Vite 构建前校验环境变量的存在性和合法性，
+ * 支持多种值类型校验、正则匹配、自定义校验函数等，
+ * 可选生成 .env 模板文件和注入运行时守卫代码。
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { envGuard } from '@meng-xi/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     envGuard({
+ *       required: {
+ *         VITE_API_BASE_URL: {
+ *           type: 'url',
+ *           required: true,
+ *           message: 'API 基础地址必须为合法 URL'
+ *         },
+ *         VITE_APP_TITLE: {
+ *           type: 'string',
+ *           required: true,
+ *           minLength: 1,
+ *           maxLength: 50
+ *         },
+ *         VITE_ENABLE_ANALYTICS: {
+ *           type: 'boolean',
+ *           required: false,
+ *           default: 'false'
+ *         },
+ *         VITE_API_TIMEOUT: {
+ *           type: 'number',
+ *           minValue: 1000,
+ *           maxValue: 60000,
+ *           message: 'API 超时时间必须在 1000-60000ms 之间'
+ *         },
+ *         VITE_LOG_LEVEL: {
+ *           type: 'enum',
+ *           enumValues: ['debug', 'info', 'warn', 'error'],
+ *           default: 'info'
+ *         }
+ *       },
+ *       failAction: 'error',
+ *       generateTemplate: true,
+ *       runtimeGuard: true,
+ *       runtimeGuardMode: 'console'
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare const envGuard: PluginFactory<EnvGuardOptions, EnvGuardOptions>;
+
+export { envGuard };
+export type { EnvFailAction, EnvGuardOptions, EnvGuardResult, RuntimeGuardMode };

package/dist/plugins/envGuard/index.mjs

@@ -0,0 +1,67 @@
+import{createPluginFactory as v,BasePlugin as F}from"../../factory/index.mjs";import{injectBeforeTag as E}from"../../common/html/index.mjs";import{writeFileContent as g}from"../../common/fs/index.mjs";import{getDateFormatParams as A}from"../../common/format/index.mjs";import m from"node:path";import p from"node:fs";import"../../logger/index.mjs";import"../../shared/vite-plugin.DcExl6jd.mjs";import"../../shared/vite-plugin.BPFqtmWa.mjs";import"fs";import"path";const C=new Set(["string","url","path","enum","semver",void 0]);function D(t,u){switch(u.type){case"number":{if(isNaN(Number(t))||t.trim()==="")return{valid:!1,status:"type_error",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u662F\u5408\u6CD5\u6570\u5B57`};break}case"url":{try{new URL(t)}catch{return{valid:!1,status:"type_error",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u662F\u5408\u6CD5 URL`}}break}case"boolean":{const r=t.toLowerCase();if(!["true","false","1","0","yes","no"].includes(r))return{valid:!1,status:"type_error",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u662F\u5408\u6CD5\u5E03\u5C14\u503C (true/false/1/0/yes/no)`};break}case"enum":{if(!u.enumValues||u.enumValues.length===0)return{valid:!1,status:"enum_mismatch",message:"enum \u7C7B\u578B\u5FC5\u987B\u6307\u5B9A enumValues"};if(!u.enumValues.includes(t))return{valid:!1,status:"enum_mismatch",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u5728\u5141\u8BB8\u7684\u679A\u4E3E\u503C\u4E2D: ${u.enumValues.join(", ")}`};break}case"json":{try{JSON.parse(t)}catch{return{valid:!1,status:"type_error",message:"\u73AF\u5883\u53D8\u91CF\u503C\u4E0D\u662F\u5408\u6CD5 JSON"}}break}case"semver":{if(!/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(t))return{valid:!1,status:"type_error",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u662F\u5408\u6CD5\u8BED\u4E49\u5316\u7248\u672C\u53F7 (x.y.z)`};break}case"path":{if(!/^(?:[./\\]|(?:[a-zA-Z]:))/.test(t))return{valid:!1,status:"type_error",message:`\u73AF\u5883\u53D8\u91CF\u503C "${t}" \u4E0D\u662F\u5408\u6CD5\u6587\u4EF6\u8DEF\u5F84`};break}}return{valid:!0,status:"pass",message:""}}function y(t,u){if(u.type!=="number")return{valid:!0,status:"pass",message:""};const r=Number(t);return u.minValue!==void 0&&r<u.minValue?{valid:!1,status:"range_error",message:`\u6570\u503C ${r} \u5C0F\u4E8E\u6700\u5C0F\u503C ${u.minValue}`}:u.maxValue!==void 0&&r>u.maxValue?{valid:!1,status:"range_error",message:`\u6570\u503C ${r} \u5927\u4E8E\u6700\u5927\u503C ${u.maxValue}`}:{valid:!0,status:"pass",message:""}}function $(t,u){return C.has(u.type)?u.minLength!==void 0&&t.length<u.minLength?{valid:!1,status:"length_error",message:`\u5B57\u7B26\u4E32\u957F\u5EA6 ${t.length} \u5C0F\u4E8E\u6700\u5C0F\u957F\u5EA6 ${u.minLength}`}:u.maxLength!==void 0&&t.length>u.maxLength?{valid:!1,status:"length_error",message:`\u5B57\u7B26\u4E32\u957F\u5EA6 ${t.length} \u5927\u4E8E\u6700\u5927\u957F\u5EA6 ${u.maxLength}`}:{valid:!0,status:"pass",message:""}:{valid:!0,status:"pass",message:""}}function R(t,u,r){const e={type:"string",required:!0,...r};if(u===void 0||u==="")return e.required!==!1?{key:t,status:"missing",message:e.message||`\u7F3A\u5C11\u5FC5\u9700\u7684\u73AF\u5883\u53D8\u91CF: ${t}`,value:u,rule:e}:{key:t,status:"pass",message:"",value:e.default??u,rule:e};const s=D(u,e);if(!s.valid)return{key:t,status:s.status,message:e.message||s.message,value:u,rule:e};const i=y(u,e);if(!i.valid)return{key:t,status:i.status,message:e.message||i.message,value:u,rule:e};const a=$(u,e);if(!a.valid)return{key:t,status:a.status,message:e.message||a.message,value:u,rule:e};if(e.pattern&&!e.pattern.test(u))return{key:t,status:"custom_error",message:e.message||`\u73AF\u5883\u53D8\u91CF ${t} \u4E0D\u5339\u914D\u6B63\u5219: ${e.pattern.source}`,value:u,rule:e};if(e.validator){const n=e.validator(u);if(n!==!0){const l=typeof n=="string"?n:"";return{key:t,status:"custom_error",message:e.message||l||`\u73AF\u5883\u53D8\u91CF ${t} \u81EA\u5B9A\u4E49\u6821\u9A8C\u5931\u8D25`,value:u,rule:e}}}return{key:t,status:"pass",message:"",value:u,rule:e}}function w(t,u){const r=[];for(const[e,s]of Object.entries(u)){const i=t[e];r.push(R(e,i,s))}return r}function _(t){const u=new Map,r=[];for(const[s,i]of Object.entries(t)){const a={type:"string",required:!0,...i};if(a.group){const n=u.get(a.group)||[];n.push({key:s,rule:a}),u.set(a.group,n)}else r.push({key:s,rule:a})}const e=[];e.push("# \u73AF\u5883\u53D8\u91CF\u6A21\u677F\u6587\u4EF6"),e.push(`# \u751F\u6210\u65F6\u95F4: ${new Date().toISOString()}`),e.push("# \u7531 @meng-xi/vite-plugin envGuard \u81EA\u52A8\u751F\u6210"),e.push(""),r.length>0&&h(e,"\u901A\u7528\u914D\u7F6E",r);for(const[s,i]of u)h(e,s,i);return e.join(`
+`)}function h(t,u,r){t.push("# =============================="),t.push(`# ${u}`),t.push("# =============================="),t.push("");for(const{key:e,rule:s}of r){s.description&&t.push(`# ${s.description}`);const i=[];i.push(`\u7C7B\u578B: ${s.type||"string"}`),i.push(s.required!==!1?"\u5FC5\u9700":"\u53EF\u9009"),s.enumValues&&s.enumValues.length>0&&i.push(`\u679A\u4E3E\u503C: ${s.enumValues.join(" | ")}`),s.minValue!==void 0&&i.push(`\u6700\u5C0F\u503C: ${s.minValue}`),s.maxValue!==void 0&&i.push(`\u6700\u5927\u503C: ${s.maxValue}`),s.minLength!==void 0&&i.push(`\u6700\u5C0F\u957F\u5EA6: ${s.minLength}`),s.maxLength!==void 0&&i.push(`\u6700\u5927\u957F\u5EA6: ${s.maxLength}`),s.sensitive&&i.push("\u26A0\uFE0F \u654F\u611F\u4FE1\u606F"),t.push(`# [${i.join(" | ")}]`),s.default!==void 0?t.push(`${e}=${s.sensitive?"********":s.default}`):t.push(`${e}=`),t.push("")}}function b(t,u,r,e){const s=[];for(const[o,d]of Object.entries(t))d.required!==!1&&s.push({key:o,rule:{type:"string",required:!0,...d}});if(s.length===0)return"";const i=e.filter(o=>o.status!=="pass"),a=s.map(({key:o,rule:d})=>({key:o,type:d.type||"string",description:d.description||""})),n=JSON.stringify(a,null,2),l=i.map(o=>o.key),f=JSON.stringify(l),c=k(r);return`<script>
+${`
+(function() {
+  'use strict';
+  var GUARD_NAME = ${JSON.stringify(u)};
+  var GUARD_DATA = ${n};
+  var FAILED_KEYS = ${f};
+  var MODE = ${JSON.stringify(r)};
+
+  var missing = [];
+  var invalid = [];
+
+  for (var i = 0; i < GUARD_DATA.length; i++) {
+    var item = GUARD_DATA[i];
+    var el = document.querySelector('meta[name="env:' + item.key + '"]');
+    if (!el) {
+      var attr = document.querySelector('[' + item.key + ']');
+      if (!attr) {
+        missing.push(item.key);
+      }
+    }
+  }
+
+  for (var j = 0; j < FAILED_KEYS.length; j++) {
+    if (invalid.indexOf(FAILED_KEYS[j]) === -1 && missing.indexOf(FAILED_KEYS[j]) === -1) {
+      invalid.push(FAILED_KEYS[j]);
+    }
+  }
+
+  var hasIssues = missing.length > 0 || invalid.length > 0;
+
+  var guard = {
+    missing: missing,
+    invalid: invalid,
+    allPassed: !hasIssues,
+    data: GUARD_DATA
+  };
+
+  if (typeof window !== 'undefined') {
+    window[GUARD_NAME] = guard;
+  }
+
+  if (hasIssues) {
+    ${c}
+  }
+})();
+`.trim()}
+<\/script>`}function k(t){switch(t){case"console":return`
+    var msgs = [];
+    if (missing.length > 0) msgs.push('[EnvGuard] \u7F3A\u5C11\u73AF\u5883\u53D8\u91CF: ' + missing.join(', '));
+    if (invalid.length > 0) msgs.push('[EnvGuard] \u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u5931\u8D25: ' + invalid.join(', '));
+    for (var k = 0; k < msgs.length; k++) console.warn(msgs[k]);`;case"throw":return`
+    var errMsg = '';
+    if (missing.length > 0) errMsg += '\u7F3A\u5C11\u73AF\u5883\u53D8\u91CF: ' + missing.join(', ') + '; ';
+    if (invalid.length > 0) errMsg += '\u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u5931\u8D25: ' + invalid.join(', ');
+    throw new Error('[EnvGuard] ' + errMsg);`;case"overlay":return`
+    var overlay = document.createElement('div');
+    overlay.id = '__env_guard_overlay__';
+    overlay.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:99999;background:#fff3cd;color:#856404;padding:12px 20px;font-size:14px;font-family:monospace;border-bottom:3px solid #ffc107;box-shadow:0 2px 8px rgba(0,0,0,0.15);';
+    var html = '<strong>\u26A0\uFE0F EnvGuard \u8B66\u544A</strong><br>';
+    if (missing.length > 0) html += '\u7F3A\u5C11: ' + missing.join(', ') + '<br>';
+    if (invalid.length > 0) html += '\u6821\u9A8C\u5931\u8D25: ' + invalid.join(', ');
+    overlay.innerHTML = html;
+    document.addEventListener('DOMContentLoaded', function() { document.body.appendChild(overlay); });`;default:return""}}function B(t,u){const r=A(t);let e=u;for(const[s,i]of Object.entries(r))e=e.replace(new RegExp(`\\{${s}\\}`,"g"),i);return e}class x extends F{validationResults=[];guardResult=null;getDefaultOptions(){return{required:{},failAction:"error",generateTemplate:!0,templateOutput:".env.template",runtimeGuard:!1,runtimeGlobalName:"__ENV_GUARD__",runtimeGuardMode:"console",envFiles:[".env",".env.local",".env.production",".env.development"],autoLoadEnv:!0,reportOutput:!1,validateBeforeBuild:!0,showSummary:!0}}validateOptions(){this.validator.field("failAction").enum(["error","warn","ignore"]).field("generateTemplate").boolean().field("runtimeGuard").boolean().field("runtimeGuardMode").enum(["console","throw","overlay"]).field("autoLoadEnv").boolean().field("reportOutput").custom(u=>u===!1||typeof u=="string","reportOutput \u5FC5\u987B\u4E3A false \u6216\u5B57\u7B26\u4E32\u8DEF\u5F84").field("validateBeforeBuild").boolean().field("showSummary").boolean().validate()}getPluginName(){return"env-guard"}addPluginHooks(u){this.options.validateBeforeBuild&&(u.configResolved=r=>{this.viteConfig=r,this.runValidation()}),this.options.runtimeGuard&&(u.transformIndexHtml={order:"post",handler:r=>this.safeExecuteSync(()=>this.injectRuntimeGuard(r),"\u6CE8\u5165\u8FD0\u884C\u65F6\u5B88\u536B")||r})}runValidation(){this.options.autoLoadEnv&&this.loadEnvFiles(),this.validationResults=w(process.env,this.options.required),this.guardResult=this.buildResult(),this.options.generateTemplate&&this.writeEnvTemplate(),this.options.reportOutput&&this.writeReport(),this.options.showSummary&&this.logSummary(),this.handleResults()}loadEnvFiles(){if(!this.viteConfig)return;const u=this.viteConfig.root||process.cwd();for(const r of this.options.envFiles){const e=m.resolve(u,r);if(p.existsSync(e))try{this.parseAndLoadEnvFile(e)}catch{this.logger.warn(`\u52A0\u8F7D .env \u6587\u4EF6\u5931\u8D25: ${e}`)}}}parseAndLoadEnvFile(u){const r=p.readFileSync(u,"utf-8").split(`
+`);for(const e of r){const s=e.trim();if(!s||s.startsWith("#"))continue;const i=s.indexOf("=");if(i===-1)continue;const a=s.slice(0,i).trim();let n=s.slice(i+1).trim();(n.startsWith('"')&&n.endsWith('"')||n.startsWith("'")&&n.endsWith("'"))&&(n=n.slice(1,-1)),a.startsWith("VITE_")&&process.env[a]===void 0&&(process.env[a]=n)}}buildResult(){const u=this.validationResults.length,r=this.validationResults.filter(i=>i.status==="pass").length,e=this.validationResults.filter(i=>i.status==="missing").length,s=this.validationResults.filter(i=>i.status!=="pass"&&i.status!=="missing").length;return{timestamp:B(new Date,"{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"),total:u,passed:r,missing:e,invalid:s,results:this.validationResults,allPassed:e===0&&s===0}}handleResults(){if(!this.guardResult||this.guardResult.allPassed)return;const u=this.validationResults.filter(i=>i.status==="missing").map(i=>i.key),r=this.validationResults.filter(i=>i.status!=="pass"&&i.status!=="missing"),e=[];u.length>0&&e.push(`\u7F3A\u5C11\u5FC5\u9700\u7684\u73AF\u5883\u53D8\u91CF: ${u.join(", ")}`);for(const i of r)e.push(`${i.key}: ${i.message}`);const s=e.join(`
+  `);switch(this.options.failAction){case"error":throw new Error(s);case"warn":this.logger.warn(s);break}}writeEnvTemplate(){const u=this.viteConfig?.root||process.cwd(),r=m.resolve(u,this.options.templateOutput),e=_(this.options.required);this.safeExecuteSync(()=>{g(r,e),this.logger.info(`\u73AF\u5883\u53D8\u91CF\u6A21\u677F\u5DF2\u751F\u6210: ${this.options.templateOutput}`)},"\u751F\u6210 .env \u6A21\u677F")}writeReport(){if(!this.guardResult||!this.options.reportOutput)return;const u=this.viteConfig?.build?.outDir||"dist",r=m.resolve(u,this.options.reportOutput);this.safeExecuteSync(()=>{const e=JSON.stringify(this.guardResult,(s,i)=>i instanceof RegExp?i.toString():typeof i=="function"?"[Function]":i,2);g(r,e),this.logger.info(`\u6821\u9A8C\u62A5\u544A\u5DF2\u751F\u6210: ${this.options.reportOutput}`)},"\u751F\u6210\u6821\u9A8C\u62A5\u544A")}logSummary(){if(!this.guardResult)return;const{total:u,passed:r,missing:e,invalid:s,allPassed:i}=this.guardResult;if(i){this.logger.success(`\u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u901A\u8FC7: ${u} \u4E2A\u53D8\u91CF\u5168\u90E8\u5408\u6CD5`);return}this.logger.info(`\u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u7ED3\u679C: \u603B\u8BA1 ${u} | \u901A\u8FC7 ${r} | \u7F3A\u5931 ${e} | \u5931\u8D25 ${s}`);const a=this.validationResults.filter(n=>n.status!=="pass");for(const n of a){const l=n.status==="missing"?"\u7F3A\u5931":"\u5931\u8D25";this.logger.warn(`  [${l}] ${n.key}: ${n.message}`)}}injectRuntimeGuard(u){const r=b(this.options.required,this.options.runtimeGlobalName,this.options.runtimeGuardMode,this.validationResults);if(!r)return u;const e=E(u,"</head>",r);return e.injected?e.html:(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8FD0\u884C\u65F6\u5B88\u536B\u4EE3\u7801\u672A\u80FD\u6CE8\u5165"),u)}getResult(){return this.guardResult}getValidationResults(){return[...this.validationResults]}}const O=v(x);export{O as envGuard};

package/dist/plugins/faviconManager/index.cjs

@@ -1 +1 @@
-"use strict";const factory_index=require("../../factory/index.cjs"),common_fs_index=require("../../common/fs/index.cjs"),validator=require("../../shared/vite-plugin.Bcg6RW2N.cjs"),common_html_index=require("../../common/html/index.cjs");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("fs"),require("path");function generateIconTagDescriptors(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class f extends factory_index.BasePlugin{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new validator.Validator(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=generateIconTagDescriptors(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=common_html_index.injectBeforeTag(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:r=!0,recursive:n=!0}=i;await common_fs_index.checkSourceExists(e);const s=await common_fs_index.copySourceToTarget(e,t,{recursive:n,overwrite:r,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${s.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${s.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${s.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const faviconManager=factory_index.createPluginFactory(f,u=>typeof u=="string"?{base:u}:u||{});exports.faviconManager=faviconManager;
+"use strict";const factory_index=require("../../factory/index.cjs"),common_fs_index=require("../../common/fs/index.cjs"),validator=require("../../shared/vite-plugin.Bcg6RW2N.cjs"),common_html_index=require("../../common/html/index.cjs");require("../../logger/index.cjs"),require("fs"),require("path"),require("../../shared/vite-plugin.CnOy46d3.cjs");function generateIconTagDescriptors(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class f extends factory_index.BasePlugin{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new validator.Validator(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=generateIconTagDescriptors(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=common_html_index.injectBeforeTag(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:r=!0,recursive:n=!0}=i;await common_fs_index.checkSourceExists(e);const s=await common_fs_index.copySourceToTarget(e,t,{recursive:n,overwrite:r,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${s.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${s.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${s.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const faviconManager=factory_index.createPluginFactory(f,u=>typeof u=="string"?{base:u}:u||{});exports.faviconManager=faviconManager;

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

@@ -1,28 +1,42 @@
 import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
 import 'vite';
-import '../../shared/vite-plugin.CLr0ttuO.cjs';
+import '../../shared/vite-plugin.B8FuZce1.cjs';
 import '../../shared/vite-plugin.DRRlWY8P.cjs';
 
 /**
  * 图标配置项接口
  *
  * @interface Icon
+ * @description 定义单个网站图标的属性，对应 HTML `<link>` 标签的各个属性。
  */
 interface Icon {
     /**
-     * 图标关系类型
+     * 图标关系类型，对应 `<link>` 标签的 `rel` 属性
+     *
+     * @example 'icon'
+     * @example 'apple-touch-icon'
+     * @example 'manifest'
      */
     rel: string;
     /**
-     * 图标 URL
+     * 图标 URL，对应 `<link>` 标签的 `href` 属性
+     *
+     * @example '/favicon.ico'
+     * @example '/apple-touch-icon.png'
      */
     href: string;
     /**
-     * 图标尺寸
+     * 图标尺寸，对应 `<link>` 标签的 `sizes` 属性
+     *
+     * @example '32x32'
+     * @example '180x180'
      */
     sizes?: string;
     /**
-     * 图标 MIME 类型
+     * 图标 MIME 类型，对应 `<link>` 标签的 `type` 属性
+     *
+     * @example 'image/png'
+     * @example 'image/svg+xml'
      */
     type?: string;
 }
@@ -30,6 +44,8 @@ interface Icon {
  * 图标文件复制配置选项接口
  *
  * @interface CopyOptions
+ * @description 配置图标文件从源目录到构建输出目录的复制行为，
+ * 仅当此对象存在时才开启图标文件复制功能。
  */
 interface CopyOptions {
     /**
@@ -51,7 +67,7 @@ interface CopyOptions {
      */
     overwrite?: boolean;
     /**
-     * 是否支持递归复制
+     * 是否支持递归复制子目录
      *
      * @default true
      */
@@ -61,6 +77,28 @@ interface CopyOptions {
  * 网站图标管理插件的配置选项接口
  *
  * @interface FaviconManagerOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 支持三种图标配置方式（优先级从高到低）：
+ * 1. `link` - 自定义完整的 `<link>` 标签 HTML
+ * 2. `url` - 完整的图标 URL
+ * 3. `base` + 默认 favicon.ico - 基础路径拼接
+ * 此外还支持通过 `icons` 数组配置多个图标，以及通过 `copyOptions` 复制图标文件。
+ *
+ * @example
+ * ```typescript
+ * faviconManager({
+ *   base: '/assets',
+ *   icons: [
+ *     { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
+ *     { rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
+ *   ],
+ *   copyOptions: {
+ *     sourceDir: 'src/assets/icons',
+ *     targetDir: 'dist/assets/icons'
+ *   }
+ * })
+ * ```
  */
 interface FaviconManagerOptions extends BasePluginOptions {
     /**

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

@@ -1,28 +1,42 @@
 import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
 import 'vite';
-import '../../shared/vite-plugin.CLr0ttuO.mjs';
+import '../../shared/vite-plugin.B8FuZce1.mjs';
 import '../../shared/vite-plugin.DRRlWY8P.mjs';
 
 /**
  * 图标配置项接口
  *
  * @interface Icon
+ * @description 定义单个网站图标的属性，对应 HTML `<link>` 标签的各个属性。
  */
 interface Icon {
     /**
-     * 图标关系类型
+     * 图标关系类型，对应 `<link>` 标签的 `rel` 属性
+     *
+     * @example 'icon'
+     * @example 'apple-touch-icon'
+     * @example 'manifest'
      */
     rel: string;
     /**
-     * 图标 URL
+     * 图标 URL，对应 `<link>` 标签的 `href` 属性
+     *
+     * @example '/favicon.ico'
+     * @example '/apple-touch-icon.png'
      */
     href: string;
     /**
-     * 图标尺寸
+     * 图标尺寸，对应 `<link>` 标签的 `sizes` 属性
+     *
+     * @example '32x32'
+     * @example '180x180'
      */
     sizes?: string;
     /**
-     * 图标 MIME 类型
+     * 图标 MIME 类型，对应 `<link>` 标签的 `type` 属性
+     *
+     * @example 'image/png'
+     * @example 'image/svg+xml'
      */
     type?: string;
 }
@@ -30,6 +44,8 @@ interface Icon {
  * 图标文件复制配置选项接口
  *
  * @interface CopyOptions
+ * @description 配置图标文件从源目录到构建输出目录的复制行为，
+ * 仅当此对象存在时才开启图标文件复制功能。
  */
 interface CopyOptions {
     /**
@@ -51,7 +67,7 @@ interface CopyOptions {
      */
     overwrite?: boolean;
     /**
-     * 是否支持递归复制
+     * 是否支持递归复制子目录
      *
      * @default true
      */
@@ -61,6 +77,28 @@ interface CopyOptions {
  * 网站图标管理插件的配置选项接口
  *
  * @interface FaviconManagerOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 支持三种图标配置方式（优先级从高到低）：
+ * 1. `link` - 自定义完整的 `<link>` 标签 HTML
+ * 2. `url` - 完整的图标 URL
+ * 3. `base` + 默认 favicon.ico - 基础路径拼接
+ * 此外还支持通过 `icons` 数组配置多个图标，以及通过 `copyOptions` 复制图标文件。
+ *
+ * @example
+ * ```typescript
+ * faviconManager({
+ *   base: '/assets',
+ *   icons: [
+ *     { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
+ *     { rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
+ *   ],
+ *   copyOptions: {
+ *     sourceDir: 'src/assets/icons',
+ *     targetDir: 'dist/assets/icons'
+ *   }
+ * })
+ * ```
  */
 interface FaviconManagerOptions extends BasePluginOptions {
     /**

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

@@ -1,28 +1,42 @@
 import { BasePluginOptions, PluginFactory } from '../../factory/index.js';
 import 'vite';
-import '../../shared/vite-plugin.CLr0ttuO.js';
+import '../../shared/vite-plugin.B8FuZce1.js';
 import '../../shared/vite-plugin.DRRlWY8P.js';
 
 /**
  * 图标配置项接口
  *
  * @interface Icon
+ * @description 定义单个网站图标的属性，对应 HTML `<link>` 标签的各个属性。
  */
 interface Icon {
     /**
-     * 图标关系类型
+     * 图标关系类型，对应 `<link>` 标签的 `rel` 属性
+     *
+     * @example 'icon'
+     * @example 'apple-touch-icon'
+     * @example 'manifest'
      */
     rel: string;
     /**
-     * 图标 URL
+     * 图标 URL，对应 `<link>` 标签的 `href` 属性
+     *
+     * @example '/favicon.ico'
+     * @example '/apple-touch-icon.png'
      */
     href: string;
     /**
-     * 图标尺寸
+     * 图标尺寸，对应 `<link>` 标签的 `sizes` 属性
+     *
+     * @example '32x32'
+     * @example '180x180'
      */
     sizes?: string;
     /**
-     * 图标 MIME 类型
+     * 图标 MIME 类型，对应 `<link>` 标签的 `type` 属性
+     *
+     * @example 'image/png'
+     * @example 'image/svg+xml'
      */
     type?: string;
 }
@@ -30,6 +44,8 @@ interface Icon {
  * 图标文件复制配置选项接口
  *
  * @interface CopyOptions
+ * @description 配置图标文件从源目录到构建输出目录的复制行为，
+ * 仅当此对象存在时才开启图标文件复制功能。
  */
 interface CopyOptions {
     /**
@@ -51,7 +67,7 @@ interface CopyOptions {
      */
     overwrite?: boolean;
     /**
-     * 是否支持递归复制
+     * 是否支持递归复制子目录
      *
      * @default true
      */
@@ -61,6 +77,28 @@ interface CopyOptions {
  * 网站图标管理插件的配置选项接口
  *
  * @interface FaviconManagerOptions
+ * @extends {BasePluginOptions}
+ *
+ * @description 支持三种图标配置方式（优先级从高到低）：
+ * 1. `link` - 自定义完整的 `<link>` 标签 HTML
+ * 2. `url` - 完整的图标 URL
+ * 3. `base` + 默认 favicon.ico - 基础路径拼接
+ * 此外还支持通过 `icons` 数组配置多个图标，以及通过 `copyOptions` 复制图标文件。
+ *
+ * @example
+ * ```typescript
+ * faviconManager({
+ *   base: '/assets',
+ *   icons: [
+ *     { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' },
+ *     { rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
+ *   ],
+ *   copyOptions: {
+ *     sourceDir: 'src/assets/icons',
+ *     targetDir: 'dist/assets/icons'
+ *   }
+ * })
+ * ```
  */
 interface FaviconManagerOptions extends BasePluginOptions {
     /**

package/dist/plugins/faviconManager/index.mjs

@@ -1 +1 @@
-import{createPluginFactory as n,BasePlugin as a}from"../../factory/index.mjs";import{checkSourceExists as c,copySourceToTarget as l}from"../../common/fs/index.mjs";import{V as g}from"../../shared/vite-plugin.DcExl6jd.mjs";import{injectBeforeTag as p}from"../../common/html/index.mjs";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"fs";import"path";function F(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class h extends a{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new g(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=F(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=p(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:s=!0,recursive:o=!0}=i;await c(e);const r=await l(e,t,{recursive:o,overwrite:s,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${r.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${r.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${r.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const f=n(h,u=>typeof u=="string"?{base:u}:u||{});export{f as faviconManager};
+import{createPluginFactory as n,BasePlugin as a}from"../../factory/index.mjs";import{checkSourceExists as c,copySourceToTarget as l}from"../../common/fs/index.mjs";import{V as g}from"../../shared/vite-plugin.DcExl6jd.mjs";import{injectBeforeTag as p}from"../../common/html/index.mjs";import"../../logger/index.mjs";import"fs";import"path";import"../../shared/vite-plugin.BPFqtmWa.mjs";function F(u){const i=[];if(u.link)return[];if(u.icons&&u.icons.length>0)for(const e of u.icons){const t={rel:e.rel,href:e.href};e.sizes&&(t.sizes=e.sizes),e.type&&(t.type=e.type),i.push({tag:"link",attrs:t,injectTo:"head"})}else if(u.url)i.push({tag:"link",attrs:{rel:"icon",href:u.url},injectTo:"head"});else{const e=u.base||"/",t=e.endsWith("/")?`${e}favicon.ico`:`${e}/favicon.ico`;i.push({tag:"link",attrs:{rel:"icon",href:t},injectTo:"head"})}return i}class h extends a{getDefaultOptions(){return{base:"/"}}validateOptions(){this.validator.field("base").string().field("url").string().field("link").string().field("icons").array(),this.options?.copyOptions&&(this.validator.field("copyOptions").object(),new g(this.options.copyOptions).field("sourceDir").required().string().field("targetDir").required().string().field("overwrite").boolean().field("recursive").boolean().validate()),this.validator.validate()}getPluginName(){return"favicon-manager"}getIconTagDescriptors(){if(!this.options.enabled)return this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),[];const i=F(this.options);return i.length>0&&this.logger.success(`\u6210\u529F\u6CE8\u5165 ${i.length} \u4E2A\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6`),i}injectCustomLinkTag(i){if(!this.options.enabled||!this.options.link)return i;const e=this.options.link,t=p(i,"</head>",e);return t.injected?(this.logger.success("\u6210\u529F\u6CE8\u5165\u81EA\u5B9A\u4E49\u56FE\u6807\u6807\u7B7E\u5230 HTML \u6587\u4EF6"),this.logger.info(`  - ${e}`),t.html):(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8DF3\u8FC7\u56FE\u6807\u6CE8\u5165"),i)}async copyFiles(){if(!this.options.enabled){this.logger.info("\u63D2\u4EF6\u5DF2\u7981\u7528\uFF0C\u8DF3\u8FC7\u6587\u4EF6\u590D\u5236");return}const{copyOptions:i}=this.options;if(!i)return;const{sourceDir:e,targetDir:t,overwrite:s=!0,recursive:o=!0}=i;await c(e);const r=await l(e,t,{recursive:o,overwrite:s,incremental:!0});this.logger.success(`\u56FE\u6807\u6587\u4EF6\u590D\u5236\u6210\u529F\uFF1A\u4ECE ${e} \u5230 ${t}`,`\u590D\u5236\u4E86 ${r.copiedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u4E86 ${r.skippedFiles} \u4E2A\u6587\u4EF6\uFF0C\u8017\u65F6 ${r.executionTime}ms`)}addPluginHooks(i){i.transformIndexHtml={order:"pre",handler:e=>{if(this.options.link)return this.injectCustomLinkTag(e);const t=this.getIconTagDescriptors();return t.length>0?{html:e,tags:t}:e}},i.writeBundle=async()=>{await this.safeExecute(()=>this.copyFiles(),"\u56FE\u6807\u6587\u4EF6\u590D\u5236")}}}const f=n(h,u=>typeof u=="string"?{base:u}:u||{});export{f as faviconManager};