VitePress 学习指南

主题

菜单图标配置 ​

本教程将详细介绍如何为 VitePress 2.0 的导航栏和侧边栏添加自定义 SVG 图标，让你的文档站更加美观和专业。

版本说明

  • 本教程基于 VitePress v1.0.0+ 编写
  • Badge 功能需要 v1.0.0+ 版本
  • SVG 图标支持所有版本
  • 部分样式选择器在 v1.0.0 中有所变化

效果预览 ​

添加图标后的效果：

  • 导航栏菜单项带有图标
  • 下拉菜单项带有小图标
  • 鼠标悬停时图标有动画效果
  • 部分菜单项带有 Badge 标签

实现方式 ​

VitePress 2.0 支持多种方式添加菜单图标：

方式优点缺点
SVG 内嵌简单直接，无需额外依赖配置文件较长
Vue 组件可复用，支持动态属性需要自定义主题
CSS 背景图与配置分离不够灵活
Iconify图标库丰富需要额外安装

本教程采用 SVG 内嵌 方式，这是最简单且无需额外依赖的方案。

步骤一：定义 SVG 图标 ​

在 docs/.vitepress/config.mts 文件顶部定义 SVG 图标常量：

typescript
// SVG 图标定义
const icons = {
  // 首页图标
  home: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="nav-icon">
    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path>
    <polyline points="9 22 9 12 15 12 15 22"></polyline>
  </svg>`,
  
  // 指南图标
  guide: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="nav-icon">
    <path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"></path>
    <path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"></path>
  </svg>`,
  
  // 设置图标
  settings: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="nav-icon">
    <circle cx="12" cy="12" r="3"></circle>
    <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
  </svg>`
}

SVG 图标来源

推荐从 Feather Icons 获取高质量的 SVG 图标，这是一个开源图标库，图标简洁美观。

步骤二：在导航栏中使用图标 ​

使用模板字符串将图标嵌入到菜单项的 text 属性中：

typescript
export default defineConfig({
  themeConfig: {
    nav: [
      { 
        text: `${icons.home} 首页`, 
        link: '/' 
      },
      { 
        text: `${icons.guide} 入门指南`, 
        link: '/guide/introduction',
        badge: { text: '推荐', type: 'tip' }
      },
      {
        text: `${icons.settings} 设置`,
        items: [
          { text: '基本设置', link: '/settings/basic' },
          { text: '高级设置', link: '/settings/advanced' }
        ]
      }
    ]
  }
})

下拉菜单图标 ​

下拉菜单的子项也可以添加图标，建议使用较小的尺寸：

typescript
const icons = {
  // ... 其他图标
  
  // 下拉菜单专用小图标
  blog: `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="nav-icon">
    <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"></path>
  </svg>`
}

// 使用
{
  text: `${icons.examples} 实战案例`,
  items: [
    { text: `${icons.blog} 博客搭建`, link: '/examples/blog' }
  ]
}

步骤三：添加 Badge 标签 ​

版本要求

Badge 功能需要 VitePress v1.0.0+ 版本支持。

VitePress 支持 Badge 标签，用于突出显示重要菜单项：

typescript
{
  text: `${icons.guide} 入门指南`,
  link: '/guide/introduction',
  badge: { text: '推荐', type: 'tip' }
}

Badge 类型 ​

类型颜色适用场景
tip绿色推荐内容
info蓝色信息提示
warning橙色警告注意
danger红色重要/热门
默认灰色普通标签

步骤四：添加 CSS 样式 ​

在 docs/.vitepress/theme/style.css 中添加图标样式：

css
/* 导航图标通用样式 */
.nav-icon {
  display: inline-block;
  vertical-align: middle;
  margin-right: 6px;
  margin-top: -2px;
  transition: transform 0.2s ease;
}

/* 导航栏链接图标 */
.VPNavBarMenuLink .nav-icon,
.VPNavBarMenuGroup .nav-icon {
  width: 16px;
  height: 16px;
  color: var(--vp-c-text-2);
  transition: color 0.25s;
}

/* 悬停变色 */
.VPNavBarMenuLink:hover .nav-icon,
.VPNavBarMenuGroup:hover .nav-icon {
  color: var(--vp-c-brand-1);
}

/* 下拉菜单图标 */
.VPNavBarMenuGroup .items .nav-icon {
  width: 14px;
  height: 14px;
  margin-right: 8px;
}

.VPMenuLink:hover .nav-icon {
  color: var(--vp-c-brand-1);
}

/* 悬停动画 */
.VPNavBarMenuLink:hover .nav-icon,
.VPMenuLink:hover .nav-icon {
  transform: scale(1.1);
}

/* 深色模式调整 */
.dark .nav-icon {
  opacity: 0.9;
}

步骤五：侧边栏图标（可选） ​

侧边栏同样支持图标和 Badge：

typescript
sidebar: {
  '/guide/': [
    {
      text: '入门指南',
      items: [
        { 
          text: '什么是 VitePress', 
          link: '/guide/what-is-vitepress',
          badge: { text: '推荐', type: 'tip' }
        }
      ]
    }
  ]
}

完整示例 ​

以下是一个完整的配置示例：

typescript
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

const icons = {
  home: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="nav-icon"><path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path><polyline points="9 22 9 12 15 12 15 22"></polyline></svg>`,
  guide: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="nav-icon"><path d="M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z"></path><path d="M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z"></path></svg>`
}

export default defineConfig({
  themeConfig: {
    nav: [
      { text: `${icons.home} 首页`, link: '/' },
      { text: `${icons.guide} 指南`, link: '/guide/', badge: { text: '新', type: 'tip' } }
    ]
  }
})

常用图标资源 ​

网站说明
Feather Icons简洁优雅的开源图标库
HeroiconsTailwind 官方图标库
LucideFeather Icons 的增强版
Tabler Icons超过 5000 个图标

注意事项 ​

  1. 图标尺寸：导航栏建议 16x16，下拉菜单建议 14x14
  2. 颜色继承：使用 stroke="currentColor" 让图标继承文字颜色
  3. 性能考虑：避免使用过大的 SVG，保持代码简洁
  4. 无障碍：确保图标与文字搭配使用，不单独依赖图标传达含义

下一步 ​

📖 相关文章推荐

导航栏配置
基础导航

贡献者

加载中...

想要成为贡献者？

在 CNB 上参与贡献

Copyright © 2016 - 2026 VitePress 学习指南