@zhiaiwan-icons/compiler

zhiaiwan-icons 图标编译器 —— 把「source/db.csv + SVG 资产」编译成 icons.json 中间产物，并生成 React / Vue2 / Vue3 / SVG 四端源码。零运行时依赖，既是 CLI 也是库。

它把「单一数据源 → 确定性编译链」封装成一个可复用工具：同一份 SVG 资产 + 元数据，一次生成四套框架源码，产物稳定可重跑。

• 零运行时依赖：仅用 Node 内置模块（fs / path / url）。
• 确定性：按 name 升序输出、统一 LF + 末尾换行、JSON 2 空格缩进、无时间戳/随机数 —— 同一份资产多次编译产物一致。
• CLI + 库双形态：命令行直接跑，或在自己的脚本里按 target 调用。
• 可分端：icons / code 分离，四端可独立生成，便于 CI 分端缓存与单端排错。

安装

pnpm add -D @zhiaiwan-icons/compiler
# 或 npm i -D / yarn add -D

约定的目录结构

编译器以当前工作目录（process.cwd()）为仓库根，要求如下结构：

<repo-root>/
├── source/
│   ├── db.csv                 # 图标登记表（元数据单一数据源，手写）
│   └── <Category>/<name>.svg  # 原始 SVG，按英文分类分目录（手写）
└── packages/
    ├── react/                 # 目标包，生成源码写入其 src/
    ├── svg/
    ├── vue/
    └── vue3/

若在非仓库根目录调用，用环境变量 ICONS_ROOT 显式指定根目录：ICONS_ROOT=/path/to/repo zhiaiwan-icons-compiler icons。

db.csv 列

| 列 | 含义 | 约束 | |----|------|------| | title | 中文标题 | — | | name | 英文名 = SVG 文件名（不含 .svg） | ^[a-z0-9-]+$ 且全库唯一 | | categoryCN | 中文分类名 | — | | category | 英文分类目录名 | 必须与 source/ 下目录完全一致 | | rtl | 是否支持 RTL | 是 / 否 | | tag | 标签 | 多标签逗号分隔 | | author | 负责人 | — |

CLI 用法

# 1. 资产编译：db.csv + svg → source/{icons.json, icons-config.json, db-fixed.csv}（含一致性校验）
zhiaiwan-icons-compiler icons

# 2. 源码生成：icons.json → packages/{react,svg,vue,vue3}/src/**
zhiaiwan-icons-compiler code

# 2'. 单端生成（只生成某一端，便于 CI 分端缓存 / 排错）
zhiaiwan-icons-compiler react   # 或 svg | vue | vue3

# 3. 清理：删除四端 src/
zhiaiwan-icons-compiler clean

子命令：icons | code | react | svg | vue | vue3 | clean。

典型串联（改了 SVG 或 db.csv 后）：

zhiaiwan-icons-compiler icons && zhiaiwan-icons-compiler code

在仓库内用 tsx 直接跑源码（免构建，工作目录 = 仓库根）：

tsx node_modules/@zhiaiwan-icons/compiler/src/index.ts icons   # 若安装了源码形态

icons 的四类校验错误

任一失败即非 0 退出，并一次性列出全部问题：

| 错误 | 含义 | |------|------| | svg路径不存在 | CSV 登记了但文件缺失 | | svg分类错误 | SVG 放在与 category 不一致的目录 | | svg名字重复 | 同名重复登记，或同名文件出现在多个目录 | | svg命名只允许小写字母/连字符/数字 | name 违反 ^[a-z0-9-]+$ |

库用法（编程调用）

主入口导出资产编译与清理；四端生成器各自从子路径导出 generate()：

import { compileIcons, cleanSrc } from '@zhiaiwan-icons/compiler';
import { generate as generateReact } from '@zhiaiwan-icons/compiler/react';
import { generate as generateSvg } from '@zhiaiwan-icons/compiler/svg';
import { generate as generateVue } from '@zhiaiwan-icons/compiler/vue';
import { generate as generateVue3 } from '@zhiaiwan-icons/compiler/vue3';

// 需先切到仓库根，或设置 process.env.ICONS_ROOT
compileIcons();       // 生成 icons.json / icons-config.json / db-fixed.csv（校验失败会 process.exit(1)）
generateReact();      // 仅生成 React 端 src/**
generateSvg();
generateVue();
generateVue3();

cleanSrc();           // 删除四端 src/

| 导出 | 来源 | 作用 | |------|------|------| | compileIcons() | . | 资产编译 + 一致性校验，生成 JSON 中间产物 | | cleanSrc() | . | 删除四端 src/ | | generate() | ./react ./svg ./vue ./vue3 | 生成对应端 src/** |

SVG 调色板约定

源 SVG 用固定 token 上色，编译器按位置映射到运行时 colors[]，从而支持 theme / fill 切换：

| token | 含义 | 映射 | |-------|------|------| | #333（含 #000 / black / currentColor） | 主描边色 | colors[0] | | #2F88FF | 主填充色 | colors[1] | | #FFF（含 white） | 反白填充色 | colors[2] | | #43CCF8 | 辅助填充色 | colors[3] |

描边元素的 stroke-width / stroke-linecap / stroke-linejoin 由运行时 props 覆盖。落在调色板外的颜色按原样保留，不参与 theme 切换。

产物

| 产物 | 说明 | |------|------| | source/icons.json | 完整清单（元数据 + SVG 文本），源码生成的直接输入 | | source/icons-config.json | 裁掉 SVG 文本的清单，供发布/预览时消费 | | source/db-fixed.csv | 规范化登记表（列序固定、按 name 升序） | | packages/*/src/** | 四端源码：icons/*、map.ts、all.ts、index.ts、runtime/* |

环境

• Node >= 18

License

Apache-2.0