@meng-xi/vite-plugin 0.1.0 → 0.1.2

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

@@ -0,0 +1,215 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.mjs';
+import '../../shared/vite-plugin.DRRlWY8P.mjs';
+
+/**
+ * 路由元信息
+ */
+interface RouteMeta {
+    /** 页面标题 */
+    title?: string;
+    /** 是否为TabBar页面 */
+    isTab?: boolean;
+    /** 是否需要登录 */
+    requireAuth?: boolean;
+    /** 自定义扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 路由配置项
+ */
+interface RouteConfig {
+    /** 路由路径 */
+    path: string;
+    /** 路由名称（用于命名路由导航） */
+    name?: string;
+    /** 路由元信息 */
+    meta?: RouteMeta;
+}
+/**
+ * uni-app pages.json 中的页面配置项
+ */
+interface UniAppPageConfig {
+    /** 页面路径 */
+    path: string;
+    /** 页面样式 */
+    style?: {
+        /** 导航栏标题 */
+        navigationBarTitleText?: string;
+        /** 是否需要登录 */
+        requireAuth?: boolean;
+        /** 其他自定义属性 */
+        [key: string]: unknown;
+    };
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * uni-app pages.json 中的 tabBar 配置
+ */
+interface UniAppTabBarConfig {
+    /** tabBar 列表 */
+    list?: Array<{
+        /** 页面路径 */
+        pagePath: string;
+        /** 文字 */
+        text?: string;
+        /** 图标路径 */
+        iconPath?: string;
+        /** 选中图标路径 */
+        selectedIconPath?: string;
+    }>;
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * uni-app pages.json 结构
+ */
+interface UniAppPagesJson {
+    /** 页面列表 */
+    pages: UniAppPageConfig[];
+    /** 子包 */
+    subPackages?: Array<{
+        root: string;
+        pages: UniAppPageConfig[];
+    }>;
+    /** tabBar 配置 */
+    tabBar?: UniAppTabBarConfig;
+    /** 全局样式 */
+    globalStyle?: Record<string, unknown>;
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * 输出文件格式类型
+ */
+type OutputFormat = 'ts' | 'js';
+/**
+ * 路由名称生成策略
+ */
+type NameStrategy = 'path' | 'camelCase' | 'pascalCase' | 'custom';
+/**
+ * 生成路由配置插件选项
+ */
+interface GenerateRouterOptions extends BasePluginOptions {
+    /**
+     * pages.json 文件路径（相对于项目根目录）
+     *
+     * @default 'src/pages.json'
+     */
+    pagesJsonPath?: string;
+    /**
+     * 输出文件路径（相对于项目根目录）
+     *
+     * @default 'src/router.config.ts'
+     */
+    outputPath?: string;
+    /**
+     * 输出文件格式
+     *
+     * @default 'ts'
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * 路由名称生成策略
+     *
+     * @default 'camelCase'
+     */
+    nameStrategy?: NameStrategy;
+    /**
+     * 自定义路由名称生成函数
+     *
+     * @param path - 页面路径
+     * @returns 路由名称
+     */
+    customNameGenerator?: (path: string) => string;
+    /**
+     * 是否包含子包路由
+     *
+     * @default true
+     */
+    includeSubPackages?: boolean;
+    /**
+     * 是否监听 pages.json 变化并自动重新生成
+     *
+     * @default true
+     */
+    watch?: boolean;
+    /**
+     * 额外的元信息字段映射
+     *
+     * @description 将 pages.json 中 style 的字段映射到 meta 中
+     * @example { 'navigationBarTitleText': 'title', 'requireAuth': 'requireAuth' }
+     */
+    metaMapping?: Record<string, string>;
+    /**
+     * 是否导出类型定义
+     *
+     * @default true
+     */
+    exportTypes?: boolean;
+    /**
+     * 是否保留用户对 routes 配置的修改
+     *
+     * @description 开启后，用户在 routes 数组中修改的字段将被保留
+     * @default true
+     */
+    preserveRouteChanges?: boolean;
+}
+
+/**
+ * 生成路由配置插件
+ *
+ * @param {GenerateRouterOptions} options - 插件配置选项
+ * @returns {Plugin} 一个 Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // 基本使用 - 使用默认配置
+ * generateRouter()
+ *
+ * // 自定义 pages.json 路径
+ * generateRouter({
+ *   pagesJsonPath: 'pages.json'
+ * })
+ *
+ * // 输出 JavaScript 文件
+ * generateRouter({
+ *   outputFormat: 'js',
+ *   outputPath: 'src/router.config.js'
+ * })
+ *
+ * // 使用帕斯卡命名策略
+ * generateRouter({
+ *   nameStrategy: 'pascalCase'
+ * })
+ *
+ * // 自定义路由名称生成
+ * generateRouter({
+ *   nameStrategy: 'custom',
+ *   customNameGenerator: (path) => `route_${path.replace(/\//g, '_')}`
+ * })
+ *
+ * // 自定义元信息映射
+ * generateRouter({
+ *   metaMapping: {
+ *     navigationBarTitleText: 'title',
+ *     requireAuth: 'requireAuth',
+ *     customField: 'custom'
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * 该插件会读取 uni-app 项目的 pages.json 文件，自动生成路由配置文件：
+ * - 支持主包和子包页面
+ * - 自动识别 tabBar 页面
+ * - 支持多种路由名称生成策略
+ * - 支持自定义元信息字段映射
+ * - 开发模式下自动监听 pages.json 变化并重新生成
+ */
+declare const generateRouter: PluginFactory<GenerateRouterOptions, GenerateRouterOptions>;
+
+export { generateRouter };
+export type { GenerateRouterOptions, NameStrategy, OutputFormat, RouteConfig, RouteMeta, UniAppPageConfig, UniAppPagesJson, UniAppTabBarConfig };

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

@@ -0,0 +1,215 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.js';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.js';
+import '../../shared/vite-plugin.DRRlWY8P.js';
+
+/**
+ * 路由元信息
+ */
+interface RouteMeta {
+    /** 页面标题 */
+    title?: string;
+    /** 是否为TabBar页面 */
+    isTab?: boolean;
+    /** 是否需要登录 */
+    requireAuth?: boolean;
+    /** 自定义扩展字段 */
+    [key: string]: unknown;
+}
+/**
+ * 路由配置项
+ */
+interface RouteConfig {
+    /** 路由路径 */
+    path: string;
+    /** 路由名称（用于命名路由导航） */
+    name?: string;
+    /** 路由元信息 */
+    meta?: RouteMeta;
+}
+/**
+ * uni-app pages.json 中的页面配置项
+ */
+interface UniAppPageConfig {
+    /** 页面路径 */
+    path: string;
+    /** 页面样式 */
+    style?: {
+        /** 导航栏标题 */
+        navigationBarTitleText?: string;
+        /** 是否需要登录 */
+        requireAuth?: boolean;
+        /** 其他自定义属性 */
+        [key: string]: unknown;
+    };
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * uni-app pages.json 中的 tabBar 配置
+ */
+interface UniAppTabBarConfig {
+    /** tabBar 列表 */
+    list?: Array<{
+        /** 页面路径 */
+        pagePath: string;
+        /** 文字 */
+        text?: string;
+        /** 图标路径 */
+        iconPath?: string;
+        /** 选中图标路径 */
+        selectedIconPath?: string;
+    }>;
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * uni-app pages.json 结构
+ */
+interface UniAppPagesJson {
+    /** 页面列表 */
+    pages: UniAppPageConfig[];
+    /** 子包 */
+    subPackages?: Array<{
+        root: string;
+        pages: UniAppPageConfig[];
+    }>;
+    /** tabBar 配置 */
+    tabBar?: UniAppTabBarConfig;
+    /** 全局样式 */
+    globalStyle?: Record<string, unknown>;
+    /** 其他属性 */
+    [key: string]: unknown;
+}
+/**
+ * 输出文件格式类型
+ */
+type OutputFormat = 'ts' | 'js';
+/**
+ * 路由名称生成策略
+ */
+type NameStrategy = 'path' | 'camelCase' | 'pascalCase' | 'custom';
+/**
+ * 生成路由配置插件选项
+ */
+interface GenerateRouterOptions extends BasePluginOptions {
+    /**
+     * pages.json 文件路径（相对于项目根目录）
+     *
+     * @default 'src/pages.json'
+     */
+    pagesJsonPath?: string;
+    /**
+     * 输出文件路径（相对于项目根目录）
+     *
+     * @default 'src/router.config.ts'
+     */
+    outputPath?: string;
+    /**
+     * 输出文件格式
+     *
+     * @default 'ts'
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * 路由名称生成策略
+     *
+     * @default 'camelCase'
+     */
+    nameStrategy?: NameStrategy;
+    /**
+     * 自定义路由名称生成函数
+     *
+     * @param path - 页面路径
+     * @returns 路由名称
+     */
+    customNameGenerator?: (path: string) => string;
+    /**
+     * 是否包含子包路由
+     *
+     * @default true
+     */
+    includeSubPackages?: boolean;
+    /**
+     * 是否监听 pages.json 变化并自动重新生成
+     *
+     * @default true
+     */
+    watch?: boolean;
+    /**
+     * 额外的元信息字段映射
+     *
+     * @description 将 pages.json 中 style 的字段映射到 meta 中
+     * @example { 'navigationBarTitleText': 'title', 'requireAuth': 'requireAuth' }
+     */
+    metaMapping?: Record<string, string>;
+    /**
+     * 是否导出类型定义
+     *
+     * @default true
+     */
+    exportTypes?: boolean;
+    /**
+     * 是否保留用户对 routes 配置的修改
+     *
+     * @description 开启后，用户在 routes 数组中修改的字段将被保留
+     * @default true
+     */
+    preserveRouteChanges?: boolean;
+}
+
+/**
+ * 生成路由配置插件
+ *
+ * @param {GenerateRouterOptions} options - 插件配置选项
+ * @returns {Plugin} 一个 Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // 基本使用 - 使用默认配置
+ * generateRouter()
+ *
+ * // 自定义 pages.json 路径
+ * generateRouter({
+ *   pagesJsonPath: 'pages.json'
+ * })
+ *
+ * // 输出 JavaScript 文件
+ * generateRouter({
+ *   outputFormat: 'js',
+ *   outputPath: 'src/router.config.js'
+ * })
+ *
+ * // 使用帕斯卡命名策略
+ * generateRouter({
+ *   nameStrategy: 'pascalCase'
+ * })
+ *
+ * // 自定义路由名称生成
+ * generateRouter({
+ *   nameStrategy: 'custom',
+ *   customNameGenerator: (path) => `route_${path.replace(/\//g, '_')}`
+ * })
+ *
+ * // 自定义元信息映射
+ * generateRouter({
+ *   metaMapping: {
+ *     navigationBarTitleText: 'title',
+ *     requireAuth: 'requireAuth',
+ *     customField: 'custom'
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * 该插件会读取 uni-app 项目的 pages.json 文件，自动生成路由配置文件：
+ * - 支持主包和子包页面
+ * - 自动识别 tabBar 页面
+ * - 支持多种路由名称生成策略
+ * - 支持自定义元信息字段映射
+ * - 开发模式下自动监听 pages.json 变化并重新生成
+ */
+declare const generateRouter: PluginFactory<GenerateRouterOptions, GenerateRouterOptions>;
+
+export { generateRouter };
+export type { GenerateRouterOptions, NameStrategy, OutputFormat, RouteConfig, RouteMeta, UniAppPageConfig, UniAppPagesJson, UniAppTabBarConfig };

package/dist/plugins/generateRouter/index.mjs

@@ -0,0 +1,35 @@
+import{createPluginFactory as p,BasePlugin as h}from"../../factory/index.mjs";import{readFileContent as i,writeFileContent as l}from"../../common/fs/index.mjs";import{toCamelCase as g,toPascalCase as F,stripJsonComments as m}from"../../common/format/index.mjs";import{resolve as r}from"path";import{existsSync as n,watch as f}from"fs";import"../../logger/index.mjs";import"../../common/object/index.mjs";import"../../shared/vite-plugin.DcExl6jd.mjs";import"crypto";class E extends h{projectRoot=process.cwd();tabBarPages=new Set;watcher=null;getDefaultOptions(){return{pagesJsonPath:"src/pages.json",outputPath:"src/router.config.ts",outputFormat:"ts",nameStrategy:"camelCase",includeSubPackages:!0,watch:!0,exportTypes:!0,preserveRouteChanges:!0,metaMapping:{navigationBarTitleText:"title",requireAuth:"requireAuth"}}}validateOptions(){if(this.validator.field("pagesJsonPath").string().field("outputPath").string().field("outputFormat").enum(["ts","js"]).field("nameStrategy").enum(["path","camelCase","pascalCase","custom"]).validate(),this.options.nameStrategy==="custom"&&!this.options.customNameGenerator)throw new Error("\u5F53 nameStrategy \u4E3A custom \u65F6\uFF0C\u5FC5\u987B\u63D0\u4F9B customNameGenerator")}getPluginName(){return"generate-router"}generateRouteName(t){switch(this.options.nameStrategy){case"path":return t.replace(/\//g,"_").replace(/^_/,"");case"camelCase":return g(t);case"pascalCase":return F(t);case"custom":return this.options.customNameGenerator(t);default:return g(t)}}extractMeta(t,u){const e={},s=t.style||{},a=this.options.metaMapping||{};for(const[o,c]of Object.entries(a))s[o]!==void 0&&(e[c]=s[o]);return this.tabBarPages.has(u)&&(e.isTab=!0),e}parsePageToRoute(t,u=""){const e=u?`/${u}/${t.path}`:`/${t.path}`,s=this.generateRouteName(e),a=this.extractMeta(t,e.replace(/^\//,"")),o={path:e,name:s};return Object.keys(a).length>0&&(o.meta=a),o}parsePagesJson(t){const u=[];if(!t.pages||!Array.isArray(t.pages)||t.pages.length===0)return this.logger.warn("pages.json \u4E2D\u6CA1\u6709\u6709\u6548\u7684\u9875\u9762\u914D\u7F6E"),u;if(this.tabBarPages.clear(),t.tabBar?.list)for(const e of t.tabBar.list)this.tabBarPages.add(e.pagePath);for(const e of t.pages)u.push(this.parsePageToRoute(e));if(this.options.includeSubPackages&&t.subPackages){for(const e of t.subPackages)if(e.pages&&Array.isArray(e.pages))for(const s of e.pages)u.push(this.parsePageToRoute(s,e.root))}return u}generateTypeDefinitions(){return!this.options.exportTypes||this.options.outputFormat==="js"?"":`
+/**
+ * \u8DEF\u7531\u5143\u4FE1\u606F
+ */
+export interface RouteMeta {
+	/** \u9875\u9762\u6807\u9898 */
+	title?: string
+	/** \u662F\u5426\u4E3ATabBar\u9875\u9762 */
+	isTab?: boolean
+	/** \u662F\u5426\u9700\u8981\u767B\u5F55 */
+	requireAuth?: boolean
+	/** \u81EA\u5B9A\u4E49\u6269\u5C55\u5B57\u6BB5 */
+	[key: string]: unknown
+}
+
+/**
+ * \u8DEF\u7531\u914D\u7F6E\u9879
+ */
+export interface RouteConfig {
+	/** \u8DEF\u7531\u8DEF\u5F84 */
+	path: string
+	/** \u8DEF\u7531\u540D\u79F0\uFF08\u7528\u4E8E\u547D\u540D\u8DEF\u7531\u5BFC\u822A\uFF09 */
+	name?: string
+	/** \u8DEF\u7531\u5143\u4FE1\u606F */
+	meta?: RouteMeta
+}
+`}generateFileContent(t){const u=this.generateTypeDefinitions(),e=this.options.outputFormat==="ts",s=JSON.stringify(t,null,"	").replace(/"(\w+)":/g,"$1:").replace(/: "([^"]+)"/g,": '$1'");return`${u}
+/**
+ * \u8DEF\u7531\u914D\u7F6E\u5217\u8868
+ * @description \u7531 pages.json \u81EA\u52A8\u751F\u6210
+ */
+export const routes${e?": RouteConfig[]":""} = ${s}
+
+export default routes
+`}async readPagesJson(){const t=r(this.projectRoot,this.options.pagesJsonPath);if(!n(t))return this.logger.warn(`pages.json \u6587\u4EF6\u4E0D\u5B58\u5728: ${t}`),null;try{const u=await i(t),e=m(u);return JSON.parse(e)}catch(u){return this.logger.error(`\u89E3\u6790 pages.json \u5931\u8D25: ${u.message}`),null}}extractExistingRoutes(t){const u=new Map,e=t.match(/export const routes[^=]*=\s*(\[[\s\S]*?\](?=\s*\n|\s*$|\s*\/\/))/);if(!e)return u;try{let s=e[1].replace(/(\w+)(?=\s*:)/g,'"$1"').replace(/'([^']*)'/g,'"$1"').replace(/,\s*([\]\}])/g,"$1");const a=JSON.parse(s);for(const o of a)o.path&&u.set(o.path,o)}catch{this.logger.warn("\u89E3\u6790\u73B0\u6709 routes \u914D\u7F6E\u5931\u8D25\uFF0C\u5C06\u5B8C\u5168\u91CD\u65B0\u751F\u6210")}return u}mergeRoutes(t,u){return t.map(e=>{const s=u.get(e.path);if(!s)return e;const a={};return e.meta&&Object.assign(a,e.meta),s.meta&&Object.assign(a,s.meta),{...s,path:e.path,meta:Object.keys(a).length>0?a:void 0}})}async generateRouterConfig(){const t=await this.readPagesJson();if(!t)return;let u=this.parsePagesJson(t);const e=r(this.projectRoot,this.options.outputPath);if(this.options.preserveRouteChanges&&n(e))try{const a=await i(e),o=this.extractExistingRoutes(a);o.size>0&&(u=this.mergeRoutes(u,o),this.logger.info("\u5DF2\u5408\u5E76\u7528\u6237\u5BF9\u8DEF\u7531\u914D\u7F6E\u7684\u4FEE\u6539"))}catch{}const s=this.generateFileContent(u);await l(e,s),this.logger.success(`\u8DEF\u7531\u914D\u7F6E\u6587\u4EF6\u5DF2\u751F\u6210: ${e}`),this.logger.info(`\u5171\u751F\u6210 ${u.length} \u6761\u8DEF\u7531\u914D\u7F6E`)}startWatching(){if(!this.options.watch)return;const t=r(this.projectRoot,this.options.pagesJsonPath);n(t)&&(this.watcher=f(t,async u=>{u==="change"&&(this.logger.info("\u68C0\u6D4B\u5230 pages.json \u53D8\u5316\uFF0C\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E..."),await this.safeExecute(()=>this.generateRouterConfig(),"\u91CD\u65B0\u751F\u6210\u8DEF\u7531\u914D\u7F6E"))}),this.logger.info(`\u6B63\u5728\u76D1\u542C pages.json \u53D8\u5316: ${t}`))}stopWatching(){this.watcher&&(this.watcher.close(),this.watcher=null)}addPluginHooks(t){t.configResolved=async u=>{this.projectRoot=u.root,await this.safeExecute(()=>this.generateRouterConfig(),"\u751F\u6210\u8DEF\u7531\u914D\u7F6E"),u.command==="serve"&&this.startWatching()}}destroy(){super.destroy(),this.stopWatching()}}const D=p(E);export{D as generateRouter};

package/dist/plugins/generateVersion/index.cjs

@@ -0,0 +1 @@
+"use strict";const factory_index=require("../../factory/index.cjs"),common_format_index=require("../../common/format/index.cjs"),common_fs_index=require("../../common/fs/index.cjs"),u=require("path");require("../../logger/index.cjs"),require("../../common/object/index.cjs"),require("../../shared/vite-plugin.Bcg6RW2N.cjs"),require("crypto"),require("fs");class f extends factory_index.BasePlugin{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 e=common_format_index.getDateFormatParams(this.buildTime),t=common_format_index.generateRandomHash(this.options.hashLength);let i;switch(this.options.format){case"timestamp":i=`${e.YYYY}${e.MM}${e.DD}${e.HH}${e.mm}${e.ss}`;break;case"date":i=`${e.YYYY}.${e.MM}.${e.DD}`;break;case"datetime":i=`${e.YYYY}.${e.MM}.${e.DD}.${e.HH}${e.mm}${e.ss}`;break;case"semver":i=this.options.semverBase||"1.0.0";break;case"hash":i=t;break;case"custom":i=this.parseCustomFormat({...e,hash:t});break;default:i=e.timestamp}const s=this.options.prefix||"",o=this.options.suffix||"";return`${s}${i}${o}`}parseCustomFormat(e){const t={...e};if(this.options.semverBase){const[i,s,o]=this.options.semverBase.split(".");t.major=i||"1",t.minor=s||"0",t.patch=o||"0"}return common_format_index.parseTemplate(this.options.customFormat||"",t)}generateVersionInfo(){return{version:this.version,buildTime:this.buildTime.toISOString(),timestamp:this.buildTime.getTime(),format:this.options.format,...this.options.extra}}async writeVersionFile(e){const t=u.join(e,this.options.outputFile||"version.json"),i=this.generateVersionInfo();await common_fs_index.writeFileContent(t,JSON.stringify(i,null,2)),this.logger.success(`\u7248\u672C\u6587\u4EF6\u5DF2\u751F\u6210: ${t}`)}addPluginHooks(e){e.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")&&(e.config=()=>{this.version||(this.buildTime=new Date,this.version=this.generateVersion());const t=this.options.defineName||"__APP_VERSION__";return this.logger.info(`\u6CE8\u5165\u5168\u5C40\u53D8\u91CF: ${t} = "${this.version}"`),{define:{[t]:JSON.stringify(this.version),[`${t}_INFO`]:JSON.stringify(this.generateVersionInfo())}}}),(this.options.outputType==="file"||this.options.outputType==="both")&&(e.writeBundle=async()=>{this.viteConfig&&await this.safeExecute(async()=>{const t=this.viteConfig.build.outDir;await this.writeVersionFile(t)},"\u5199\u5165\u7248\u672C\u6587\u4EF6")})}}const generateVersion=factory_index.createPluginFactory(f);exports.generateVersion=generateVersion;

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

@@ -0,0 +1,184 @@
+import { BasePluginOptions, PluginFactory } from '../../factory/index.cjs';
+import 'vite';
+import '../../shared/vite-plugin.CLr0ttuO.cjs';
+import '../../shared/vite-plugin.DRRlWY8P.cjs';
+
+/**
+ * 版本号格式类型
+ *
+ * @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 };