unplugin-icons 基于 Iconify 生态实现图标的按需自动导入，支持 150+ 图标集、200,000+ 图标，以 Vue 组件形式使用且只打包实际用到的图标。本文讲解其安装配置、与 unplugin-vue-components 的协作及图标使用方式。
| 图标集 | 前缀 | 风格 |
|---|---|---|
| Material Design Icons | mdi | Google 风格 |
| Carbon | carbon | IBM 风格 |
| Font Awesome | fa | 经典通用 |
| Heroicons | heroicons | Tailwind 风格 |
| Tabler | tabler | 线性简洁 |
图标搜索：icones.js.org
# 方式一：全部图标集（~60MB，推荐开发机）
pnpm add -D @iconify/json
# 方式二：按需安装特定图标集
pnpm add -D @iconify-json/mdi
pnpm add -D @iconify-json/carbonpnpm add -D unplugin-icons// vite.config.ts
import Icons from 'unplugin-icons/vite'
import IconsResolver from 'unplugin-icons/resolver'
import Components from 'unplugin-vue-components/vite'
export default defineConfig({
plugins: [
vue(),
Icons({
compiler: 'vue3',
autoInstall: true,
}),
Components({
resolvers: [
IconsResolver({
prefix: 'i',
enabledCollections: ['mdi', 'carbon'],
}),
],
}),
],
})| 配置项 | 说明 |
|---|---|
compiler: 'vue3' | 编译为 Vue3 组件 |
autoInstall | 自动安装缺失的图标集 |
prefix: 'i' | 组件名前缀，<i-mdi-home /> |
enabledCollections | 限制可用图标集 |
<template>
<!-- 格式：i-{集合名}-{图标名} -->
<i-mdi-home />
<i-carbon-settings />
<i-mdi-account-circle class="text-2xl text-blue-500" />
</template><script setup>
import HomeIcon from '~icons/mdi/home'
import SettingsIcon from '~icons/carbon/settings'
</script>
<template>
<HomeIcon width="24" height="24" />
<SettingsIcon class="text-gray-600" />
</template>图标编译为 SVG 组件，可通过 CSS 控制：
<i-mdi-heart class="text-red-500 text-xl" />
<!-- 或内联样式 -->
<i-mdi-heart style="color: red; font-size: 20px;" />| 对比项 | unplugin-icons | UnoCSS preset-icons |
|---|---|---|
| 使用方式 | 组件 <i-mdi-home /> | 类名 class="i-mdi-home" |
| 实现原理 | 编译为 Vue 组件 | 生成 CSS background/mask |
| 动态颜色 | 通过 props/CSS | 通过 CSS 变量 |
| 适用场景 | 需要组件级控制 | 纯装饰性图标 |
两种方案可以共存，按场景选择。
Q: 图标不显示怎么办？
@iconify/json 或特定集合）；2) 确认组件名前缀正确；3) 检查 enabledCollections 是否包含目标集合。Q: 如何查看可用的图标名称？
访问 icones.js.org，搜索图标后复制名称。名称格式为 {collection}:{icon}，在组件中转换为 {collection}-{icon}。