@wemt/fontawesome-toolkit

一个提取和转换 FontAwesome 图标的综合工具库，用于从项目中提取已使用的 FontAwesome 图标，并将 SVG 图标转换为 Web 字体（TTF、WOFF、WOFF2、EOT），同时自动生成 CSS 文件。

✨ 核心功能

🔍 SVG 提取模块

自动扫描项目中的 FontAwesome 图标使用情况，提取并复制到指定目录。

功能特性：

• 自动扫描项目代码，识别使用的图标
• 提取图标并生成使用清单 JSON 文件
• 支持自定义扫描路径和匹配规则
• 支持多种图标样式（solid、regular、brands）

适用场景：

• 微信小程序开发
• 需要按需加载图标的移动端应用
• 优化打包体积，只包含实际使用的图标
• 需要自定义图标组件的项目

🎨 字体生成模块

将 SVG 图标转换为 Web 字体文件，自动生成对应的 CSS。

功能特性：

• 支持多种字体格式（TTF、WOFF、WOFF2、EOT）
• 自动生成 CSS 文件和 @font-face 声明
• 自动分配 Unicode 码点（默认从 0xE001 开始）
• 支持自定义 CSS 模板和字体元数据

适用场景：

• Web 应用使用图标字体
• 将 SVG 图标转换为字体以减少 HTTP 请求
• 需要在 CSS 中使用图标的场景
• 自定义图标字体项目

🚀 集成方式

• Vite 插件：构建时自动执行
• 集成函数：同时使用 SVG 提取和字体生成
• 独立模块：按需使用单个功能
• 模块化设计：灵活组合

⚠️ 注意事项

• 确保项目中已安装 @fortawesome/fontawesome-free 包
• Vite 插件会在构建开始时（buildStart 钩子）执行
• 建议将输出目录添加到 .gitignore，在构建时自动生成
• 默认匹配规则适用于 fas fa-home、far fa-user 等格式
• 如果使用其他格式，需要自定义 scan.match 正则表达式

📦 安装

npm install @wemt/fontawesome-toolkit --save-dev

🏗️ 架构说明

本库采用模块化设计，包含两个完全独立的模块：

• extractor - SVG 提取模块
• font - 字体生成模块

每个模块都可以独立使用，也可以通过集成函数组合使用。

📖 使用方法

方式一：独立使用 SVG 提取模块

import { extractSvgIcons, defaultExtractorConfig } from "@wemt/fontawesome-toolkit";

const config = {
  ...defaultExtractorConfig,
  scan: {
    path: ["src"],
    ext: [".vue", ".ts"],
    match: [/fa[srb]\s+(fa-[\w-]+)/g],
  },
  output: {
    path: "dist/icons",
    name: "icons.json",
  },
  icon: {
    path: ["node_modules/@fortawesome/fontawesome-free/svgs/solid"],
    ext: [".svg"],
    prefix: "fa-",
  },
};

const iconMap = await extractSvgIcons(config);
// 返回: { "home": "/path/to/home.svg", "user": "/path/to/user.svg", ... }

方式二：独立使用字体生成模块

import { generateFont, defaultFontConfig } from "@wemt/fontawesome-toolkit";

// 假设你已经有了图标映射
const iconMap = {
  home: "/path/to/home.svg",
  user: "/path/to/user.svg",
};

const config = {
  font: {
    ...defaultFontConfig,
    enabled: true,
    fontName: "my-icons",
    formats: ["ttf", "woff", "woff2"],
    output: {
      fontPath: "dist/fonts",
      cssPath: "dist/css",
      cssFileName: "icons.css",
    },
    cssPrefix: "icon",
    startCodepoint: 0xe001,
  },
};

await generateFont(iconMap, config);
// 生成字体文件和 CSS 文件

方式三：使用集成函数（推荐）

同时使用 SVG 提取和字体生成：

import fastk from "@wemt/fontawesome-toolkit";

await fastk({
  // SVG 提取配置
  scan: {
    path: ["src"],
    ext: [".vue"],
    match: [/fa[srb]\s+(fa-[\w-]+)/g],
  },
  output: {
    path: "dist/icons",
    name: "icons.json",
  },
  icon: {
    path: ["node_modules/@fortawesome/fontawesome-free/svgs"],
    ext: [".svg"],
    prefix: "fa-",
  },
  // 字体生成配置（可选）
  font: {
    enabled: true,
    fontName: "my-icons",
    formats: ["ttf", "woff", "woff2"],
    output: {
      fontPath: "dist/fonts",
      cssPath: "dist/css",
      cssFileName: "icons.css",
    },
  },
});

方式四：作为 Vite 插件使用

基础使用

在 vite.config.js 或 vite.config.ts 中配置插件：

import { defineConfig } from "vite";
import { FontawesomeToolkitPlugin as fastk } from "@wemt/fontawesome-toolkit";

export default defineConfig({
  plugins: [
    fastk({
      scan: { path: ["src"], ext: [".vue"] },
      output: { path: "dist/icons" },
      icon: {
      path: ["node_modules/@fortawesome/fontawesome-free/svgs"],
        prefix: "fa-",
      },
      // 可选：启用字体生成
      font: {
        enabled: true,
        fontName: "my-icons",
        formats: ["ttf", "woff2"],
      },
    }),
  ],
});

完整配置示例

import { defineConfig } from "vite";
import { FontawesomeToolkitPlugin as fastk } from "@wemt/fontawesome-toolkit";

export default defineConfig({
  plugins: [
    fastk({
      // SVG 提取配置
      scan: {
        path: ["src"],
        ext: [".vue", ".js", ".ts"],
        match: [/fa[srb]\s+(fa-[\w-]+)/g],
      },
      output: {
        path: "src/assets/fontawesome/svg",
        name: "fortawesome.json",
      },
      icon: {
        path: ["node_modules/@fortawesome/fontawesome-free/svgs"],
        ext: [".svg"],
        prefix: "fa-",
      },
      // 字体生成配置
      font: {
        enabled: true,
        fontName: "fontawesome-icons",
        formats: ["ttf", "woff", "woff2"],
        output: {
          fontPath: "src/assets/fontawesome/fonts",
          cssPath: "src/assets/fontawesome",
          cssFileName: "fontawesome-icons.css",
        },
        cssPrefix: "fa",
        startCodepoint: 0xe001,
        metadata: {
          fontName: "FontAwesome Icons",
          version: "1.0.0",
          description: "Custom FontAwesome icon font",
        },
      },
    }),
  ],
});

⚙️ 配置选项详解

SVG 提取配置

scan（扫描配置）

| 选项 | 类型 | 默认值 | 说明 | | ------- | ---------- | ---------------------------- | -------------------------- | | path | string[] | ['src'] | 要扫描的文件路径数组 | | ext | string[] | ['.vue'] | 要扫描的文件扩展名数组 | | match | RegExp[] | [/fa[srb]\s+(fa-[\w-]+)/g] | 匹配规则数组（正则表达式） |

output（输出配置）

| 选项 | 类型 | 默认值 | 说明 | | ------ | -------- | ------------------------------ | ---------------- | | path | string | 'src/assets/fontawesome/svg' | 输出目录路径 | | name | string | 'fortawesome.json' | 输出 JSON 文件名 |

icon（图标配置）

| 选项 | 类型 | 默认值 | 说明 | | -------- | ---------- | ---------- | ------------------ | | path | string[] | 见下方 | 图标源文件路径数组 | | ext | string[] | ['.svg'] | 图标文件扩展名数组 | | prefix | string | 'fa-' | 图标类名前缀 |

默认的 icon.path 值：

["node_modules/@fortawesome/fontawesome-free/svgs"];

字体生成配置

font（字体配置）

| 选项 | 类型 | 默认值 | 说明 | | ---------------- | -------------- | -------------------------- | ------------------- | | enabled | boolean | false | 是否启用字体生成 | | fontName | string | 'fontawesome-icons' | 字体族名称 | | formats | FontFormat[] | ['ttf', 'woff', 'woff2'] | 输出格式数组 | | cssPrefix | string | 'fa' | CSS 类名前缀 | | startCodepoint | number | 0xE001 | 起始 Unicode 码点 | | cssTemplate | string? | undefined | 自定义 CSS 模板路径 |

font.output（字体输出配置）

| 选项 | 类型 | 默认值 | 说明 | | ------------- | -------- | -------------------------------- | ---------------- | | fontPath | string | 'src/assets/fontawesome/fonts' | 字体文件输出路径 | | cssPath | string | 'src/assets/fontawesome' | CSS 文件输出路径 | | cssFileName | string | 'fontawesome-icons.css' | CSS 文件名 |

font.metadata（字体元数据）

| 选项 | 类型 | 默认值 | 说明 | | ------------- | --------- | -------------------------------- | -------- | | fontName | string | 'FontAwesome Icons' | 字体名称 | | version | string | '1.0.0' | 版本号 | | author | string? | undefined | 作者 | | copyright | string? | undefined | 版权信息 | | description | string? | 'Custom FontAwesome icon font' | 描述 |

📄 许可证

MIT

👤 作者

Wemt Team ([email protected])