自定义 SVG Icon 功能¶

本文档介绍如何在网站中使用自定义 SVG 图标替代 FontAwesome 图标。

概述¶

网站支持三种类型的图标：

FontAwesome 图标：默认的图标系统，如 fas fa-house
自定义 SVG 图标：存放在 assets/media/icons/ 或 static/images/icons/ 目录中的 SVG 文件
Emoji 图标：使用 emoji 字符作为图标

使用场景¶

自定义 SVG 图标可以应用于以下位置：

导航菜单（主导航、下拉菜单）
面包屑导航
书籍目录菜单
Mega 下拉菜单
其他使用 render-icon.html partial 的地方

SVG 图标存放位置¶

备用位置（static 目录）¶

static/images/icons/
├── my-custom-icon.svg
├── cloud.svg
└── gear.svg

优势：

直接复制到输出目录，无需构建处理
适合简单的 SVG 文件

注意：系统会优先尝试从 assets/media/icons/ 加载，如果未找到则回退到 static/images/icons/。

SVG 文件要求¶

文件格式¶

文件扩展名必须是 .svg
确保 SVG 代码干净，移除不必要的元数据
使用 viewBox 属性而非固定的 width 和 height

SVG 优化工具¶

推荐使用以下工具优化 SVG 文件：

SVGO：命令行 SVG 优化工具
SVGOMG：在线 SVG 优化工具
Adobe Illustrator：导出时选择"优化 SVG"

配置方法¶

1. 导航菜单配置¶

在 config/_default/menus.zh.toml 或 menus.en.toml 中：

[[main]]
name = "博客"
URL = "/blog/"
weight = 10
pre = "custom my-blog-icon"  # 使用自定义 SVG
identifier = "blog"

[[main]]
name = "AI"
URL = "/ai/"
weight = 1 
pre = "fas fa-wand-magic-sparkles"  # 仍可使用 FontAwesome

[[main]]
name = "图书"
URL = "/book/"
weight = 24
pre = "emoji 📚"  # 使用 emoji
identifier = "book"

格式说明：

FontAwesome：pre = "fas fa-icon-name" 或 pre = "far fa-icon-name"
自定义 SVG：pre = "custom icon-filename"（不含 .svg 扩展名）
Emoji：pre = "emoji 😀"

2. 面包屑导航配置¶

在页面或 section 的 front matter 中：

---
title: "我的页面"
icon: "my-custom-icon"     # SVG 文件名（不含扩展名）
icon_pack: "custom"         # 指定使用自定义 SVG
---

或使用 FontAwesome：

---
title: "我的页面"
icon: "house"               # FontAwesome 图标名
icon_pack: "fas"            # FontAwesome pack
---

或使用 Emoji：

---
title: "我的页面"
icon: "🏠"                  # Emoji 字符
icon_pack: "emoji"
---

3. 书籍目录配置¶

在书籍章节的 front matter 中：

---
title: "第一章"
weight: 1
icon: "chapter-icon"
icon_pack: "custom"
---

4. Mega 下拉菜单配置¶

在 data/zh/mega_menu.yaml 或 data/en/mega_menu.yaml 中：

mega:
  blog:
    title: "博客"
    description: "技术文章和教程"
    viewAll:
      label: "查看全部"
      url: "/blog/"
      icon: "custom my-view-all-icon"  # 自定义 SVG
    columns:
      - title: "分类"
        items:
          - name: "云原生"
            icon: "custom cloud-icon"   # 自定义 SVG
            url: "/categories/cloud-native/"
          - name: "AI"
            icon: "fas fa-robot"         # FontAwesome
            url: "/categories/ai/"
          - name: "容器技术"
            icon: "emoji 🐳"             # Emoji
            url: "/categories/container/"

在代码中使用¶

如果你需要在自定义模板中使用图标，可以直接调用 render-icon.html partial：

使用 FontAwesome¶

{{ partial "render-icon.html" (dict "icon" "house" "pack" "fas" "class" "my-custom-class") }}

使用自定义 SVG¶

{{ partial "render-icon.html" (dict "icon" "my-icon" "pack" "custom" "alt" "My Icon") }}

使用 Emoji¶

{{ partial "render-icon.html" (dict "icon" "🏠" "pack" "emoji") }}

参数说明¶

icon（必需）：图标标识符
FontAwesome：图标名称（如 "house"）
自定义 SVG：文件名（不含 .svg 扩展名）
Emoji：emoji 字符
pack（可选，默认 "fas"）：图标包类型
"fas", "far", "fab", "fal"：FontAwesome
"custom"：自定义 SVG
"emoji"：Emoji
class（可选）：额外的 CSS 类名
alt（可选）：SVG 图标的 alt 文本，默认使用 icon 参数值

CSS 样式定制¶

默认样式¶

所有 SVG 图标都会应用以下基础样式：

.svg-icon {
  display: inline-block;
  width: 1em;
  height: 1em;
  fill: currentColor;
  vertical-align: middle;
}

调整图标大小¶

使用预定义的大小类：

<img src="..." class="svg-icon icon-sm">  <!-- 小图标 -->
<img src="..." class="svg-icon icon-lg">  <!-- 大图标 -->
<img src="..." class="svg-icon icon-xl">  <!-- 超大图标 -->

自定义样式¶

你可以在自定义 CSS 中覆盖图标样式：

// 针对特定位置的图标
.nav-link .svg-icon {
  width: 1.2em;
  height: 1.2em;
}

// 针对特定图标
.svg-icon[alt="my-icon"] {
  filter: drop-shadow(0 0 2px rgba(0,0,0,0.2));
}

示例¶

完整示例：创建自定义导航图标¶

准备 SVG 文件

创建 assets/media/icons/rocket.svg：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
  <path d="M12 2.69l5.66 5.66a8 8 0 1 1-11.31 0z"/>
</svg>

配置菜单

编辑 config/_default/menus.zh.toml：

[[main]]
name = "启动"
URL = "/launch/"
weight = 30
pre = "custom rocket"

验证效果

运行开发服务器并访问网站，应该能看到自定义的火箭图标。

故障排除¶

图标未显示¶

检查文件路径：确认 SVG 文件存在于正确的目录
检查文件名：确保文件名与配置中的 icon 参数匹配（不含扩展名）
检查 SVG 格式：确保 SVG 文件格式正确，使用 fill="currentColor"
清除缓存：运行 hugo --gc 清除 Hugo 缓存后重试

图标颜色不正确¶

确保 SVG 文件中使用 fill="currentColor" 而非固定颜色值：

<!-- ❌ 错误 -->
<path fill="#000000" d="..."/>

<!-- ✅ 正确 -->
<path fill="currentColor" d="..."/>

图标大小不合适¶

调整图标所在容器的字体大小，或添加自定义 CSS 类：

.my-custom-nav .svg-icon {
  width: 1.5em;
  height: 1.5em;
}

最佳实践¶

使用语义化的文件名：如 cloud-native.svg 而非 icon1.svg
保持 SVG 简洁：移除不必要的元数据和注释
使用 viewBox：确保图标在不同尺寸下正确缩放
统一图标风格：保持整个网站图标风格一致
优化文件大小：使用 SVGO 等工具优化 SVG 文件
提供回退方案：在配置中同时保留 FontAwesome 图标作为备选

更新历史¶

2025-11-13：初始版本，支持自定义 SVG、FontAwesome 和 Emoji 图标