vite-plugin-cus-svg-icon 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# vite-plugin-svg-icon
+
+一个轻量的 Vite 插件，只处理本地 SVG 图标，并尽量对齐 UnoCSS `preset-icons` 的使用方式与输出风格。
+
+## 特性
+
+- 仅处理本地 SVG，不依赖 UnoCSS
+- 支持 UnoCSS 风格的 `prefix`、`collections`、`FileSystemIconLoader`、`addCurrentFill`
+- 内部已集成 `@iconify/utils`，无需在业务项目中额外单独安装和导入
+- 默认类名前缀为 `i-`，支持自定义和多前缀
+- 支持 `safelist`
+- 支持 `extraProperties`
+- 支持 `scale`、`unit`
+- 支持 `mode: 'mask' | 'bg' | 'auto'`
+- 支持 SVG 大小阈值控制，默认超过 `10KB` 不注入 CSS，并输出警告
+- 开发环境按 Vite 已加载模块增量扫描
+- 构建阶段按配置范围全量扫描源码文本，不做 AST 解析
+
+## 安装
+
+```bash
+npm install vite-plugin-svg-icon
+```
+
+## 使用方式
+
+```ts
+import { defineConfig } from "vite";
+import { svgIconPlugin } from "vite-plugin-svg-icon";
+
+export default defineConfig({
+  plugins: [
+    svgIconPlugin({
+      // 必填：定义本地图标集合
+      collections: {
+        // 简洁写法：仅配置 path 即可
+        svg: {
+          path: "src/assets/icons",
+        },
+        // 目录级 safelist，适合动态拼接类名的目录
+        svgDy: {
+          path: "src/assets/icons-dynamic",
+          safelist: true,
+        },
+      },
+    }),
+  ],
+});
+```
+
+在应用入口引入虚拟样式：
+
+```ts
+import "virtual:svg-icon.css";
+```
+
+然后在模板或字符串中直接使用类名：
+
+```html
+<span class="i-svg:home"></span>
+<span class="i-svg:user-add"></span>
+<span class="i-svgDy:logo"></span>
+<span class="i-svgDy:rainbow"></span>
+<span class="i-svgDy:rainbow?mask"></span>
+```
+
+如果图标目录下存在 `home.svg` 与 `user/add.svg`，就会分别生成对应的 CSS。
+
+## 本地 Collections
+
+### 推荐简洁的 collection 对象写法：
+
+```ts
+import { svgIconPlugin } from "vite-plugin-svg-icon";
+
+svgIconPlugin({
+  collections: {
+    svg: {
+      path: "src/assets/icons",
+    },
+    svgDy: {
+      path: "src/assets/icons-dynamic",
+      safelist: true,
+    },
+  },
+});
+```
+
+- `path`：本地图标目录
+- `transform` / `fn`：可选 SVG 处理函数
+- `autoFillCurrentColor`：默认 `true`，会自动在根 `<svg>` 上补 `fill="currentColor"`，若已有 `fill` 则保持不变
+- `safelist: true`：自动保留该目录下所有图标，适合动态图标目录
+
+### 也支持与 UnoCSS 接近的写法：
+
+```ts
+import {
+  FileSystemIconLoader,
+  addCurrentFill,
+  svgIconPlugin,
+} from "vite-plugin-svg-icon";
+
+svgIconPlugin({
+  collections: {
+    svg: FileSystemIconLoader("src/assets/icons", addCurrentFill),
+    svgDy: FileSystemIconLoader("src/assets/icons-dynamic", addCurrentFill),
+  },
+});
+```
+
+- `FileSystemIconLoader(dir, transform?)`：从本地目录懒加载 SVG
+- `addCurrentFill(svg)`：给未声明 `fill` 的根 `<svg>` 注入 `fill="currentColor"`，适合单色图标
+- 目录中的 `user/add.svg` 会映射为 `user-add`
+
+## Demo
+
+仓库根目录提供了一个基于最新 `create-vite` 生成的 `demo` 项目，用于真实验证插件行为：
+
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+如果你希望直接在仓库根目录执行完整验证，可以运行：
+
+```bash
+npm run verify
+```
+
+这个命令会自动完成：
+
+- 插件源码类型检查
+- 插件单元测试
+- 插件构建
+- `demo` 构建验证
+- `demo` 开发服务器启动与虚拟 CSS 内容校验
+- 超过 `10KB` 的 SVG 警告校验
+
+## 配置项
+
+```ts
+interface SvgIconPluginOptions {
+  collections: Record<string, IconCollection>; // 必填：图标集合定义
+  prefix?: string | string[]; // 类名前缀，默认 'i-'
+  virtualModuleId?: string; // 虚拟 CSS 模块 ID，默认 'virtual:svg-icon.css'
+  scale?: number; // 图标尺寸缩放，默认 1
+  unit?: string; // 尺寸单位，默认 'em'
+  mode?: "mask" | "bg" | "auto"; // 默认渲染模式，默认 'auto'
+  maxSvgSize?: number; // SVG 大小上限（字节），默认 10 * 1024
+  contentInclude?: string[]; // 构建期扫描包含范围（glob）
+  contentExclude?: string[]; // 构建期扫描排除范围（glob）
+  safelist?: string[]; // 顶层保留类名（仍然有效）
+  extraProperties?: Record<string, string>; // 追加到所有图标规则的公共 CSS
+}
+```
+
+其中 `collections` 支持三种形式：
+
+```ts
+collections: {
+  svg: FileSystemIconLoader('src/icons', addCurrentFill),
+  svgDy: {
+    path: 'src/icons-dynamic',
+    safelist: true,
+  },
+  inline: {
+    home: '<svg viewBox="0 0 24 24"><path fill="currentColor" d="..." /></svg>',
+  },
+}
+```
+
+### `scale`
+
+- 类型：`number`
+- 默认值：`1`
+- 含义：按当前字体大小 `1em` 缩放图标
+- 输出方式：直接作用于生成 CSS 的 `width` 和 `height`，不会额外引入尺寸变量
+
+### `mode`
+
+- `mask`：单色图标，使用 `mask` / `-webkit-mask`
+- `bg`：背景图模式，保留 SVG 原始颜色
+- `auto`：默认值；检测到多色、渐变、pattern、image 等复杂着色时自动退化为背景图模式
+
+### `extraProperties`
+
+与 UnoCSS 一样，可以给所有图标附加公共 CSS 属性，例如：
+
+```ts
+extraProperties: {
+  display: 'inline-block',
+  'vertical-align': 'middle',
+}
+```
+
+## 扫描策略
+
+- 开发环境：在 `transform` / `transformIndexHtml` 中扫描当前被 Vite 处理的源码文本，只更新受影响文件的图标集合
+- 生产构建：在虚拟 CSS 模块加载时，对 `contentInclude` 范围进行并发全量扫描
+- 提取方式：直接把源码当纯文本处理，通过前缀和 collection 解析候选类名，不解析 AST
+- 兼容类似 `hover:i-svg:home`、`dark:i-svgDy:bell?bg` 的变体写法
+- 对 `safelist: true` 的文件系统 collection，插件会直接基于目录索引生成保留项，不需要用户手写 `readdirSync()`
+- 开发环境会监听文件系统 collection 目录中的 SVG 新增、删除与修改，并自动刷新虚拟 CSS
+
+## 性能设计
+
+- 增量扫描：开发环境只处理当前被 Vite 触达或变更的源码文件，不在启动时扫描整个项目
+- 轻量指纹：源码变更判断使用内容指纹而不是热路径上的 `fs.stat()`，这不仅在超大项目里有意义，在中小项目的高频 HMR 场景下同样能减少系统调用
+- 快速失败：源码文本在进入正则提取前，会先检查是否包含任一图标前缀，避免大量无关文件进入完整扫描
+- 并发去重：文件系统 collection 使用 `refreshPromise` 合并并发刷新；单个图标加载也会做 in-flight 去重，避免重复读取同一个 SVG
+- 原子替换：collection 刷新时先构建新索引，再一次性替换旧索引，避免并发读取时看到 `clear()` 后的中间态
+- 增量 usage 索引：源码图标使用关系按文件差量维护，虚拟 CSS 重建时直接消费当前活跃 usage，而不是每次重新合并全部扫描结果
+
+## 生成样式
+
+生成结果参考 UnoCSS 的图标输出结构：
+
+```css
+.i-svg\:home {
+  --svg-c-icon: url("data:image/svg+xml;utf8,...");
+}
+
+.i-svg\:home {
+  -webkit-mask: var(--svg-c-icon) no-repeat;
+  mask: var(--svg-c-icon) no-repeat;
+  -webkit-mask-size: 100% 100%;
+  mask-size: 100% 100%;
+  background-color: currentColor;
+  color: inherit;
+  width: 1em;
+  height: 1em;
+}
+```
+
+## 限制
+
+- 当前只处理本地 collections，不处理第三方图标集下载
+- 嵌套目录会被展开为连字符，例如 `user/add.svg -> i-svg:user-add`
+- `auto` 模式采用启发式判断多色 SVG，极少数边缘 SVG 仍建议手动使用 `?mask` / `?bg`

package/dist/core.d.ts

@@ -0,0 +1,34 @@
+import type { CustomIconLoader, IconMode, IconRecord, LoadedIconSource, ParsedIconUsage, ResolvedSvgIconPluginOptions, SvgIconPluginOptions } from './types';
+/** 解析并规范化插件配置，包括 collections 与各项默认值。 */
+export declare function resolveOptions(options: SvgIconPluginOptions, root: string): Promise<ResolvedSvgIconPluginOptions>;
+/** 二次暴露 Iconify 的文件系统 loader，并附加本插件内部需要的元信息。 */
+export declare function FileSystemIconLoader(dir: string, transform?: (svg: string) => string | Promise<string>): CustomIconLoader;
+/** 当根 svg 尚未声明 fill 时，为其补上 fill="currentColor"。 */
+export declare function addCurrentFill(svg: string): string;
+/** 将相对 svg 文件路径转换为类名匹配阶段使用的规范化图标名。 */
+export declare function normalizeIconName(relativeFilePath: string): string;
+/** 将 collection 级别的自动 safelist 扩展为标准图标类使用记录。 */
+export declare function extractCollectionSafelistUsages(options: Pick<ResolvedSvgIconPluginOptions, 'collections' | 'prefixes'>): Map<string, ParsedIconUsage>;
+/** 直接从任意源码文本中提取图标使用记录，不依赖 AST 解析。 */
+export declare function extractIconUsagesFromCode(code: string, options: Pick<ResolvedSvgIconPluginOptions, 'prefixes' | 'collections' | 'mode'>): Map<string, ParsedIconUsage>;
+/** 从配置中的 safelist 条目里提取图标使用记录。 */
+export declare function extractIconUsagesFromSafelist(entries: string[], options: Pick<ResolvedSvgIconPluginOptions, 'prefixes' | 'collections' | 'mode'>): Map<string, ParsedIconUsage>;
+/** 构建规范化的图标记录，供大小判断、mode 决策与 CSS 生成复用。 */
+export declare function createIconRecord(collection: string, icon: string, source: LoadedIconSource, maxSvgSize: number): IconRecord;
+/** 按 mask/bg 渲染模式分组，为已解析的图标使用记录生成 CSS 规则。 */
+export declare function generateCss(entries: Array<{
+    usage: ParsedIconUsage;
+    icon: IconRecord;
+    mode: Exclude<IconMode, 'auto'>;
+}>, options: Pick<ResolvedSvgIconPluginOptions, 'scale' | 'unit' | 'extraProperties'>): string;
+/** 解析最终渲染模式；当 mode 为 auto 时会自动判断是否应退化为 bg。 */
+export declare function resolveIconRenderMode(svg: string, mode: IconMode): Exclude<IconMode, 'auto'>;
+/** 判断文件路径是否位于给定目录集合中的任意目录下。 */
+export declare function isFileInDirectories(filePath: string, directories: string[]): boolean;
+/** 使用 Iconify 的序列化器将 SVG 转为优化过的 data URL。 */
+export declare function toSvgDataUri(svg: string): string;
+/** 将 Windows 路径统一转换为斜杠形式，便于内部稳定比较。 */
+export declare function normalizeSlashes(value: string): string;
+/** 去掉 Vite 模块 id 上附带的 query 与 hash 后缀。 */
+export declare function stripQuery(id: string): string;
+export type { IconMode, SvgIconPluginOptions } from './types';

package/dist/core.js

@@ -0,0 +1,425 @@
+import path from 'node:path';
+import { glob } from 'tinyglobby';
+import { FileSystemIconLoader as IconifyFileSystemIconLoader } from '@iconify/utils/lib/loader/node-loaders';
+import { svgToData as iconifySvgToData } from '@iconify/utils/lib/svg/url';
+const DEFAULT_CONTENT_INCLUDE = ['**/*.{html,js,ts,jsx,tsx,vue,md,mdx,astro,svelte}'];
+const DEFAULT_CONTENT_EXCLUDE = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/*.svg',
+    '**/*.{png,jpg,jpeg,gif,webp,avif,ico,woff,woff2,ttf,eot,mp4,mp3,pdf,zip}',
+];
+const SVG_MODE_SUFFIX = /(?:\?(mask|bg|auto))$/;
+const TOKEN_MATCHER = /[A-Za-z0-9_:?-]+/g;
+/** 解析并规范化插件配置，包括 collections 与各项默认值。 */
+export async function resolveOptions(options, root) {
+    const prefixes = toArray(options.prefix ?? 'i-')
+        .map((prefix) => prefix.trim())
+        .filter(Boolean);
+    const collections = new Map();
+    for (const [name, collection] of Object.entries(options.collections)) {
+        collections.set(name, await resolveCollection(name, collection, root));
+    }
+    return {
+        collections,
+        prefixes,
+        virtualModuleId: options.virtualModuleId?.trim() || 'virtual:svg-icon.css',
+        resolvedVirtualModuleId: `\0${options.virtualModuleId?.trim() || 'virtual:svg-icon.css'}`,
+        scale: options.scale ?? 1,
+        unit: options.unit?.trim() || 'em',
+        mode: options.mode ?? 'auto',
+        maxSvgSize: options.maxSvgSize ?? 10 * 1024,
+        contentInclude: options.contentInclude?.length
+            ? options.contentInclude
+            : DEFAULT_CONTENT_INCLUDE,
+        contentExclude: options.contentExclude?.length
+            ? options.contentExclude
+            : DEFAULT_CONTENT_EXCLUDE,
+        safelist: options.safelist ?? [],
+        extraProperties: options.extraProperties ?? {},
+        root,
+    };
+}
+/** 二次暴露 Iconify 的文件系统 loader，并附加本插件内部需要的元信息。 */
+export function FileSystemIconLoader(dir, transform) {
+    const loader = IconifyFileSystemIconLoader(dir, transform);
+    loader.__svgIconLoaderMeta = {
+        kind: 'fs',
+        dir,
+        transform,
+    };
+    return loader;
+}
+/** 当根 svg 尚未声明 fill 时，为其补上 fill="currentColor"。 */
+export function addCurrentFill(svg) {
+    if (/fill\s*=\s*['"]currentColor['"]/i.test(svg)) {
+        return svg;
+    }
+    // 对齐 UnoCSS 本地 collection 的用法，让单色图标默认继承文本颜色。
+    return svg.replace(/<svg\b([^>]*)>/i, (match, attrs) => {
+        if (/\sfill\s*=/.test(attrs)) {
+            return match;
+        }
+        return `<svg${attrs} fill="currentColor">`;
+    });
+}
+/** 将相对 svg 文件路径转换为类名匹配阶段使用的规范化图标名。 */
+export function normalizeIconName(relativeFilePath) {
+    return stripExtension(relativeFilePath)
+        .split(/[\\/]+/)
+        .map((segment) => segment.trim().replace(/[^a-zA-Z0-9_-]+/g, '-'))
+        .filter(Boolean)
+        .join('-');
+}
+/** 将 collection 级别的自动 safelist 扩展为标准图标类使用记录。 */
+export function extractCollectionSafelistUsages(options) {
+    const usages = new Map();
+    const prefix = options.prefixes[0];
+    for (const [collectionName, collection] of options.collections) {
+        if (!collection.autoSafelist || !collection.sortedIconNames)
+            continue;
+        for (const iconName of collection.sortedIconNames) {
+            const className = `${prefix}${collectionName}:${iconName}`;
+            usages.set(className, {
+                className,
+                collection: collectionName,
+                icon: iconName,
+                mode: 'auto',
+            });
+        }
+    }
+    return usages;
+}
+/** 直接从任意源码文本中提取图标使用记录，不依赖 AST 解析。 */
+export function extractIconUsagesFromCode(code, options) {
+    const usages = new Map();
+    if (!options.prefixes.some((prefix) => code.includes(prefix))) {
+        return usages;
+    }
+    for (const token of code.match(TOKEN_MATCHER) ?? []) {
+        const usage = parseIconUsage(token, options);
+        if (usage) {
+            usages.set(usage.className, usage);
+        }
+    }
+    return usages;
+}
+/** 从配置中的 safelist 条目里提取图标使用记录。 */
+export function extractIconUsagesFromSafelist(entries, options) {
+    const usages = new Map();
+    for (const entry of entries) {
+        const value = entry.trim();
+        if (!value)
+            continue;
+        const usage = parseIconUsage(value, options) ||
+            parseIconUsage(`${options.prefixes[0]}${value}`, options);
+        if (usage) {
+            usages.set(usage.className, usage);
+        }
+    }
+    return usages;
+}
+/** 构建规范化的图标记录，供大小判断、mode 决策与 CSS 生成复用。 */
+export function createIconRecord(collection, icon, source, maxSvgSize) {
+    const cleanedSvg = cleanupSvg(source.svg);
+    const size = Buffer.byteLength(cleanedSvg);
+    return {
+        collection,
+        icon,
+        filePath: source.filePath,
+        svg: cleanedSvg,
+        size,
+        oversize: size > maxSvgSize,
+        dataUri: size > maxSvgSize ? undefined : toSvgDataUri(cleanedSvg),
+    };
+}
+/** 按 mask/bg 渲染模式分组，为已解析的图标使用记录生成 CSS 规则。 */
+export function generateCss(entries, options) {
+    const maskSelectors = [];
+    const bgSelectors = [];
+    const variableRules = [];
+    for (const entry of entries) {
+        const selector = `.${escapeClassName(entry.usage.className)}`;
+        // 每个类只保存一次 SVG 数据，再由共享规则通过 --svg-c-icon 引用。
+        variableRules.push(`${selector}{--svg-c-icon:url("${entry.icon.dataUri}");}`);
+        if (entry.mode === 'mask') {
+            maskSelectors.push(selector);
+        }
+        else {
+            bgSelectors.push(selector);
+        }
+    }
+    const rules = [];
+    if (maskSelectors.length) {
+        rules.push(createSharedRule(maskSelectors, 'mask', options));
+    }
+    if (bgSelectors.length) {
+        rules.push(createSharedRule(bgSelectors, 'bg', options));
+    }
+    rules.push(...variableRules);
+    return rules.join('\n');
+}
+/** 解析最终渲染模式；当 mode 为 auto 时会自动判断是否应退化为 bg。 */
+export function resolveIconRenderMode(svg, mode) {
+    if (mode !== 'auto') {
+        return mode;
+    }
+    // 多色或带渐变的 SVG 使用背景图模式更安全，避免 mask 丢失颜色信息。
+    if (hasComplexPaint(svg)) {
+        return 'bg';
+    }
+    return 'mask';
+}
+/** 判断文件路径是否位于给定目录集合中的任意目录下。 */
+export function isFileInDirectories(filePath, directories) {
+    const normalizedFile = normalizeSlashes(path.resolve(filePath));
+    return directories.some((dir) => normalizedFile.startsWith(normalizeSlashes(path.resolve(dir)) + '/'));
+}
+/** 使用 Iconify 的序列化器将 SVG 转为优化过的 data URL。 */
+export function toSvgDataUri(svg) {
+    // 直接复用 Iconify 的优化实现，使输出更接近其生态行为。
+    return iconifySvgToData(svg);
+}
+/** 将 Windows 路径统一转换为斜杠形式，便于内部稳定比较。 */
+export function normalizeSlashes(value) {
+    return value.replace(/\\/g, '/');
+}
+/** 去掉 Vite 模块 id 上附带的 query 与 hash 后缀。 */
+export function stripQuery(id) {
+    return id.replace(/[?#].*$/, '');
+}
+/** 将单个 token 解析为具体的图标使用记录，兼容连接符与冒号两种写法。 */
+function parseIconUsage(token, options) {
+    const className = token.trim();
+    if (!className)
+        return null;
+    const collectionNames = [...options.collections.keys()].sort((left, right) => right.length - left.length);
+    const candidates = [className, ...getVariantCandidates(className)];
+    for (const candidate of candidates) {
+        let requestedMode = options.mode;
+        let baseName = candidate;
+        const modeMatch = baseName.match(SVG_MODE_SUFFIX);
+        if (modeMatch?.[1]) {
+            requestedMode = modeMatch[1];
+            baseName = baseName.slice(0, -modeMatch[0].length);
+        }
+        for (const prefix of options.prefixes) {
+            if (!baseName.startsWith(prefix))
+                continue;
+            const rest = baseName.slice(prefix.length);
+            for (const collection of collectionNames) {
+                if (rest.startsWith(`${collection}:`)) {
+                    const icon = rest.slice(collection.length + 1);
+                    if (icon) {
+                        return { className: candidate, collection, icon, mode: requestedMode };
+                    }
+                }
+                if (rest.startsWith(`${collection}-`)) {
+                    const icon = rest.slice(collection.length + 1);
+                    if (icon) {
+                        return { className: candidate, collection, icon, mode: requestedMode };
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+/** 将任意支持的 collection 输入形式统一解析为内部 loader 抽象。 */
+async function resolveCollection(name, collection, root) {
+    if (isFileSystemCollectionConfig(collection)) {
+        const transform = composeTransforms(collection.autoFillCurrentColor === false ? undefined : addCurrentFill, collection.transform ?? collection.fn);
+        return resolveFileSystemCollection(name, collection.path, root, transform, collection.safelist ?? false);
+    }
+    if (typeof collection === 'function' && collection.__svgIconLoaderMeta?.kind === 'fs') {
+        return resolveFileSystemCollection(name, collection.__svgIconLoaderMeta.dir, root, collection.__svgIconLoaderMeta.transform, false, collection);
+    }
+    if (typeof collection === 'function') {
+        return {
+            name,
+            load: async (iconName) => {
+                const svg = await collection(iconName);
+                return svg ? { svg } : null;
+            },
+        };
+    }
+    return {
+        name,
+        load: async (iconName) => {
+            const source = collection[iconName];
+            if (!source)
+                return null;
+            return {
+                svg: typeof source === 'function' ? await source() : source,
+            };
+        },
+    };
+}
+/** 构建可刷新的文件系统 collection 索引，并委托 Iconify loader 读取 SVG。 */
+async function resolveFileSystemCollection(name, dir, root, transform, autoSafelist = false, loader = FileSystemIconLoader(path.resolve(root, dir), transform)) {
+    const fsDir = path.resolve(root, dir);
+    let iconToFile = new Map();
+    let refreshPromise = null;
+    const collection = {
+        name,
+        autoSafelist,
+        fsDir,
+        normalizedFsDir: normalizeSlashes(fsDir),
+        fileToIconName: new Map(),
+        sortedIconNames: [],
+        refresh: async () => {
+            if (refreshPromise) {
+                return refreshPromise;
+            }
+            refreshPromise = (async () => {
+                const files = await glob('**/*.svg', {
+                    cwd: fsDir,
+                    absolute: true,
+                });
+                const nextIconToFile = new Map();
+                const nextFileToIconName = new Map();
+                for (const file of files) {
+                    const relativeFilePath = normalizeSlashes(path.relative(fsDir, file));
+                    const iconName = normalizeIconName(relativeFilePath);
+                    nextIconToFile.set(iconName, file);
+                    nextFileToIconName.set(normalizeSlashes(path.resolve(file)), iconName);
+                }
+                iconToFile = nextIconToFile;
+                collection.fileToIconName = nextFileToIconName;
+                collection.sortedIconNames = [...nextIconToFile.keys()].sort();
+            })().finally(() => {
+                refreshPromise = null;
+            });
+            return refreshPromise;
+        },
+        load: async (iconName) => {
+            let filePath = iconToFile.get(iconName);
+            if (!filePath) {
+                await collection.refresh?.();
+                filePath = iconToFile.get(iconName);
+            }
+            if (!filePath)
+                return null;
+            const svg = await loader(iconName);
+            if (!svg)
+                return null;
+            return {
+                svg,
+                filePath: normalizeSlashes(path.resolve(filePath)),
+            };
+        },
+    };
+    await collection.refresh?.();
+    return collection;
+}
+/** 在 mode 判断与 data-url 序列化前，对 SVG 做轻量清理。 */
+function cleanupSvg(svg) {
+    return svg
+        .replace(/<\?xml[\s\S]*?\?>/g, '')
+        .replace(/<!DOCTYPE[\s\S]*?>/gi, '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/\r?\n|\r/g, ' ')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/** 为 mask 模式或 bg 模式的选择器生成共享 CSS 规则。 */
+function createSharedRule(selectors, mode, options) {
+    const size = `${formatScale(options.scale)}${options.unit}`;
+    const declarations = mode === 'mask'
+        ? [
+            '-webkit-mask:var(--svg-c-icon) no-repeat;',
+            'mask:var(--svg-c-icon) no-repeat;',
+            '-webkit-mask-size:100% 100%;',
+            'mask-size:100% 100%;',
+            'background-color:currentColor;',
+            'color:inherit;',
+            `width:${size};`,
+            `height:${size};`,
+        ]
+        : [
+            'background:var(--svg-c-icon) no-repeat;',
+            'background-size:100% 100%;',
+            'background-color:transparent;',
+            'color:inherit;',
+            `width:${size};`,
+            `height:${size};`,
+        ];
+    for (const [property, value] of Object.entries(options.extraProperties)) {
+        declarations.push(`${property}:${value};`);
+    }
+    return `${selectors.join(',')}{${declarations.join('')}}`;
+}
+/** 判断 SVG 是否包含多色或复杂着色，从而应使用 bg 模式。 */
+function hasComplexPaint(svg) {
+    if (/<(linearGradient|radialGradient|pattern|image)\b/i.test(svg)) {
+        return true;
+    }
+    const values = new Set();
+    const attrMatcher = /\b(?:fill|stroke|stop-color|color)\s*=\s*['"]([^'"]+)['"]/gi;
+    for (const match of svg.matchAll(attrMatcher)) {
+        const normalized = normalizePaintValue(match[1]);
+        if (!normalized)
+            continue;
+        if (normalized.startsWith('url('))
+            return true;
+        values.add(normalized);
+    }
+    const styleMatcher = /\b(?:fill|stroke|stop-color|color)\s*:\s*([^;"]+)/gi;
+    for (const match of svg.matchAll(styleMatcher)) {
+        const normalized = normalizePaintValue(match[1]);
+        if (!normalized)
+            continue;
+        if (normalized.startsWith('url('))
+            return true;
+        values.add(normalized);
+    }
+    return values.size > 1;
+}
+/** 规范化颜色值，便于 auto 模式稳定比较着色特征。 */
+function normalizePaintValue(value) {
+    const normalized = value.trim().replace(/\s+/g, '').toLowerCase();
+    if (!normalized)
+        return null;
+    if (['none', 'currentcolor', 'inherit', 'transparent', 'context-fill', 'context-stroke'].includes(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+/** 对生成的 CSS 选择器做转义，避免特殊字符影响解析。 */
+function escapeClassName(value) {
+    return value.replace(/([^a-zA-Z0-9_-])/g, '\\$1');
+}
+/** 移除文件路径中的最后一个扩展名。 */
+function stripExtension(filePath) {
+    return filePath.replace(/\.[^.]+$/, '');
+}
+/** 将单值或数组统一规范为数组。 */
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/** 将 scale 数值格式化为更紧凑、适合 CSS 输出的字符串。 */
+function formatScale(scale) {
+    const text = String(scale);
+    return text.endsWith('.0') ? text.slice(0, -2) : text;
+}
+/** 返回去掉变体前缀后的候选值，便于解析 hover:i-svg:home 这类类名。 */
+function getVariantCandidates(token) {
+    const indices = [];
+    for (let index = token.indexOf(':'); index !== -1; index = token.indexOf(':', index + 1)) {
+        indices.push(index);
+    }
+    return indices.map((index) => token.slice(index + 1));
+}
+/** 将两个可选的 SVG transform 组合为一条串行处理管线。 */
+function composeTransforms(first, second) {
+    if (!first)
+        return second;
+    if (!second)
+        return first;
+    return async (svg) => second(await first(svg));
+}
+/** 判断当前输入是否为本地文件系统 collection 的对象简写形式。 */
+function isFileSystemCollectionConfig(value) {
+    return typeof value === 'object' && value !== null && 'path' in value;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FileSystemIconLoader, addCurrentFill, type IconMode, type SvgIconPluginOptions, } from './core';
+export { svgIconPlugin } from './plugin';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { FileSystemIconLoader, addCurrentFill, } from './core';
+export { svgIconPlugin } from './plugin';

package/dist/plugin.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+import { type SvgIconPluginOptions } from './core';
+/** 创建插件实例，并维护开发态与构建态共享的运行时状态。 */
+export declare function svgIconPlugin(userOptions: SvgIconPluginOptions): Plugin;

package/dist/plugin.js

@@ -0,0 +1,346 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'tinyglobby';
+import { createFilter, normalizePath } from 'vite';
+import { createIconRecord, extractCollectionSafelistUsages, extractIconUsagesFromCode, extractIconUsagesFromSafelist, generateCss, isFileInDirectories, resolveOptions, resolveIconRenderMode, stripQuery, } from './core';
+/** 创建插件实例，并维护开发态与构建态共享的运行时状态。 */
+export function svgIconPlugin(userOptions) {
+    const state = {
+        iconRecords: new Map(),
+        iconRecordPromises: new Map(),
+        sourceRecords: new Map(),
+        usageOwners: new Map(),
+        sourceUsages: new Map(),
+        staticUsages: new Map(),
+        activeUsages: new Map(),
+        warnedOversizeIcons: new Set(),
+        buildScanned: false,
+    };
+    return {
+        name: 'vite-plugin-svg-icon',
+        enforce: 'pre',
+        // 在 Vite 配置最终确定后，统一解析用户配置。
+        async configResolved(config) {
+            state.config = config;
+            state.options = await resolveOptions(userOptions, config.root);
+            state.filter = createFilter(state.options.contentInclude, state.options.contentExclude);
+            syncStaticUsages(state);
+        },
+        // 在开发模式下为文件系统 collection 注册新增、修改、删除监听。
+        configureServer(server) {
+            state.server = server;
+            registerCollectionWatchers(state, server);
+        },
+        // 将对外暴露的虚拟 CSS id 映射为内部解析 id。
+        resolveId(id) {
+            if (id === state.options?.virtualModuleId) {
+                return state.options.resolvedVirtualModuleId;
+            }
+            return null;
+        },
+        // 根据已扫描源码与 safelist 图标生成当前虚拟 CSS 内容。
+        async load(id) {
+            if (!state.options || id !== state.options.resolvedVirtualModuleId) {
+                return null;
+            }
+            // 构建模式下会一次性扫描完整源码集合，开发模式下则保持增量更新。
+            if (state.config?.command === 'build' && !state.buildScanned) {
+                await scanAllContentFiles(state);
+                state.buildScanned = true;
+            }
+            return getCss(state);
+        },
+        // 对通过内容过滤器的源码模块做增量扫描。
+        async transform(code, id) {
+            if (!state.options || !state.filter)
+                return null;
+            const filePath = cleanFileId(id);
+            if (!state.filter(filePath))
+                return null;
+            await updateSourceRecord(state, filePath, code);
+            return null;
+        },
+        // 扫描 HTML 入口内容，确保只出现在 index.html 中的图标类也能被发现。
+        async transformIndexHtml(html, ctx) {
+            if (!state.options)
+                return html;
+            const filePath = getHtmlFilePath(ctx, state.options.root);
+            await updateSourceRecord(state, filePath, html);
+            return html;
+        },
+        // 开发模式下，当源码文件或本地 SVG 变化时使图标 CSS 缓存失效。
+        async handleHotUpdate(ctx) {
+            if (!state.options || !state.filter)
+                return;
+            const filePath = cleanFileId(ctx.file);
+            if (filePath.endsWith('.svg') && isCollectionSvgFile(state, filePath)) {
+                await invalidateIconCacheByFile(state, filePath);
+                return invalidateVirtualCss(state);
+            }
+            if (!state.filter(filePath)) {
+                return;
+            }
+            let code;
+            try {
+                code = await ctx.read();
+            }
+            catch {
+                removeSourceRecord(state, filePath);
+                return invalidateVirtualCss(state);
+            }
+            await updateSourceRecord(state, filePath, code);
+            return invalidateVirtualCss(state);
+        },
+    };
+}
+/** 在构建模式下扫描所有配置命中的源码文件。 */
+async function scanAllContentFiles(state) {
+    if (!state.options)
+        return;
+    const files = await glob(state.options.contentInclude, {
+        cwd: state.options.root,
+        absolute: true,
+        ignore: state.options.contentExclude,
+    });
+    await Promise.all(files.map((file) => scanSourceFile(state, file)));
+}
+/** 从磁盘读取单个源码文件，并更新其中提取出的图标使用记录。 */
+async function scanSourceFile(state, filePath) {
+    try {
+        const contents = await fs.readFile(filePath, 'utf8');
+        await updateSourceRecord(state, filePath, contents);
+    }
+    catch {
+        removeSourceRecord(state, filePath);
+    }
+}
+/** 基于源码内容指纹缓存，保存某个源码文件最新提取出的图标使用记录。 */
+async function updateSourceRecord(state, filePath, code) {
+    if (!state.options)
+        return;
+    const normalizedPath = normalizePath(filePath);
+    const fingerprint = createCodeFingerprint(code);
+    const cached = state.sourceRecords.get(normalizedPath);
+    if (cached && cached.fingerprint === fingerprint) {
+        return;
+    }
+    const nextUsages = extractIconUsagesFromCode(code, state.options);
+    applySourceUsagesDelta(state, normalizedPath, cached?.usages ?? new Map(), nextUsages);
+    // 只保留当前文件最新内容提取出的结果，便于低成本处理 HMR 更新。
+    state.sourceRecords.set(normalizedPath, {
+        filePath: normalizedPath,
+        fingerprint,
+        usages: nextUsages,
+    });
+}
+/** 将当前已使用的所有图标类解析为虚拟模块需要输出的 CSS 规则。 */
+async function getCss(state) {
+    if (!state.options)
+        return '';
+    const entries = [];
+    for (const usage of state.activeUsages.values()) {
+        const icon = await loadIconRecord(state, usage.collection, usage.icon);
+        if (!icon)
+            continue;
+        if (icon.oversize || !icon.dataUri) {
+            warnOversizeIcon(state, usage, icon);
+            continue;
+        }
+        entries.push({
+            usage,
+            icon,
+            mode: resolveIconRenderMode(icon.svg, usage.mode),
+        });
+    }
+    return generateCss(entries, state.options);
+}
+/** 让 Vite 模块图中的虚拟 CSS 模块失效，以触发重新生成。 */
+function invalidateVirtualCss(state) {
+    if (!state.server || !state.options) {
+        return;
+    }
+    const module = state.server.moduleGraph.getModuleById(state.options.resolvedVirtualModuleId);
+    if (!module) {
+        return;
+    }
+    state.server.moduleGraph.invalidateModule(module);
+    return [module];
+}
+/** 将 Vite 模块 id 规范化为不带 query/hash 的普通文件路径。 */
+function cleanFileId(id) {
+    return normalizePath(stripQuery(id));
+}
+/** 返回 transformIndexHtml 阶段应使用的实际 HTML 文件路径。 */
+function getHtmlFilePath(ctx, root) {
+    if (ctx && 'filename' in ctx && typeof ctx.filename === 'string') {
+        return normalizePath(ctx.filename);
+    }
+    return normalizePath(path.join(root, 'index.html'));
+}
+/** 从已解析的 collection 中加载单个图标，并按 collection/icon 维度做缓存。 */
+async function loadIconRecord(state, collection, icon) {
+    if (!state.options)
+        return null;
+    const cacheKey = `${collection}:${icon}`;
+    if (state.iconRecords.has(cacheKey)) {
+        return state.iconRecords.get(cacheKey) ?? null;
+    }
+    if (state.iconRecordPromises.has(cacheKey)) {
+        return state.iconRecordPromises.get(cacheKey) ?? null;
+    }
+    const loader = state.options.collections.get(collection);
+    if (!loader) {
+        state.iconRecords.set(cacheKey, null);
+        return null;
+    }
+    // 缓存进行中的加载任务，避免并发场景下重复读取同一个 SVG。
+    const promise = (async () => {
+        const source = await loader.load(icon);
+        if (!source) {
+            state.iconRecords.set(cacheKey, null);
+            return null;
+        }
+        const record = createIconRecord(collection, icon, source, state.options.maxSvgSize);
+        state.iconRecords.set(cacheKey, record);
+        return record;
+    })();
+    state.iconRecordPromises.set(cacheKey, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        state.iconRecordPromises.delete(cacheKey);
+    }
+}
+/** 当 SVG 超过 maxSvgSize 被跳过时，仅输出一次告警。 */
+function warnOversizeIcon(state, usage, icon) {
+    const warnKey = icon.filePath ?? `${icon.collection}:${icon.icon}`;
+    if (state.warnedOversizeIcons.has(warnKey))
+        return;
+    state.warnedOversizeIcons.add(warnKey);
+    state.config?.logger.warn(`[vite-plugin-svg-icon] Skipped "${usage.className}" because "${icon.filePath ?? `${icon.collection}:${icon.icon}`}" is larger than ${state.options.maxSvgSize} bytes.`);
+}
+/** 刷新文件系统 collection 索引，并清理变化 SVG 对应的旧缓存。 */
+async function invalidateIconCacheByFile(state, filePath) {
+    if (!state.options)
+        return;
+    const normalizedPath = normalizePath(filePath);
+    for (const [collectionName, collection] of state.options.collections) {
+        if (!collection.fsDir || !collection.fileToIconName)
+            continue;
+        if (!isFileInDirectories(normalizedPath, [collection.fsDir]))
+            continue;
+        const previousIconName = collection.fileToIconName.get(normalizedPath);
+        await collection.refresh?.();
+        if (previousIconName) {
+            state.iconRecords.delete(`${collectionName}:${previousIconName}`);
+            state.iconRecordPromises.delete(`${collectionName}:${previousIconName}`);
+        }
+        const nextIconName = collection.fileToIconName.get(normalizedPath);
+        if (nextIconName && nextIconName !== previousIconName) {
+            state.iconRecords.delete(`${collectionName}:${nextIconName}`);
+            state.iconRecordPromises.delete(`${collectionName}:${nextIconName}`);
+        }
+    }
+    syncStaticUsages(state);
+}
+/** 判断某个文件路径是否属于任一已配置的文件系统图标 collection。 */
+function isCollectionSvgFile(state, filePath) {
+    if (!state.options)
+        return false;
+    const normalizedPath = normalizePath(filePath);
+    return [...state.options.collections.values()].some((collection) => Boolean(collection.normalizedFsDir && normalizedPath.startsWith(collection.normalizedFsDir + '/')));
+}
+/** 注册开发态监听器，使 SVG 的新增、修改、删除都能刷新 collection 输出。 */
+function registerCollectionWatchers(state, server) {
+    if (!state.options)
+        return;
+    const directories = [...state.options.collections.values()]
+        .map((collection) => collection.fsDir)
+        .filter((dir) => Boolean(dir));
+    if (!directories.length)
+        return;
+    server.watcher.add(directories);
+    const handleCollectionEvent = async (filePath) => {
+        if (!filePath.endsWith('.svg'))
+            return;
+        if (!isCollectionSvgFile(state, normalizePath(filePath)))
+            return;
+        await invalidateIconCacheByFile(state, filePath);
+        await reloadVirtualCss(state, server);
+    };
+    server.watcher.on('add', handleCollectionEvent);
+    server.watcher.on('unlink', handleCollectionEvent);
+}
+/** 根据静态 safelist 与 collection 自动 safelist 重新同步当前活跃图标使用集合。 */
+function syncStaticUsages(state) {
+    if (!state.options)
+        return;
+    state.staticUsages = new Map([
+        ...extractIconUsagesFromSafelist(state.options.safelist, state.options),
+        ...extractCollectionSafelistUsages(state.options),
+    ]);
+    rebuildActiveUsages(state);
+}
+/** 依据静态使用集合与源码使用集合，重建当前活跃的图标使用索引。 */
+function rebuildActiveUsages(state) {
+    state.activeUsages = new Map(state.staticUsages);
+    for (const [className, usage] of state.sourceUsages) {
+        state.activeUsages.set(className, usage);
+    }
+}
+/** 将单个源码文件的新旧提取结果做差量合并，维护 usage 拥有者与活跃索引。 */
+function applySourceUsagesDelta(state, filePath, previousUsages, nextUsages) {
+    for (const [className] of previousUsages) {
+        if (nextUsages.has(className))
+            continue;
+        const owners = state.usageOwners.get(className);
+        owners?.delete(filePath);
+        if (owners && owners.size > 0) {
+            continue;
+        }
+        state.usageOwners.delete(className);
+        state.sourceUsages.delete(className);
+        if (!state.staticUsages.has(className)) {
+            state.activeUsages.delete(className);
+        }
+    }
+    for (const [className, usage] of nextUsages) {
+        let owners = state.usageOwners.get(className);
+        if (!owners) {
+            owners = new Set();
+            state.usageOwners.set(className, owners);
+        }
+        owners.add(filePath);
+        state.sourceUsages.set(className, usage);
+        state.activeUsages.set(className, usage);
+    }
+}
+/** 删除源码文件对应的使用记录，并同步释放它贡献的活跃图标引用。 */
+function removeSourceRecord(state, filePath) {
+    const normalizedPath = normalizePath(filePath);
+    const record = state.sourceRecords.get(normalizedPath);
+    if (!record)
+        return;
+    applySourceUsagesDelta(state, normalizedPath, record.usages, new Map());
+    state.sourceRecords.delete(normalizedPath);
+}
+/** 使用轻量内容指纹判断源码内容是否真的变化，避免热路径上的 stat 调用。 */
+function createCodeFingerprint(code) {
+    // FNV-1a 32-bit 在实现复杂度、速度和分布稳定性之间比较均衡，
+    // 适合作为开发态热路径上的轻量内容指纹。
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < code.length; index += 1) {
+        hash ^= code.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `${code.length}:${hash.toString(36)}`;
+}
+/** 失效并触发虚拟 CSS 模块热更新，避免对整页执行 full reload。 */
+async function reloadVirtualCss(state, server) {
+    const modules = invalidateVirtualCss(state);
+    const module = modules?.[0];
+    if (!module)
+        return;
+    await server.reloadModule(module);
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export type Awaitable<T> = T | Promise<T>;
+export type IconMode = 'mask' | 'bg' | 'auto';
+export type IconTransform = (svg: string) => Awaitable<string>;
+export type IconSource = string | (() => Awaitable<string>);
+export type InlineIconCollection = Record<string, IconSource>;
+export interface FileSystemCollectionConfig {
+    path: string;
+    fn?: IconTransform;
+    transform?: IconTransform;
+    autoFillCurrentColor?: boolean;
+    safelist?: boolean;
+}
+export interface FileSystemIconLoaderMeta {
+    kind: 'fs';
+    dir: string;
+    transform?: IconTransform;
+}
+export interface CustomIconLoader {
+    (iconName: string): Awaitable<string | undefined>;
+    __svgIconLoaderMeta?: FileSystemIconLoaderMeta;
+}
+export type IconCollection = InlineIconCollection | CustomIconLoader | FileSystemCollectionConfig;
+export interface SvgIconPluginOptions {
+    collections: Record<string, IconCollection>;
+    prefix?: string | string[];
+    virtualModuleId?: string;
+    scale?: number;
+    unit?: string;
+    mode?: IconMode;
+    maxSvgSize?: number;
+    contentInclude?: string[];
+    contentExclude?: string[];
+    safelist?: string[];
+    extraProperties?: Record<string, string>;
+}
+export interface ResolvedCollection {
+    name: string;
+    load: (iconName: string) => Promise<LoadedIconSource | null>;
+    refresh?: () => Promise<void>;
+    autoSafelist?: boolean;
+    fsDir?: string;
+    normalizedFsDir?: string;
+    fileToIconName?: Map<string, string>;
+    sortedIconNames?: string[];
+}
+export interface ResolvedSvgIconPluginOptions {
+    collections: Map<string, ResolvedCollection>;
+    prefixes: string[];
+    virtualModuleId: string;
+    resolvedVirtualModuleId: string;
+    scale: number;
+    unit: string;
+    mode: IconMode;
+    maxSvgSize: number;
+    contentInclude: string[];
+    contentExclude: string[];
+    safelist: string[];
+    extraProperties: Record<string, string>;
+    root: string;
+}
+export interface ParsedIconUsage {
+    className: string;
+    collection: string;
+    icon: string;
+    mode: IconMode;
+}
+export interface LoadedIconSource {
+    svg: string;
+    filePath?: string;
+}
+export interface IconRecord {
+    collection: string;
+    icon: string;
+    filePath?: string;
+    svg: string;
+    size: number;
+    oversize: boolean;
+    dataUri?: string;
+}
+export interface SourceScanRecord {
+    filePath: string;
+    fingerprint: string;
+    usages: Map<string, ParsedIconUsage>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "vite-plugin-cus-svg-icon",
+  "version": "0.1.0",
+  "description": "A lightweight Vite plugin for generating CSS icons from local SVG files only.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "keywords": [
+    "vite-plugin",
+    "vite",
+    "svg",
+    "icons",
+    "local-icons"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "verify:demo": "node ./scripts/verify-demo.mjs",
+    "verify": "npm run check && npm run test && npm run build && npm run verify:demo"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.0"
+  },
+  "dependencies": {
+    "@iconify/utils": "^3.1.0",
+    "tinyglobby": "^0.2.15"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  }
+}