@meng-xi/vite-plugin 0.1.0 → 0.1.2

package/dist/common/fs/index.d.mts

@@ -0,0 +1,150 @@
+/**
+ * 复制操作的选项接口
+ */
+interface CopyOptions {
+    /**
+     * 是否支持递归复制
+     */
+    recursive: boolean;
+    /**
+     * 是否覆盖同名文件
+     */
+    overwrite: boolean;
+    /**
+     * 是否启用增量复制
+     */
+    incremental?: boolean;
+    /**
+     * 并行处理的最大文件数
+     */
+    parallelLimit?: number;
+    /**
+     * 是否跳过空目录
+     */
+    skipEmptyDirs?: boolean;
+}
+/**
+ * 复制结果接口
+ */
+interface CopyResult {
+    /**
+     * 复制的文件数量
+     */
+    copiedFiles: number;
+    /**
+     * 跳过的文件数量
+     */
+    skippedFiles: number;
+    /**
+     * 复制的目录数量
+     */
+    copiedDirs: number;
+    /**
+     * 总执行时间（毫秒）
+     */
+    executionTime: number;
+}
+
+/**
+ * 文件/目录条目信息
+ */
+interface FileEntry {
+    /** 完整路径 */
+    path: string;
+    /** 是否为文件 */
+    isFile: boolean;
+    /** 是否为目录 */
+    isDirectory: boolean;
+}
+/**
+ * 检查源文件是否存在
+ * @param sourcePath 源文件路径
+ * @throws 当源文件不存在或无法访问时抛出异常
+ */
+declare function checkSourceExists(sourcePath: string): Promise<void>;
+/**
+ * 创建目标目录
+ * @param targetPath 目标目录路径
+ * @throws 当无法创建目标目录时抛出异常
+ */
+declare function ensureTargetDir(targetPath: string): Promise<void>;
+/**
+ * 读取目录内容（优化版：一次性获取文件类型信息）
+ * @param dirPath 目录路径
+ * @param recursive 是否递归读取
+ * @returns 文件和目录条目列表
+ */
+declare function readDirRecursive(dirPath: string, recursive: boolean): Promise<FileEntry[]>;
+/**
+ * 检查文件是否需要更新
+ * @param sourceFile 源文件路径
+ * @param targetFile 目标文件路径
+ * @returns 是否需要更新
+ */
+declare function shouldUpdateFile(sourceFile: string, targetFile: string): Promise<boolean>;
+/**
+ * 检查文件是否存在
+ * @param filePath 文件路径
+ * @returns 是否存在
+ *
+ * @example
+ * ```typescript
+ * if (await fileExists('/path/to/file')) {
+ *   console.log('文件存在')
+ * }
+ * ```
+ */
+declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * 带并发限制的批量执行
+ *
+ * @param items 待处理项
+ * @param handler 处理函数
+ * @param concurrency 并发数
+ * @returns 处理结果数组，顺序与输入项对应
+ *
+ * @example
+ * ```typescript
+ * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
+ * const results = await runWithConcurrency(
+ *   urls,
+ *   async (url) => fetch(url),
+ *   3 // 最多同时处理3个请求
+ * )
+ * ```
+ */
+declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
+/**
+ * 执行文件复制操作（优化版：并行IO）
+ * @param sourcePath 源文件或目录路径
+ * @param targetPath 目标文件或目录路径
+ * @param options 复制选项
+ * @returns 复制结果
+ * @throws 当复制过程中出现错误时抛出异常
+ */
+declare function copySourceToTarget(sourcePath: string, targetPath: string, options: CopyOptions): Promise<CopyResult>;
+/**
+ * 写入文件内容
+ * @param filePath 文件路径
+ * @param content 文件内容
+ * @throws 当写入过程中出现错误时抛出异常
+ */
+declare function writeFileContent(filePath: string, content: string): Promise<void>;
+/**
+ * 读取文件内容
+ * @param filePath 文件路径
+ * @returns 文件内容字符串
+ * @throws 当读取过程中出现错误时抛出异常
+ */
+declare function readFileContent(filePath: string): Promise<string>;
+/**
+ * 同步读取文件内容
+ * @param filePath 文件路径
+ * @returns 文件内容字符串
+ * @throws 当读取过程中出现错误时抛出异常
+ * @deprecated 请使用异步版本 readFileContent
+ */
+declare function readFileSync(filePath: string): string;
+
+export { checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, shouldUpdateFile, writeFileContent };
+export type { CopyOptions, CopyResult };

package/dist/common/fs/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * 复制操作的选项接口
+ */
+interface CopyOptions {
+    /**
+     * 是否支持递归复制
+     */
+    recursive: boolean;
+    /**
+     * 是否覆盖同名文件
+     */
+    overwrite: boolean;
+    /**
+     * 是否启用增量复制
+     */
+    incremental?: boolean;
+    /**
+     * 并行处理的最大文件数
+     */
+    parallelLimit?: number;
+    /**
+     * 是否跳过空目录
+     */
+    skipEmptyDirs?: boolean;
+}
+/**
+ * 复制结果接口
+ */
+interface CopyResult {
+    /**
+     * 复制的文件数量
+     */
+    copiedFiles: number;
+    /**
+     * 跳过的文件数量
+     */
+    skippedFiles: number;
+    /**
+     * 复制的目录数量
+     */
+    copiedDirs: number;
+    /**
+     * 总执行时间（毫秒）
+     */
+    executionTime: number;
+}
+
+/**
+ * 文件/目录条目信息
+ */
+interface FileEntry {
+    /** 完整路径 */
+    path: string;
+    /** 是否为文件 */
+    isFile: boolean;
+    /** 是否为目录 */
+    isDirectory: boolean;
+}
+/**
+ * 检查源文件是否存在
+ * @param sourcePath 源文件路径
+ * @throws 当源文件不存在或无法访问时抛出异常
+ */
+declare function checkSourceExists(sourcePath: string): Promise<void>;
+/**
+ * 创建目标目录
+ * @param targetPath 目标目录路径
+ * @throws 当无法创建目标目录时抛出异常
+ */
+declare function ensureTargetDir(targetPath: string): Promise<void>;
+/**
+ * 读取目录内容（优化版：一次性获取文件类型信息）
+ * @param dirPath 目录路径
+ * @param recursive 是否递归读取
+ * @returns 文件和目录条目列表
+ */
+declare function readDirRecursive(dirPath: string, recursive: boolean): Promise<FileEntry[]>;
+/**
+ * 检查文件是否需要更新
+ * @param sourceFile 源文件路径
+ * @param targetFile 目标文件路径
+ * @returns 是否需要更新
+ */
+declare function shouldUpdateFile(sourceFile: string, targetFile: string): Promise<boolean>;
+/**
+ * 检查文件是否存在
+ * @param filePath 文件路径
+ * @returns 是否存在
+ *
+ * @example
+ * ```typescript
+ * if (await fileExists('/path/to/file')) {
+ *   console.log('文件存在')
+ * }
+ * ```
+ */
+declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * 带并发限制的批量执行
+ *
+ * @param items 待处理项
+ * @param handler 处理函数
+ * @param concurrency 并发数
+ * @returns 处理结果数组，顺序与输入项对应
+ *
+ * @example
+ * ```typescript
+ * const urls = ['url1', 'url2', 'url3', 'url4', 'url5']
+ * const results = await runWithConcurrency(
+ *   urls,
+ *   async (url) => fetch(url),
+ *   3 // 最多同时处理3个请求
+ * )
+ * ```
+ */
+declare function runWithConcurrency<T, R>(items: T[], handler: (item: T) => Promise<R>, concurrency: number): Promise<R[]>;
+/**
+ * 执行文件复制操作（优化版：并行IO）
+ * @param sourcePath 源文件或目录路径
+ * @param targetPath 目标文件或目录路径
+ * @param options 复制选项
+ * @returns 复制结果
+ * @throws 当复制过程中出现错误时抛出异常
+ */
+declare function copySourceToTarget(sourcePath: string, targetPath: string, options: CopyOptions): Promise<CopyResult>;
+/**
+ * 写入文件内容
+ * @param filePath 文件路径
+ * @param content 文件内容
+ * @throws 当写入过程中出现错误时抛出异常
+ */
+declare function writeFileContent(filePath: string, content: string): Promise<void>;
+/**
+ * 读取文件内容
+ * @param filePath 文件路径
+ * @returns 文件内容字符串
+ * @throws 当读取过程中出现错误时抛出异常
+ */
+declare function readFileContent(filePath: string): Promise<string>;
+/**
+ * 同步读取文件内容
+ * @param filePath 文件路径
+ * @returns 文件内容字符串
+ * @throws 当读取过程中出现错误时抛出异常
+ * @deprecated 请使用异步版本 readFileContent
+ */
+declare function readFileSync(filePath: string): string;
+
+export { checkSourceExists, copySourceToTarget, ensureTargetDir, fileExists, readDirRecursive, readFileContent, readFileSync, runWithConcurrency, shouldUpdateFile, writeFileContent };
+export type { CopyOptions, CopyResult };

package/dist/common/fs/index.mjs

@@ -0,0 +1 @@
+import s from"fs";import E from"path";const k=10;async function v(u){try{await s.promises.access(u,s.constants.F_OK)}catch(t){const r=t;throw r.code==="ENOENT"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6E90\u6587\u4EF6\u4E0D\u5B58\u5728 - ${u}`):r.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BBF\u95EE\u6E90\u6587\u4EF6 - ${u}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u68C0\u67E5\u6E90\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function m(u){try{await s.promises.mkdir(u,{recursive:!0})}catch(t){const r=t;throw r.code==="EACCES"?new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u521B\u5EFA\u76EE\u6807\u76EE\u5F55 - ${u}`):new Error(`\u590D\u5236\u6587\u4EF6\u5931\u8D25\uFF1A\u521B\u5EFA\u76EE\u6807\u76EE\u5F55\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}async function D(u,t){const r=await s.promises.readdir(u,{withFileTypes:!0}),e=[];for(const a of r){const o=E.join(u,a.name),l=a.isFile(),F=a.isDirectory();if(e.push({path:o,isFile:l,isDirectory:F}),F&&t){const c=await D(o,t);e.push(...c)}}return e}async function y(u,t){try{const[r,e]=await Promise.all([s.promises.stat(u),s.promises.stat(t)]);return r.mtimeMs>e.mtimeMs||r.size!==e.size}catch{return!0}}async function d(u){try{return await s.promises.access(u,s.constants.F_OK),!0}catch{return!1}}async function $(u,t,r){const e=[];let a=0;async function o(){for(;a<u.length;){const F=a++,c=await t(u[F]);e[F]=c}}const l=Array(Math.min(r,u.length)).fill(null).map(()=>o());return await Promise.all(l),e}async function T(u,t,r){const e=Date.now(),{recursive:a,overwrite:o,incremental:l=!1,parallelLimit:F=k}=r;let c=0,f=0,h=0;if((await s.promises.stat(u)).isDirectory()){await m(t);const n=await D(u,a),B=n.filter(i=>i.isFile);h=n.filter(i=>i.isDirectory).length;const C=new Set;for(const i of B){const A=E.relative(u,i.path),w=E.dirname(E.join(t,A));C.add(w)}await Promise.all([...C].map(i=>m(i)));const S=await $(B,async i=>{const A=E.relative(u,i.path),w=E.join(t,A);let p=o;return p||(p=!await d(w)),l&&p&&(p=await y(i.path,w)),p?(await s.promises.copyFile(i.path,w),{copied:!0,skipped:!1}):{copied:!1,skipped:!0}},F);for(const i of S)i.copied&&c++,i.skipped&&f++}else{await m(E.dirname(t));let n=o;n||(n=!await d(t)),l&&n&&(n=await y(u,t)),n?(await s.promises.copyFile(u,t),c++):f++}const g=Date.now()-e;return{copiedFiles:c,skippedFiles:f,copiedDirs:h,executionTime:g}}async function x(u,t){try{await s.promises.writeFile(u,t,"utf-8")}catch(r){const e=r;throw e.code==="EACCES"?new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u5199\u5165\u6587\u4EF6 - ${u}`):new Error(`\u5199\u5165\u6587\u4EF6\u5931\u8D25\uFF1A\u5199\u5165\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${e.message}`)}}async function j(u){try{return await s.promises.readFile(u,"utf-8")}catch(t){const r=t;throw r.code==="EACCES"?new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BFB\u53D6\u6587\u4EF6 - ${u}`):new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u8BFB\u53D6\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}function M(u){try{return s.readFileSync(u,"utf-8")}catch(t){const r=t;throw r.code==="EACCES"?new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u6CA1\u6709\u6743\u9650\u8BFB\u53D6\u6587\u4EF6 - ${u}`):new Error(`\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25\uFF1A\u8BFB\u53D6\u6587\u4EF6\u65F6\u51FA\u9519 - ${u}\uFF0C\u9519\u8BEF\uFF1A${r.message}`)}}export{v as checkSourceExists,T as copySourceToTarget,m as ensureTargetDir,d as fileExists,D as readDirRecursive,j as readFileContent,M as readFileSync,$ as runWithConcurrency,y as shouldUpdateFile,x as writeFileContent};

package/dist/common/html/index.cjs

@@ -0,0 +1,2 @@
+"use strict";function injectBeforeTag(e,t,l){const n=new RegExp(t,"i");return n.test(e)?{html:e.replace(n,`${l}
+${t}`),injected:!0}:{html:e,injected:!1}}function injectHtmlByPriority(e,t,l=["</head>","</body>","</html>"]){for(const n of l){const c=injectBeforeTag(e,n,t);if(c.injected)return c}return{html:e+t,injected:!0}}function injectBeforeTagWithFallback(e,t,l){const n=injectBeforeTag(e,"</body>",t);if(n.injected)return{...n,usedFallback:!1};const c=injectBeforeTag(e,"</html>",t);return c.injected?{...c,usedFallback:!1}:{html:e+t,injected:!0,usedFallback:!0}}function injectHeadAndBody(e,t,l){let n=e,c=!1;if(t){const i=injectBeforeTag(n,"</head>",t);i.injected&&(n=i.html,c=!0)}const r=injectBeforeTagWithFallback(n,l);return{html:r.html,headInjected:c,bodyInjected:r.injected,usedFallback:r.usedFallback}}exports.injectBeforeTag=injectBeforeTag,exports.injectBeforeTagWithFallback=injectBeforeTagWithFallback,exports.injectHeadAndBody=injectHeadAndBody,exports.injectHtmlByPriority=injectHtmlByPriority;

package/dist/common/html/index.d.cts

@@ -0,0 +1,109 @@
+/**
+ * HTML 注入结果
+ */
+interface HtmlInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** 是否成功注入 */
+    injected: boolean;
+}
+/**
+ * 双区域 HTML 注入结果
+ */
+interface DualInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** head 区域是否成功注入 */
+    headInjected: boolean;
+    /** body 区域是否成功注入 */
+    bodyInjected: boolean;
+    /** body 注入是否使用了回退策略（追加到末尾） */
+    usedFallback: boolean;
+}
+
+/**
+ * 在 HTML 中指定闭合标签前注入代码
+ *
+ * @param html - 原始 HTML 内容
+ * @param tag - 目标闭合标签（如 `</head>`、`</body>`、`</html>`）
+ * @param code - 要注入的代码
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 在 </head> 前注入 CSS
+ * const result = injectBeforeTag(html, '</head>', '<style>...</style>')
+ *
+ * // 在 </body> 前注入 JS
+ * const result = injectBeforeTag(html, '</body>', '<script>...</script>')
+ * ```
+ */
+declare function injectBeforeTag(html: string, tag: string, code: string): HtmlInjectResult;
+/**
+ * 按优先级向 HTML 中注入代码
+ *
+ * @description 依次尝试在 `</head>`、`</body>`、`</html>` 前注入代码，
+ * 优先注入到靠前的标签位置。适用于需要注入到页面中但无特定位置要求的场景
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param targets - 目标标签优先级列表，默认为 `['</head>', '</body>', '</html>']`
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 优先注入到 </body> 前
+ * const result = injectHtmlByPriority(html, scriptCode, ['</body>', '</html>'])
+ * ```
+ */
+declare function injectHtmlByPriority(html: string, code: string, targets?: string[]): HtmlInjectResult;
+/**
+ * 带回退策略的 HTML 注入
+ *
+ * @description 依次尝试在 `</body>`、`</html>` 前注入代码，
+ * 如果均未找到目标标签，则将代码追加到 HTML 末尾。
+ * 适用于需要注入到页面底部但不确定 HTML 结构是否完整的场景。
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param fallbackMessage - 回退到末尾时的警告信息，为空则不输出警告
+ * @returns 注入结果对象，包含注入后的 HTML、是否成功标志和是否使用了回退策略
+ *
+ * @example
+ * ```typescript
+ * // 注入 JS 脚本到页面底部
+ * const result = injectBeforeTagWithFallback(html, '<script>...</script>')
+ *
+ * // 带自定义警告信息
+ * const result = injectBeforeTagWithFallback(html, scriptCode, '未找到 </body> 标签，代码追加到文件末尾')
+ * ```
+ */
+declare function injectBeforeTagWithFallback(html: string, code: string, _fallbackMessage?: string): HtmlInjectResult & {
+    usedFallback: boolean;
+};
+/**
+ * 双区域 HTML 注入（head + body）
+ *
+ * @description 将代码分别注入到 HTML 的 `</head>` 前和 `</body>` 前（带回退策略）。
+ * 这是插件中常见的注入模式：CSS/HTML 注入到 head，JS 注入到 body。
+ *
+ * @param html - 原始 HTML 内容
+ * @param headCode - 注入到 `</head>` 前的代码（如 CSS、meta 标签），不提供则跳过 head 注入
+ * @param bodyCode - 注入到 `</body>` 前的代码（如 JS 脚本），回退到 `</html>` 前或末尾
+ * @returns 双区域注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // CSS 注入到 head，JS 注入到 body
+ * const result = injectHeadAndBody(html, '<style>...</style>', '<script>...</script>')
+ * if (!result.headInjected) logger.warn('未找到 </head> 标签')
+ * if (result.usedFallback) logger.warn('代码追加到文件末尾')
+ *
+ * // 仅注入到 body
+ * const result = injectHeadAndBody(html, undefined, '<script>...</script>')
+ * ```
+ */
+declare function injectHeadAndBody(html: string, headCode: string | undefined, bodyCode: string): DualInjectResult;
+
+export { injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority };
+export type { DualInjectResult, HtmlInjectResult };

package/dist/common/html/index.d.mts

@@ -0,0 +1,109 @@
+/**
+ * HTML 注入结果
+ */
+interface HtmlInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** 是否成功注入 */
+    injected: boolean;
+}
+/**
+ * 双区域 HTML 注入结果
+ */
+interface DualInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** head 区域是否成功注入 */
+    headInjected: boolean;
+    /** body 区域是否成功注入 */
+    bodyInjected: boolean;
+    /** body 注入是否使用了回退策略（追加到末尾） */
+    usedFallback: boolean;
+}
+
+/**
+ * 在 HTML 中指定闭合标签前注入代码
+ *
+ * @param html - 原始 HTML 内容
+ * @param tag - 目标闭合标签（如 `</head>`、`</body>`、`</html>`）
+ * @param code - 要注入的代码
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 在 </head> 前注入 CSS
+ * const result = injectBeforeTag(html, '</head>', '<style>...</style>')
+ *
+ * // 在 </body> 前注入 JS
+ * const result = injectBeforeTag(html, '</body>', '<script>...</script>')
+ * ```
+ */
+declare function injectBeforeTag(html: string, tag: string, code: string): HtmlInjectResult;
+/**
+ * 按优先级向 HTML 中注入代码
+ *
+ * @description 依次尝试在 `</head>`、`</body>`、`</html>` 前注入代码，
+ * 优先注入到靠前的标签位置。适用于需要注入到页面中但无特定位置要求的场景
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param targets - 目标标签优先级列表，默认为 `['</head>', '</body>', '</html>']`
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 优先注入到 </body> 前
+ * const result = injectHtmlByPriority(html, scriptCode, ['</body>', '</html>'])
+ * ```
+ */
+declare function injectHtmlByPriority(html: string, code: string, targets?: string[]): HtmlInjectResult;
+/**
+ * 带回退策略的 HTML 注入
+ *
+ * @description 依次尝试在 `</body>`、`</html>` 前注入代码，
+ * 如果均未找到目标标签，则将代码追加到 HTML 末尾。
+ * 适用于需要注入到页面底部但不确定 HTML 结构是否完整的场景。
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param fallbackMessage - 回退到末尾时的警告信息，为空则不输出警告
+ * @returns 注入结果对象，包含注入后的 HTML、是否成功标志和是否使用了回退策略
+ *
+ * @example
+ * ```typescript
+ * // 注入 JS 脚本到页面底部
+ * const result = injectBeforeTagWithFallback(html, '<script>...</script>')
+ *
+ * // 带自定义警告信息
+ * const result = injectBeforeTagWithFallback(html, scriptCode, '未找到 </body> 标签，代码追加到文件末尾')
+ * ```
+ */
+declare function injectBeforeTagWithFallback(html: string, code: string, _fallbackMessage?: string): HtmlInjectResult & {
+    usedFallback: boolean;
+};
+/**
+ * 双区域 HTML 注入（head + body）
+ *
+ * @description 将代码分别注入到 HTML 的 `</head>` 前和 `</body>` 前（带回退策略）。
+ * 这是插件中常见的注入模式：CSS/HTML 注入到 head，JS 注入到 body。
+ *
+ * @param html - 原始 HTML 内容
+ * @param headCode - 注入到 `</head>` 前的代码（如 CSS、meta 标签），不提供则跳过 head 注入
+ * @param bodyCode - 注入到 `</body>` 前的代码（如 JS 脚本），回退到 `</html>` 前或末尾
+ * @returns 双区域注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // CSS 注入到 head，JS 注入到 body
+ * const result = injectHeadAndBody(html, '<style>...</style>', '<script>...</script>')
+ * if (!result.headInjected) logger.warn('未找到 </head> 标签')
+ * if (result.usedFallback) logger.warn('代码追加到文件末尾')
+ *
+ * // 仅注入到 body
+ * const result = injectHeadAndBody(html, undefined, '<script>...</script>')
+ * ```
+ */
+declare function injectHeadAndBody(html: string, headCode: string | undefined, bodyCode: string): DualInjectResult;
+
+export { injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority };
+export type { DualInjectResult, HtmlInjectResult };

package/dist/common/html/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * HTML 注入结果
+ */
+interface HtmlInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** 是否成功注入 */
+    injected: boolean;
+}
+/**
+ * 双区域 HTML 注入结果
+ */
+interface DualInjectResult {
+    /** 注入后的 HTML 内容 */
+    html: string;
+    /** head 区域是否成功注入 */
+    headInjected: boolean;
+    /** body 区域是否成功注入 */
+    bodyInjected: boolean;
+    /** body 注入是否使用了回退策略（追加到末尾） */
+    usedFallback: boolean;
+}
+
+/**
+ * 在 HTML 中指定闭合标签前注入代码
+ *
+ * @param html - 原始 HTML 内容
+ * @param tag - 目标闭合标签（如 `</head>`、`</body>`、`</html>`）
+ * @param code - 要注入的代码
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 在 </head> 前注入 CSS
+ * const result = injectBeforeTag(html, '</head>', '<style>...</style>')
+ *
+ * // 在 </body> 前注入 JS
+ * const result = injectBeforeTag(html, '</body>', '<script>...</script>')
+ * ```
+ */
+declare function injectBeforeTag(html: string, tag: string, code: string): HtmlInjectResult;
+/**
+ * 按优先级向 HTML 中注入代码
+ *
+ * @description 依次尝试在 `</head>`、`</body>`、`</html>` 前注入代码，
+ * 优先注入到靠前的标签位置。适用于需要注入到页面中但无特定位置要求的场景
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param targets - 目标标签优先级列表，默认为 `['</head>', '</body>', '</html>']`
+ * @returns 注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // 优先注入到 </body> 前
+ * const result = injectHtmlByPriority(html, scriptCode, ['</body>', '</html>'])
+ * ```
+ */
+declare function injectHtmlByPriority(html: string, code: string, targets?: string[]): HtmlInjectResult;
+/**
+ * 带回退策略的 HTML 注入
+ *
+ * @description 依次尝试在 `</body>`、`</html>` 前注入代码，
+ * 如果均未找到目标标签，则将代码追加到 HTML 末尾。
+ * 适用于需要注入到页面底部但不确定 HTML 结构是否完整的场景。
+ *
+ * @param html - 原始 HTML 内容
+ * @param code - 要注入的代码
+ * @param fallbackMessage - 回退到末尾时的警告信息，为空则不输出警告
+ * @returns 注入结果对象，包含注入后的 HTML、是否成功标志和是否使用了回退策略
+ *
+ * @example
+ * ```typescript
+ * // 注入 JS 脚本到页面底部
+ * const result = injectBeforeTagWithFallback(html, '<script>...</script>')
+ *
+ * // 带自定义警告信息
+ * const result = injectBeforeTagWithFallback(html, scriptCode, '未找到 </body> 标签，代码追加到文件末尾')
+ * ```
+ */
+declare function injectBeforeTagWithFallback(html: string, code: string, _fallbackMessage?: string): HtmlInjectResult & {
+    usedFallback: boolean;
+};
+/**
+ * 双区域 HTML 注入（head + body）
+ *
+ * @description 将代码分别注入到 HTML 的 `</head>` 前和 `</body>` 前（带回退策略）。
+ * 这是插件中常见的注入模式：CSS/HTML 注入到 head，JS 注入到 body。
+ *
+ * @param html - 原始 HTML 内容
+ * @param headCode - 注入到 `</head>` 前的代码（如 CSS、meta 标签），不提供则跳过 head 注入
+ * @param bodyCode - 注入到 `</body>` 前的代码（如 JS 脚本），回退到 `</html>` 前或末尾
+ * @returns 双区域注入结果对象
+ *
+ * @example
+ * ```typescript
+ * // CSS 注入到 head，JS 注入到 body
+ * const result = injectHeadAndBody(html, '<style>...</style>', '<script>...</script>')
+ * if (!result.headInjected) logger.warn('未找到 </head> 标签')
+ * if (result.usedFallback) logger.warn('代码追加到文件末尾')
+ *
+ * // 仅注入到 body
+ * const result = injectHeadAndBody(html, undefined, '<script>...</script>')
+ * ```
+ */
+declare function injectHeadAndBody(html: string, headCode: string | undefined, bodyCode: string): DualInjectResult;
+
+export { injectBeforeTag, injectBeforeTagWithFallback, injectHeadAndBody, injectHtmlByPriority };
+export type { DualInjectResult, HtmlInjectResult };

package/dist/common/html/index.mjs

@@ -0,0 +1,2 @@
+function d(e,t,l){const n=new RegExp(t,"i");return n.test(e)?{html:e.replace(n,`${l}
+${t}`),injected:!0}:{html:e,injected:!1}}function o(e,t,l=["</head>","</body>","</html>"]){for(const n of l){const c=d(e,n,t);if(c.injected)return c}return{html:e+t,injected:!0}}function a(e,t,l){const n=d(e,"</body>",t);if(n.injected)return{...n,usedFallback:!1};const c=d(e,"</html>",t);return c.injected?{...c,usedFallback:!1}:{html:e+t,injected:!0,usedFallback:!0}}function u(e,t,l){let n=e,c=!1;if(t){const i=d(n,"</head>",t);i.injected&&(n=i.html,c=!0)}const r=a(n,l);return{html:r.html,headInjected:c,bodyInjected:r.injected,usedFallback:r.usedFallback}}export{d as injectBeforeTag,a as injectBeforeTagWithFallback,u as injectHeadAndBody,o as injectHtmlByPriority};

package/dist/common/index.cjs

@@ -1 +1 @@
-"use strict";const script=require("../shared/vite-plugin.Tab4qcIM.cjs"),validation=require("../shared/vite-plugin.IGZeStMa.cjs");require("fs"),require("path"),require("crypto"),exports.checkSourceExists=script.checkSourceExists,exports.containsScriptTag=script.containsScriptTag,exports.copySourceToTarget=script.copySourceToTarget,exports.ensureTargetDir=script.ensureTargetDir,exports.fileExists=script.fileExists,exports.formatDate=script.formatDate,exports.generateRandomHash=script.generateRandomHash,exports.getDateFormatParams=script.getDateFormatParams,exports.injectBeforeTag=script.injectBeforeTag,exports.injectHtmlByPriority=script.injectHtmlByPriority,exports.makeCallback=script.makeCallback,exports.padNumber=script.padNumber,exports.parseTemplate=script.parseTemplate,exports.readDirRecursive=script.readDirRecursive,exports.readFileContent=script.readFileContent,exports.readFileSync=script.readFileSync,exports.runWithConcurrency=script.runWithConcurrency,exports.shouldUpdateFile=script.shouldUpdateFile,exports.stripJsonComments=script.stripJsonComments,exports.toCamelCase=script.toCamelCase,exports.toPascalCase=script.toPascalCase,exports.validateIdentifierName=script.validateIdentifierName,exports.writeFileContent=script.writeFileContent,exports.Validator=validation.Validator,exports.deepMerge=validation.deepMerge;
+"use strict";const common_fs_index=require("./fs/index.cjs"),common_format_index=require("./format/index.cjs"),common_html_index=require("./html/index.cjs"),common_object_index=require("./object/index.cjs"),common_script_index=require("./script/index.cjs"),validator=require("../shared/vite-plugin.Bcg6RW2N.cjs"),common_validation_index=require("./validation/index.cjs");require("fs"),require("path"),require("crypto"),exports.checkSourceExists=common_fs_index.checkSourceExists,exports.copySourceToTarget=common_fs_index.copySourceToTarget,exports.ensureTargetDir=common_fs_index.ensureTargetDir,exports.fileExists=common_fs_index.fileExists,exports.readDirRecursive=common_fs_index.readDirRecursive,exports.readFileContent=common_fs_index.readFileContent,exports.readFileSync=common_fs_index.readFileSync,exports.runWithConcurrency=common_fs_index.runWithConcurrency,exports.shouldUpdateFile=common_fs_index.shouldUpdateFile,exports.writeFileContent=common_fs_index.writeFileContent,exports.escapeHtmlAttr=common_format_index.escapeHtmlAttr,exports.formatDate=common_format_index.formatDate,exports.generateRandomHash=common_format_index.generateRandomHash,exports.getDateFormatParams=common_format_index.getDateFormatParams,exports.padNumber=common_format_index.padNumber,exports.parseTemplate=common_format_index.parseTemplate,exports.stripJsonComments=common_format_index.stripJsonComments,exports.toCamelCase=common_format_index.toCamelCase,exports.toPascalCase=common_format_index.toPascalCase,exports.injectBeforeTag=common_html_index.injectBeforeTag,exports.injectBeforeTagWithFallback=common_html_index.injectBeforeTagWithFallback,exports.injectHeadAndBody=common_html_index.injectHeadAndBody,exports.injectHtmlByPriority=common_html_index.injectHtmlByPriority,exports.deepMerge=common_object_index.deepMerge,exports.containsScriptTag=common_script_index.containsScriptTag,exports.makeCallback=common_script_index.makeCallback,exports.validateIdentifierName=common_script_index.validateIdentifierName,exports.Validator=validator.Validator,exports.validateCallbackFields=common_validation_index.validateCallbackFields,exports.validateEnumValue=common_validation_index.validateEnumValue,exports.validateGlobalName=common_validation_index.validateGlobalName,exports.validateNestedDuration=common_validation_index.validateNestedDuration,exports.validateNoScriptInTemplate=common_validation_index.validateNoScriptInTemplate,exports.validateNonNegativeNumber=common_validation_index.validateNonNegativeNumber;