Dify 自定义图标体系dify/iconify-collections 包与 i-custom-* Tailwind 图标的生成、校验与消费【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/difyDify 前端中的模型 Logo、导航图标、集成商标识等大量定制 SVG并不是逐一手写的 React 组件而是由工作区内部包dify/iconify-collections统一打包成预生成的 Iconify 集合collection再由 Tailwind v4 的 icons 插件转成i-custom-*工具类直接消费。本文以 packages/iconify-collections/README.md 为核心骨架结合 生成脚本、尺寸守卫脚本 与 web 端消费入口 的源码实现完整讲清这套图标流水线的目录约定、生成命令、命名规则与审查要点帮助你在 Dify 中正确添加、再生成并验证自定义 SVG 图标。1. 这个包解决什么问题从 README 的第一段说明可以看到包的定位它是“为 Dify 自定义 SVG 图标预生成的 Iconify 集合”。web 应用直接从本包导入这两个集合这样 Tailwind 在 dev 启动时不需要再去扫描旧版web/app/components/base/icons/src目录树、现场构建自定义 SVG 图标数据启动链路更轻、行为更可预期。这与仓库中保留的旧流程形成对照web/package.json 里的gen-icons脚本仍然是一条“先生成集合、再回灌 React 组件”的流水线gen-icons: pnpm --filter dify/iconify-collections generate node ./scripts/gen-icons.mjs pnpm -w exec vp check --fix web/app/components/base/icons/src/而 web/scripts/gen-icons.mjs 会读取同一份packages/iconify-collections/assets目录为public与vender下的 SVG 生成 React 组件与 JSON 数据到web/app/components/base/icons/src。README 对此有明确指引新增自定义 SVG 图标时不要再向web/app/components/base/icons/src/...添加生成好的 React 图标组件或 JSON 文件该路径已是 legacy新图标必须走本包并以i-custom-*类形式被消费。2. 包结构与导出物packages/iconify-collections/package.json 声明了包的名称、私用属性与全部导出面{ name: dify/iconify-collections, version: 0.0.0-private, private: true, exports: { ./custom-public: { types: ./custom-public/index.d.ts, import: ./custom-public/index.mjs, require: ./custom-public/index.js }, ./custom-public/icons.json: ./custom-public/icons.json, ./custom-public/info.json: ./custom-public/info.json, ./custom-public/metadata.json: ./custom-public/metadata.json, ./custom-public/chars.json: ./custom-public/chars.json, ./custom-vender: { /* 同上结构 */: } }, scripts: { check:dimensions: tsx ./scripts/check-icon-dimensions.ts, generate: tsx ./scripts/generate-collections.ts }, devDependencies: { iconify-import-svg: catalog:, tsx: catalog: } }可以看到两个要点包只暴露两个子路径custom-public与custom-vender每个子路径下分别可导入icons.json、info.json、metadata.json、chars.json及 ESM/CJS/类型入口只有两个脚本generate负责再生成check:dimensions负责尺寸校验二者都通过tsx直接执行 TypeScript 脚本。生成物实际落在包内的custom-public/与custom-vender/目录中每个目录包含 7 个文件icons.json图标数据本体、info.json集合元信息、metadata.json与chars.json占位为空对象{}、以及index.js/index.mjs/index.d.ts三个入口。其中info.json记录了集合prefix、name如 Dify Custom Vender、total当前 custom-vender 为 346 个图标、version、作者与许可证Modified Apache 2.0 / Apache-2.0等信息——这些字段全部由生成脚本统一写入手工不应编辑。3. SVG 源文件的目录约定public 与 venderREADME 规定新增 SVG 源文件只能放进两个目录之一二者的语义不同assets/public/...多色图标或“公共品牌类”图标。从 assets/public 的实际内容看这里存放着 LLM 厂商 Logollm/下 openai、anthropic、deepseek、gemini 等、文件类型图标files/下 pdf、docx、xlsx 等、追踪平台 Logotracing/下 langfuse、phoenix、arize 等、知识库与账单相关图形等assets/vender/...需要以currentColor渲染的 UI 图标。assets/vender 下按 UI 场景分子目录main-nav/31 个主导航图标、line/121 个线性图标、solid/85 个面性图标、workflow/、agent-v2/、integrations/等。这两个目录的差异不止是约定而是直接体现在生成脚本的解析参数上下一节展开。4. 生成流程generate 脚本做了什么pnpm --filter dify/iconify-collections generate实际执行 scripts/generate-collections.ts其核心步骤如下。4.1 用 iconify-import-svg 解析两个源目录脚本对两个目录分别调用importSvgCollections参数差异是关键const customPublicCollections importSvgCollections({ source: path.resolve(packageDir, assets/public), prefix: custom-public, ignoreImportErrors: true, cleanupSVG: true, deOptimisePaths: true, runSVGO: true, // public 集合跑 SVGO 压缩 parseColors: false, // 保留多色原样 }) const customVenderCollections importSvgCollections({ source: path.resolve(packageDir, assets/vender), prefix: custom-vender, ignoreImportErrors: true, cleanupSVG: true, deOptimisePaths: true, runSVGO: false, // vender 集合不跑 SVGO parseColors: { callback: () currentColor, // 所有颜色统一替换为 currentColor }, })public集合保留原始颜色parseColors: false并执行 SVGO 优化适合多彩的品牌 Logovender集合把fill/stroke颜色一律重写为currentColor因此这些图标能跟随text-*颜色类变化适合随主题切换的 UI 线性/面性图标ignoreImportErrors: true表示个别坏文件不会中断整个生成过程。从产物也能验证这一行为custom-vender/icons.json 中每个图标的 body 都是fillcurrentColor的路径数据而源文件 assets/vender/integrations/mcp.svg 中原始的fillvar(--fill-0, #495464)已被替换。4.2 扁平化子目录变成图标名前缀flattenCollections(collections, prefix)函数把importSvgCollections得到的“按子目录分组的嵌套集合”压平成单层结构。规则是子目录名作为图标名前缀agent-v2/access-point.svg→ 图标名agent-v2-access-point子集合未定义width/height时用集合级width/height回填到每个图标applyCollectionSize保证布局敏感的图标携带内禀尺寸汇总所有子集合的lastModified最大值作为整个集合的时间戳。4.3 写出产物并清理旧目录main()先rm掉custom-public/、custom-vender/以及残留的src/目录再对每个集合写出 7 个文件。index.mjs用import ... with { type: json }方式导出icons、info、metadata、chars四个导出index.js是等价 CJS 版本index.d.ts则声明了IconifyJSON/IconifyIcon/IconifyAlias等接口与 package.json 的exports映射一一对应。集合版本直接取自包自己的version字段0.0.0-private。操作要点继承自 README添加或修改 SVG 文件后按顺序执行pnpm --filter dify/iconify-collections generate随后提交两样东西SVG 源文件以及custom-public/或custom-vender/下的生成产物。5. 尺寸守卫check:dimensionsREADME 强调生成后必须跑第二条命令pnpm --filter dify/iconify-collections check:dimensions它的作用是“保护那些内禀尺寸对布局敏感的既有图标组”。实现见 scripts/check-icon-dimensions.ts脚本维护一张dimensionRules规则表当前规则要求custom-vender集合中 9 个主导航图标main-nav-home、main-nav-home-active、main-nav-integrations、main-nav-integrations-active、main-nav-knowledge、main-nav-knowledge-active、main-nav-marketplace、main-nav-marketplace-active、main-nav-studio、main-nav-studio-active在集合扁平化之后必须保持20x20const dimensionRules: DimensionRule[] [ { collection: custom-vender, icons: [ main-nav-home, main-nav-home-active, // ... 共 10 个 main-nav-* 图标 ], width: 20, height: 20, }, ]校验逻辑是逐个图标取icons[iconName]的width/height缺省时回退到集合级尺寸再缺省按 16 计图标缺失或尺寸不等于期望值都会输出形如custom-vender:main-nav-home expected 20x20, got 16x16的失败信息并把process.exitCode置 1可作为 CI 门禁使用。如果后续出现了新的布局敏感图标组README 给出的扩展方式很直接把该组加进scripts/check-icon-dimensions.ts的dimensionRules即可。6. web 端如何消费从文件路径到 i-custom-* 类README 给出的命名换算规则是SVG 源路径去掉assets/前缀与.svg后缀、目录层级用连字符拼接前面加i-前缀。例如assets/vender/integrations/mcp.svg对应前端用法span aria-hidden classNamei-custom-vender-integrations-mcp size-4 /这套类名之所以能生效源于 web/app/styles/plugins/icons.ts 中预绑定的 Tailwind icons 插件import { icons as customPublicIcons } from dify/iconify-collections/custom-public import { icons as customVenderIcons } from dify/iconify-collections/custom-vender import { getIconCollections, iconsPlugin } from egoist/tailwindcss-icons export default iconsPlugin({ collections: { ...getIconCollections([heroicons, ri]), custom-public: customPublicIcons, custom-vender: customVenderIcons, }, extraProperties: { width: 1rem, height: 1rem, display: block, }, })该插件把 heroicons、remixicon 与两个自定义集合合并进同一套iconsPlugin并通过extraProperties给所有图标统一加上width: 1rem; height: 1rem; display: block的基础尺寸与布局。文件头注释说明它通过 Tailwind v4 的plugin ./plugins/icons.ts;语法挂进tailwind-core.css——这也解释了包 README 开头所说“Tailwind 不需要在 dev 启动时现场扫描旧图标树”的机制集合数据在构建期就已固化成 JSON插件直接消费静态导入。正因如此README 特别提示再生成图标后必须重启 web dev server。Tailwind 在启动时加载这个插件集合已经在运行的 dev server 不会把新增的i-custom-*类渲染出来。7. 审查生成物与常见坑README 最后一条经验值得强调审查icons.json的 diff 时要检查无关的既有图标组是否丢失或改变了内禀width/height。原因从 4.2 节的applyCollectionSize可以看出图标级尺寸只有在未定义时才会被集合级尺寸回填一旦某次生成把尺寸字段洗掉依赖内禀尺寸的布局如 20x20 的main-nav-*就会静默错位而尺寸守卫只覆盖已登记规则表里的图标。因此审查清单可归纳为generate后custom-public/、custom-vender/的 diff 是否只包含预期新增/修改的图标无关图标组是否保留了原有width/height布局敏感的新图标组是否已登记进 check-icon-dimensions.tscheck:dimensions通过后重启 web dev server 验证i-custom-*类实际渲染效果提交时同时包含 SVG 源文件与生成产物避免“源码在、产物缺”的不一致状态。另外注意一个容易误用的点vender 集合所有颜色都会被替换为currentColor因此多色图标必须放assets/public/反过来需要随文字颜色变化的 UI 图标放assets/vender/。两个集合的解析参数runSVGO、parseColors差异决定了它们各自适合的内容类型。8. 小结一图流操作路径步骤命令 / 操作说明1放置 SVG多色/品牌类 → assets/public/...UI 单色类 → assets/vender/...2pnpm --filter dify/iconify-collections generate重写custom-public/与custom-vender/全部产物3pnpm --filter dify/iconify-collections check:dimensions校验main-nav-*等敏感组仍为 20x204提交 SVG 源 生成产物两者缺一不可5重启 web dev server让 Tailwind 插件重新加载集合6前端使用span classNamei-custom-public-... /或i-custom-vender-...配合size-4等尺寸类不再手写 React 图标组件整套体系的价值在于把“SVG 资产 → Iconify 集合 → Tailwind 工具类”这条链路收敛到一个私用工作区包中源文件单一assets/、产物确定custom-public/、custom-vender/、消费面统一i-custom-*并为布局敏感的图标组提供了可程序化验证的尺寸门禁。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考