UnoCSS presetIcons 集成方案

[Lruihao]

Context

FixIt 主题使用 Font Awesome Free 图标库（100 个图标，75KB CSS 文件）。UnoCSS 的 presetIcons 预设可以将图标作为 CSS 内联 SVG 使用，支持 FontAwesome、Material、Lucide 等数百个图标集，无需加载外部字体/CSS 文件。

---

方案概述

用 UnoCSS presetIcons 替代 Font Awesome CSS 文件加载，图标以 SVG data URI 内联到 CSS 中。

优势：

• 移除 75KB 的 Font Awesome CSS 文件
• 按需生成，只包含实际使用的图标
• 支持数百个图标集（FontAwesome、Material、Lucide、Tabler 等）
• 与 UnoCSS 工具类统一使用方式

限制：

• presetIcons 生成的是 SVG 背景图，不是 Font Awesome 的字体图标
• 字体图标的一些特性（如 fa-stack、fa-fw）需要额外处理
• 图标颜色通过 currentColor 继承，与 Font Awesome 行为一致

---

实施步骤

Step 1: 配置 presetIcons

在 uno.config.ts 中添加 presetIcons：

import { defineConfig, presetWind3, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    presetIcons({
      extraProperties: {
        'display': 'inline-block',
        'vertical-align': 'text-bottom',
      },
    }),
  ],
  // ...
})

Step 2: 替换所有 FA 类名为 UnoCSS 图标类

类名格式：fa6-{style}-{name}

映射规则：

FA 类名	UnoCSS 类名
fa-solid fa-angle-right	fa6-solid-angle-right
fa-regular fa-calendar	fa6-regular-calendar
fa-brands fa-github	fa6-brands-github

100 个图标需替换，涉及 100+ 个模板文件。

Step 2b: 替换 SCSS 中的 FA 伪类图标

SCSS 中有 12 处使用 FA 图标码（--fa: "\f066" 等）的伪元素，需要迁移：

文件	用途
core/_common.scss	.is-fullscreen .fa-expand 图标切换
core/mixins/_theme-switch.scss	主题切换图标 mixin
pages/shared/_copy-icon-btn.scss	复制按钮 ::before 图标
pages/shared/_code.scss	代码块复制/运行按钮图标
pages/shared/shortcodes/_center-quote.scss	引用装饰 ::before/::after 图标
pages/shared/shortcodes/_file-tree.scss	文件夹图标
pages/shared/_content.scss	::marker 图标

Step 3: 移除 Font Awesome

• 移除 layouts/_partials/base/head/index.html 中的 FA CSS 加载
• 移除 assets/lib/fontawesome-free/ 目录
• 移除 librarybot.yml 中的 FA 更新配置
• 移除 assets/data/cdn/jsdelivr.yml 和 unpkg.yml 中的 FA CDN 条目
• 移除 hugo.toml 中的 FA CDN 配置

Step 4: 更新 icon.html 模板

icon.html 的 .Class 参数直接传递 UnoCSS 图标类，无需修改逻辑。但 fa-stack、fa-fw 等 FA 特有功能需要移除或替换。

---

需要修改的文件

文件	改动
uno.config.ts	添加 presetIcons 预设
100+ 个模板文件	替换 FA 类名
layouts/_partials/base/head/index.html	移除 FA CSS 加载
assets/lib/fontawesome-free/	删除目录
librarybot.yml	移除 FA 更新配置
assets/data/cdn/jsdelivr.yml	移除 FA CDN 条目
assets/data/cdn/unpkg.yml	移除 FA CDN 条目
layouts/_partials/plugin/icon.html	更新 FA 特有功能处理

---

主题消费者影响

• FA CSS 不再加载，用户自定义的 FA 类名失效
• 用户需迁移自定义代码中的 FA 类名为 UnoCSS 图标类
• custom.scss 中的 FA 相关样式需要更新

---

验证

1. pnpm css:build 成功，unocss.css 包含图标 SVG
2. pnpm build:demo 构建成功
3. 图标正确显示（颜色、大小、对齐）
4. 主题切换不影响图标显示（currentColor 继承）

[Lruihao]

保留 FontAwesome CSS 图标兼容用户配置中使用，增加额外的图标支持。