MrleeAdmin/frontend/web/scripts/download-icons

离线图标模式使用说明

概述

本项目支持离线图标模式，图标数据可以本地缓存，减少对在线 API 的依赖。

工作原理

1. 优先从本地加载：客户端优先从 /public/icons/ 目录加载图标数据
2. 在线回退：如果本地没有缓存，自动从 Iconify API 获取
3. 服务端处理：服务端始终使用在线 API（因为服务端无法访问 public 目录）

下载图标到本地

快速开始

# 进入下载脚本目录
cd web/scripts/download-icons

# 运行下载脚本（无需额外依赖）
node download-icons.cjs

下载结果

脚本会下载以下图标集到 web/public/icons/ 目录：

• ant-design.json - 830 个 Ant Design 图标
• simple-icons.json - 3393 个品牌图标
• mdi.json - 9032 个 Material Design Icons
• material-symbols.json - 15161 个 Material Symbols
• tabler.json - 5986 个 Tabler Icons
• ph.json - 9072 个 Phosphor Icons
• lucide.json - 1669 个 Lucide Icons

总计：45,143 个图标

目录结构

web/
├── public/
│   └── icons/
│       ├── index.json          # 图标索引文件
│       ├── ant-design.json      # Ant Design 图标集
│       ├── simple-icons.json    # Simple Icons 图标集
│       ├── mdi.json             # MDI 图标集
│       ├── material-symbols.json # Material Symbols 图标集
│       ├── tabler.json          # Tabler Icons 图标集
│       ├── ph.json              # Phosphor Icons 图标集
│       └── lucide.json          # Lucide Icons 图标集
└── scripts/
    └── download-icons/
        ├── download-icons.cjs   # 下载脚本
        └── README.md

使用示例

<template>
  <Icon icon="ant-design:home-outlined" />
  <Icon icon="simple-icons:gitee" />
  <Icon icon="mdi:account" />
</template>

<script setup>
import { Icon } from '~/components/icon'
</script>

支持的图标集

图标集	数量	说明
ant-design	830	Ant Design 官方图标
simple-icons	3393	品牌图标（GitHub、Gitee 等）
mdi	9032	Material Design Icons
material-symbols	15161	Google Material Symbols
tabler	5986	Tabler Icons
ph	9072	Phosphor Icons
lucide	1669	Lucide Icons

注意事项

1. 首次加载：首次使用时需要下载图标数据到本地
2. 网络要求：如果本地没有缓存，需要网络连接才能获取图标
3. 更新图标：如需更新图标集，重新运行下载脚本即可
4. 文件大小：完整的图标集较大，但已优化为 JSON 格式，加载速度快

故障排除

图标不显示

1. 检查浏览器控制台是否有错误信息
2. 确认 /public/icons/ 目录下有对应的 JSON 文件
3. 检查网络连接（如果本地没有缓存）

下载失败

1. 检查网络连接
2. 确认 Node.js 版本 >= 14
3. 尝试手动下载图标数据

性能优化

• 图标数据会在内存中缓存，避免重复加载
• 使用 CDN 加速图标 SVG 的加载
• 已下载 45,143 个图标，覆盖大部分常用场景

技术细节

加载策略

// 客户端优先从本地加载
if (process.client) {
  try {
    // 1. 尝试从本地加载
    icons = await fetch(`/icons/${prefix}.json`)
  } catch (localError) {
    // 2. 本地加载失败，回退到在线 API
    icons = await fetch(`https://api.iconify.design/collection?prefix=${prefix}`)
  }
} else {
  // 3. 服务端始终使用在线 API
  icons = await fetch(`https://api.iconify.design/collection?prefix=${prefix}`)
}

缓存机制

• 内存缓存：避免重复请求
• 本地文件：持久化存储
• 在线回退：确保可用性