字体图标

图标走 Iconify，运行在离线模式——这带来一条必须记住的限制。

用法

<script setup lang="ts">
import { Icon } from '~/iconify'
</script>

<template>
  <Icon icon="lucide:eye" />
  <Icon icon="lucide:trash-2" class="text-red-500" />
</template>

Icon 不是全局组件，用前须从 ~/iconify（或转出它的 ~/components）导入。

图标名格式是 {集合}:{图标}，可在 Iconify 官网 搜索。

菜单图标在后端 PageRegistry 的 PageDescriptor.Icon 字段里写同样的格式：

new("identity.position", "岗位管理", "menu.identity_position", MenuType.Menu,
    "/identity/position", "IdentityPosition", "identity/position/index",
    "identity", SaasPermissionCodes.Position.Read, "lucide:briefcase", 135),
//                                                 ↑ 图标

离线模式的限制

只有预加载的图标集能直接渲染

配置在 ~/iconify/offline.ts。运行期直接渲染只保证这四个已预加载集：

• lucide —— 主力图标集，优先用它
• tabler
• mdi
• simple-icons —— 第三方品牌 logo（如 Gitee 用 simple-icons:gitee）

未预加载的集（carbon / ep / heroicons 等）在页面里直接用会渲染为空白，且不报错——因为离线 Icon 对已挂载组件不会因后加载而重渲染。

以仓库的 PRELOAD_ICON_PACKAGES 配置为准。

品牌图标优先用 simple-icons:* 或 tabler:brand-*。

IconPicker 是例外

图标选择器组件可以按需懒加载 carbon / ep / heroicons 供用户挑选——那是「用户在弹窗里选图标」的场景，与「页面里直接渲染」不同，不受上面限制。

但要注意：用户选了未预加载集的图标存进菜单后，页面渲染时仍然会空白。如果允许用户自选图标，要么把可选集限制在预加载的四个里，要么把用户可能选的集也加入预加载。

为什么用离线模式

在线模式下 Iconify 会在运行时向 CDN 请求图标数据。离线模式把图标数据打进产物，代价是体积和「只能用预加载集」，换来的是：

• 内网/断网环境可用——这是企业中后台的常见部署场景；
• 不依赖第三方 CDN 可用性；
• 首屏图标不闪烁。

加一个图标集

1. 确认对应的 @iconify-json/{集合} 依赖已安装；
2. 在 ~/iconify/offline.ts 的 ICON_SET_META 与 PACKAGE_LOADERS 里登记该集（carbon / ep / heroicons 已登记，可跳过）；
3. 把该集加入同文件的 PRELOAD_ICON_PACKAGES；
4. 重新构建。

加集会增大产物

每个图标集都是完整数据包。只在确实需要时加，优先从已有四个集里找替代图标。

排查

现象	原因
图标位置空白	用了未预加载的图标集
菜单图标空白	后端 Icon 字段写了未预加载集的图标名
图标名写对了还是不显示	图标名拼错（大小写、连字符）；去 Iconify 官网核对
IconPicker 里能看到、放到页面就没了	正是上面那条限制——选择器懒加载，页面渲染不懒加载

相关页面

• 布局与主题：外观定制
• 路由与菜单：菜单图标从哪来
• 常用组件：IconPicker 等公共组件