@meng-xi/vite-plugin 0.1.3 → 0.1.4

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

@@ -0,0 +1,156 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
+import { E as EnvFieldRule, b as EnvValidationResult } from '../../shared/vite-plugin.CmtcnItg.cjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.cjs';
+import '../../shared/vite-plugin.DRRlWY8P.cjs';
+
+/**
+ * 环境变量校验失败时的处理动作
+ *
+ * @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.d.mts

@@ -0,0 +1,156 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
+import { E as EnvFieldRule, b as EnvValidationResult } from '../../shared/vite-plugin.CmtcnItg.mjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.mjs';
+import '../../shared/vite-plugin.DRRlWY8P.mjs';
+
+/**
+ * 环境变量校验失败时的处理动作
+ *
+ * @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.d.ts

@@ -0,0 +1,156 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.js';
+import { E as EnvFieldRule, b as EnvValidationResult } from '../../shared/vite-plugin.CmtcnItg.js';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.js';
+import '../../shared/vite-plugin.DRRlWY8P.js';
+
+/**
+ * 环境变量校验失败时的处理动作
+ *
+ * @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{v as A}from"../../shared/vite-plugin.DnFDPjNf.mjs";import{injectBeforeTag as E}from"../../common/html/index.mjs";import{writeFileContent as h}from"../../common/fs/index.mjs";import{formatDate as y}from"../../common/format/index.mjs";import p from"node:path";import m from"node:fs";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"../../shared/vite-plugin.DcExl6jd.mjs";import"../../shared/vite-plugin.BCuhU1au.mjs";import"../../common/script/index.mjs";import"fs";import"path";import"crypto";function D(r){const i=new Map,s=[];for(const[t,e]of Object.entries(r)){const o={type:"string",required:!0,...e};if(o.group){const n=i.get(o.group)||[];n.push({key:t,rule:o}),i.set(o.group,n)}else s.push({key:t,rule:o})}const u=[];u.push("# \u73AF\u5883\u53D8\u91CF\u6A21\u677F\u6587\u4EF6"),u.push(`# \u751F\u6210\u65F6\u95F4: ${new Date().toISOString()}`),u.push("# \u7531 @meng-xi/vite-plugin envGuard \u81EA\u52A8\u751F\u6210"),u.push(""),s.length>0&&g(u,"\u901A\u7528\u914D\u7F6E",s);for(const[t,e]of i)g(u,t,e);return u.join(`
+`)}function g(r,i,s){r.push("# =============================="),r.push(`# ${i}`),r.push("# =============================="),r.push("");for(const{key:u,rule:t}of s){t.description&&r.push(`# ${t.description}`);const e=[];e.push(`\u7C7B\u578B: ${t.type||"string"}`),e.push(t.required!==!1?"\u5FC5\u9700":"\u53EF\u9009"),t.enumValues&&t.enumValues.length>0&&e.push(`\u679A\u4E3E\u503C: ${t.enumValues.join(" | ")}`),t.minValue!==void 0&&e.push(`\u6700\u5C0F\u503C: ${t.minValue}`),t.maxValue!==void 0&&e.push(`\u6700\u5927\u503C: ${t.maxValue}`),t.minLength!==void 0&&e.push(`\u6700\u5C0F\u957F\u5EA6: ${t.minLength}`),t.maxLength!==void 0&&e.push(`\u6700\u5927\u957F\u5EA6: ${t.maxLength}`),t.sensitive&&e.push("\u26A0\uFE0F \u654F\u611F\u4FE1\u606F"),r.push(`# [${e.join(" | ")}]`),t.default!==void 0?r.push(`${u}=${t.sensitive?"********":t.default}`):r.push(`${u}=`),r.push("")}}function C(r,i,s,u){const t=[];for(const[a,l]of Object.entries(r))l.required!==!1&&t.push({key:a,rule:{type:"string",required:!0,...l}});if(t.length===0)return"";const e=u.filter(a=>a.status!=="pass"),o=t.map(({key:a,rule:l})=>({key:a,type:l.type||"string",description:l.description||""})),n=JSON.stringify(o,null,2),d=e.map(a=>a.key),f=JSON.stringify(d),c=R(s);return`<script>
+${`
+(function() {
+  'use strict';
+  var GUARD_NAME = ${JSON.stringify(i)};
+  var GUARD_DATA = ${n};
+  var FAILED_KEYS = ${f};
+  var MODE = ${JSON.stringify(s)};
+
+  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 R(r){switch(r){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""}}class $ 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(i=>i===!1||typeof i=="string","reportOutput \u5FC5\u987B\u4E3A false \u6216\u5B57\u7B26\u4E32\u8DEF\u5F84").field("validateBeforeBuild").boolean().field("showSummary").boolean().validate()}getPluginName(){return"env-guard"}addPluginHooks(i){this.options.validateBeforeBuild&&(i.configResolved=s=>{this.viteConfig=s,this.runValidation()}),this.options.runtimeGuard&&(i.transformIndexHtml={order:"post",handler:s=>this.safeExecuteSync(()=>this.injectRuntimeGuard(s),"\u6CE8\u5165\u8FD0\u884C\u65F6\u5B88\u536B")||s})}runValidation(){this.options.autoLoadEnv&&this.loadEnvFiles(),this.validationResults=A(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 i=this.viteConfig.root||process.cwd();for(const s of this.options.envFiles){const u=p.resolve(i,s);if(m.existsSync(u))try{this.parseAndLoadEnvFile(u)}catch{this.logger.warn(`\u52A0\u8F7D .env \u6587\u4EF6\u5931\u8D25: ${u}`)}}}parseAndLoadEnvFile(i){const s=m.readFileSync(i,"utf-8").split(`
+`);for(const u of s){const t=u.trim();if(!t||t.startsWith("#"))continue;const e=t.indexOf("=");if(e===-1)continue;const o=t.slice(0,e).trim();let n=t.slice(e+1).trim();(n.startsWith('"')&&n.endsWith('"')||n.startsWith("'")&&n.endsWith("'"))&&(n=n.slice(1,-1)),o.startsWith("VITE_")&&process.env[o]===void 0&&(process.env[o]=n)}}buildResult(){const i=this.validationResults.length,s=this.validationResults.filter(e=>e.status==="pass").length,u=this.validationResults.filter(e=>e.status==="missing").length,t=this.validationResults.filter(e=>e.status!=="pass"&&e.status!=="missing").length;return{timestamp:y(new Date,"{YYYY}-{MM}-{DD}T{HH}:{mm}:{ss}"),total:i,passed:s,missing:u,invalid:t,results:this.validationResults,allPassed:u===0&&t===0}}handleResults(){if(!this.guardResult||this.guardResult.allPassed)return;const i=this.validationResults.filter(e=>e.status==="missing").map(e=>e.key),s=this.validationResults.filter(e=>e.status!=="pass"&&e.status!=="missing"),u=[];i.length>0&&u.push(`\u7F3A\u5C11\u5FC5\u9700\u7684\u73AF\u5883\u53D8\u91CF: ${i.join(", ")}`);for(const e of s)u.push(`${e.key}: ${e.message}`);const t=u.join(`
+  `);switch(this.options.failAction){case"error":throw new Error(t);case"warn":this.logger.warn(t);break}}writeEnvTemplate(){const i=this.viteConfig?.root||process.cwd(),s=p.resolve(i,this.options.templateOutput),u=D(this.options.required);this.safeExecuteSync(()=>{h(s,u),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 i=this.viteConfig?.build?.outDir||"dist",s=p.resolve(i,this.options.reportOutput);this.safeExecuteSync(()=>{const u=JSON.stringify(this.guardResult,(t,e)=>e instanceof RegExp?e.toString():typeof e=="function"?"[Function]":e,2);h(s,u),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:i,passed:s,missing:u,invalid:t,allPassed:e}=this.guardResult;if(e){this.logger.success(`\u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u901A\u8FC7: ${i} \u4E2A\u53D8\u91CF\u5168\u90E8\u5408\u6CD5`);return}this.logger.info(`\u73AF\u5883\u53D8\u91CF\u6821\u9A8C\u7ED3\u679C: \u603B\u8BA1 ${i} | \u901A\u8FC7 ${s} | \u7F3A\u5931 ${u} | \u5931\u8D25 ${t}`);const o=this.validationResults.filter(n=>n.status!=="pass");for(const n of o){const d=n.status==="missing"?"\u7F3A\u5931":"\u5931\u8D25";this.logger.warn(`  [${d}] ${n.key}: ${n.message}`)}}injectRuntimeGuard(i){const s=C(this.options.required,this.options.runtimeGlobalName,this.options.runtimeGuardMode,this.validationResults);if(!s)return i;const u=E(i,"</head>",s);return u.injected?u.html:(this.logger.warn("\u672A\u627E\u5230 </head> \u6807\u7B7E\uFF0C\u8FD0\u884C\u65F6\u5B88\u536B\u4EE3\u7801\u672A\u80FD\u6CE8\u5165"),i)}getResult(){return this.guardResult}getValidationResults(){return[...this.validationResults]}}const w=v($);export{w 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("../../common/object/index.cjs"),require("fs"),require("path"),require("../../shared/vite-plugin.BrI73DHA.cjs"),require("../../common/script/index.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

@@ -7,22 +7,36 @@ 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 {
     /**