一、核心概念

菜单 IOC 图标指后台管理系统侧边菜单、顶部菜单配置项中的 icon 字段值，并非本地 ico 后缀文件。IOC 即图标标识，只需填写图标名称字符串，无需写标签、路径、后缀、class 类名全称。

通用配置位置：路由 meta.icon、后台菜单配置表 icon 字段、系统菜单新增/编辑弹窗图标输入框。

二、四大主流框架填写格式（直接抄用）

1. RuoYi-Vue / RuoYi-Plus（最常用）

使用 Element Plus 官方图标名，纯图标英文名（大驼峰），无需前缀、无需后缀。

✅ 正确填写示例：

HomeFilled
Menu
Setting
User
DataLine
FolderOpened

❌ 错误写法：el-icon-home、icon-home、svg路径、图片地址

2. Vben Admin（IOC 标准写法）

支持两套规则，优先 Iconify 简写，兼容 Element 图标名。

✅ Iconify 规范（推荐）：图标库-图标名

ic:baseline-home
ic:outline-settings
mdi:home-outline

✅ 兼容 Element 写法：同 RuoYi 大驼峰名称

3. Element Plus 原生菜单

路由 meta.icon 直接写入组件名，与全局注册图标名一致。

// 路由配置示例
{
  path: '/home',
  name: 'Home',
  component: () => import('@/views/home/index.vue'),
  meta: { title: '首页', icon: 'HomeFilled' }
}

4. Iconify 统一图标方案

填写 前缀:图标短名，前缀固定、名称可查 Iconify 官网。

标准格式：库前缀/图标名 或 库前缀:图标名

mdi:account
ep:setting
ic:round-dashboard

三、自定义 SVG / 本地图标填写规则

1. 本地 SVG 图标放入 src/assets/icons/menu 目录；

2. 全局注册自定义图标集；

3. 输入框直接填写 SVG 文件名（不含后缀）。

示例：文件 custom-order.svg → 填写 custom-order

四、必填注意事项（90% 报错原因）

  • 禁止写完整 class：不要写 iconfont、el-icon-xxx 前缀

  • 大小写严格匹配：Element 图标为大驼峰，Iconify 多为小写短横线命名

  • 不填路径、不填图片、不填后缀：无需 http 链接、无需 .svg/.png/.ico

  • 后台数据库与前端规则统一：后端菜单表 icon 字段值，必须和前端解析规则一致，否则图标空白

五、快速找图标名称方法

  1. Element Plus：官网图标库复制组件名（如 HomeFilled）；

  2. Iconify：官网搜索图标，复制 prefix:name 标准值；

  3. 框架自带图标：查看项目 icon.ts 注册文件，取用已注册名称。

六、常见问题排查

  • 菜单图标不显示：图标名拼写错误、未全局注册图标、前后端命名规则不一致

  • 控制台报错：填写了非法字符、路径、未注册的自定义图标名

  • Vben 不识别：优先使用 ic:xxx 标准 IOC 写法，而非 Element 驼峰名