直接集成 preset-icons 即可使用纯 CSS 图标，无需 SVG 引入或 JS 运行时，颜色和尺寸由 CSS 类（如 c-red、text-2xl）控制；需安装图标集（如 @iconify-json/mdi）并在 uno.config.ts 中正确配置 collections、include 和 exclude。
直接集成 preset-icons 就能用纯 CSS 图标，不需要额外 SVG 引入、不依赖 JS 运行时、颜色和尺寸完全由 CSS 控制。
安装图标集合并启用 preset-icons
UnoCSS 的图标能力来自 @unocss/preset-icons，它本身不带图标数据，必须配合图标集 JSON 包使用。常见组合如 @iconify-json/mdi（Material Design Icons）或 @iconify-json/carbon：
- 运行
pnpm add -D @unocss/preset-icons @iconify-json/mdi - 在
uno.config.ts中注册预设，并确保collections明确列出你安装的图标集名称（注意不是包名全称，而是图标集 ID，如mdi） - 不要漏掉
include和exclude配置——否则 UnoCSS 可能跳过模板文件，导致图标类不生成
类名写法与 color / size 控制原理
图标类名格式为 i-{collection}-{icon}，例如 i-mdi-home。它的样式生效依赖两个关键点：
- 默认使用
mask模式：图标是透明 SVG 数据 URI，靠background-color: currentColor填色，所以父元素的color会直接作用于图标 - 尺寸靠文字相关类控制：
text-xl、text-2xl会改变font-size，而图标 mask 默认按1em × 1em渲染，因此自动缩放 - 如果发现图标大小异常，检查是否遗漏了
extraProperties配置——比如没加display: inline-block，会导致行内布局塌陷
为什么图标没渲染？常见失效场景
最常遇到的不是配置错，而是构建时“看不见”类名：
-
vite.config.ts中unocss()插件没加，或加在uni()之前（uni-app 小程序项目必须后置） - 模板中写了
i-mdi-home，但该文件没被include规则覆盖（比如用了.ux后缀却没在include里加/\.ux$/） - 开发时热更新没触发重扫描——改完
uno.config.ts后要手动重启 dev server，否则旧缓存还在 - 图标名拼写错误：
i-mdi-hom不会报错，只会静默忽略；建议用 IDE 插件（如 UnoCSS VS Code 扩展）开启图标名自动补全
想用自定义 SVG 怎么办？
官方 preset-icons 默认只支持 Iconify 生态的 JSON 图标集。若需本地 SVG 文件，得搭配 FileSystemIconLoader：
- 安装
@iconify/utils（非 dev 依赖） - 在
uno.config.ts中用FileSystemIconLoader('./icons')加载目录，目录下放home.svg、user.svg等命名规范的文件 - 类名变成
i-custom-home，其中custom是你在collections里配的 key - 注意：本地 SVG 必须是标准格式（含
viewBox，无width/height属性），否则 mask 渲染会变形
真正容易被忽略的是构建阶段的扫描边界——include 写得窄，图标类就进不了 CSS；exclude 漏掉 node_modules，构建速度会断崖下跌。这两项不是可选项，是必调参数。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
