Vitepress项目中Tailwind类正常但图标无法显示的问题

问题说明 #

在Vitepress项目中，Tailwind风格的样式类（如text-green-500、text-3xl）可正常生效，但通过UnoCSS preset-icons 生成的图标无法显示。相关代码文件如下：

章节文件 chapter-1.md #

## Hello
<Icon />

Vue 组件 Icon.vue #

<template>
  <div class="i-mdi-home text-3xl text-green-500">Test</div>
</template>

UnoCSS 配置文件 uno.config.ts #

import presetAttributify from '@unocss/preset-attributify'
import presetIcons from '@unocss/preset-icons'
import presetWebFonts from '@unocss/preset-web-fonts'
import { createLocalFontProcessor } from '@unocss/preset-web-fonts/local'
import presetWind3 from '@unocss/preset-wind3'
import { defineConfig } from '@unocss/vite'

export default defineConfig({
  shortcuts: [
    { logo: 'i-logos-vue w-6em h-6em transform transition-800' },
  ],
  presets: [
    presetWind3(),
    presetAttributify(),
    presetIcons({
      extraProperties: {
        'display': 'inline-block',
        'vertical-align': 'middle',
      },
    }),
    presetWebFonts({
      provider: 'google',
      fonts: {
        sans: 'Roboto',
        mono: ['Fira Code', 'Fira Mono:400,700'],
        lobster: 'Lobster',
        lato: [
          {
            name: 'Lato',
            weights: ['400', '700'],
            italic: true,
          },
          {
            name: 'sans-serif',
            provider: 'none',
          },
        ],
      },
      processors: createLocalFontProcessor(),
    }),
  ],
  safelist: [
    'i-ph-smiley',
    'i-carbon-add',
    'i-heroicons-outline-home',
    // add all icon classes you use in .md files
  ],
})

Vite 配置文件 config.mts #

import { defineConfig } from 'vitepress'
import UnoCSS from 'unocss/vite'
import MarkdownIt from 'markdown-it';
import { customHighlighter } from './plugins/customHighlighter';

export default defineConfig({
  title: "Madinah Arabic Books",
  description: "Content, keys and solutions",
  markdown: {
    config: (md: MarkdownIt) => {
      md.use(customHighlighter);
    }
  },  
  themeConfig: {
    ...
  },
  vite: {
    plugins: [UnoCSS()],
  },
})

主题文件 theme/index.ts #

import { h } from 'vue'
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import Icon from '../components/Icon.vue'
import 'uno.css'
import '@unocss/reset/tailwind.css'
import './style.css'

export default {
  extends: DefaultTheme,
  Layout: () => {
    return h(DefaultTheme.Layout, null, {})
  },
  enhanceApp({ app, router, siteData }) {
    app.component('Icon', Icon)
  }
} satisfies Theme

解决步骤 #

1. 安装对应图标库 #

preset-icons 不会自动安装图标源，你使用的i-mdi-home属于Material Design Icons，需手动安装：

npm install @iconify-json/mdi
# 或 pnpm add @iconify-json/mdi

2. 添加图标类到安全列表 #

当前safelist中缺少i-mdi-home，Markdown中引用的图标类若未被UnoCSS扫描到，需手动加入：

// uno.config.ts
safelist: [
  'i-ph-smiley',
  'i-carbon-add',
  'i-heroicons-outline-home',
  'i-mdi-home', // 新增此行
],

3. 检查图标渲染样式 #

通过浏览器开发者工具查看.i-mdi-home元素的::before伪元素，确认是否存在正确的content属性（图标Unicode值），若不存在则说明样式未生成。

4. 清理缓存重启服务 #

删除node_modules/.vite或.vitepress/dist目录，然后重启开发服务，避免缓存导致的样式未更新问题。

内容的提问来源于stack exchange，提问作者coure2011