Codex 结合 better-icons 拿图标：先固定图标库再动手的配置骨架

1. 为什么图标总是越写越乱如果你用 Codex 写过前端页面大概率遇到过这种场景同一个「删除」动作首页用的是垃圾桶轮廓列表页变成了实心垃圾桶弹窗里又冒出一个 emoji。单看每个图标都没问题放在一起就是花的。根子不在 Codex 不会画图标而在于它每次都在「猜」——猜路径、猜名称、猜风格猜出来的东西自然对不上。我试过让 Codex 直接写 SVG 路径结果它编了一个M12 2C6.48...开头的坐标看着像那么回事实际渲染出来是个歪的。也试过让它用 emoji 顶替和lucide:trash-2混在一张表格里视觉重量完全不一样。真正稳定的做法是图标不靠 Codex 生成靠一个统一的库去查。查得到就用查不到就换关键词找同类而不是随手造一个。better-icons 就是干这件事的工具它连接 Iconify 的 200 多个图标库把「检索」和「取回 SVG」拆成两个明确动作。但在让它动手之前有一件事必须先做——固定图标库。这篇聚焦的就是这个前置环节怎么用config.toml和settings.json把图标来源收敛成单一入口然后演示固定之后 Codex 取图标的验证动作。适合需要在 Iconify/SVG 场景里稳定复现的开发者。2. 先理解 better-icons 管什么、不管什么better-icons 是一个 skill核心能力就两件检索图标、拿回 SVG。它不负责图标长什么样、配色怎么定那些是设计规范的事。它管的是「图标从哪来」。图标用库前缀:名称的格式定位比如lucide:home、mdi:delete、heroicons:arrow-right。有了这个统一格式Codex 写图标时先搜索、再取 SVG路径就不会再靠猜。常用的库有 lucide、mdi、heroicons、tabler 这几个。选哪个库直接影响页面整体风格但比选哪个更重要的是——一个项目只用一个库。混着用两三个库即使每个图标都标准风格还是花的。给 Codex 的约束可以写成一句图标统一从指定库检索缺的图标换关键词找同类不许用 emoji 替代。有了这句它就不会在写页面时随手发挥。2.1 检索和获取是两个命令# 检索看有哪些图标可用 better-icons search arrow --limit 10 # 获取把这个图标的内容取回来 better-icons get lucide:home icon.svg检索负责「有哪些」获取负责「取回来」。分开的好处是Codex 可以先看候选再决定用哪个而不是直接猜一个名称去取。2.2 批量取回和存量盘点想找一个动作的多个候选可以直接下载成 SVG 文件better-icons search check -d ./my-icons这条命令会把搜索结果直接下载到目录里Codex 需要哪个就用哪个不用一个一个手抄。对存量项目还有一个盘点用法better-icons scan_project_icons通过 MCP 提供的scan_project_icons可以把项目里用到的图标列出来。改图标之前先盘点能看出当前用的什么库、命名乱不乱而不是凭印象猜。3. 固定图标库config.toml 与 settings.json 配置骨架固定图标库这件事落到配置上就是两处一处告诉 Codex 用哪个库一处告诉 better-icons 去哪查。下面给出可复制的骨架你按项目实际情况改库名就行。3.1 config.toml声明图标库约束在项目根目录或 Codex 的配置目录下建config.toml把图标来源写死[icons] # 项目统一使用的图标库只允许一个 library lucide # 允许的库前缀白名单防止 Codex 混用 allowed_prefixes [lucide] # 缺图标时的行为换关键词找同类而不是造路径 fallback search_similar # 禁止用 emoji 替代图标 allow_emoji false # 检索默认返回条数 search_limit 10 # 批量下载目录 download_dir ./src/assets/icons这里的关键是allowed_prefixes。只放一个lucideCodex 就没有混用的空间。allow_emoji false把 emoji 这条路堵死fallback search_similar告诉它找不到就换词别自己编。3.2 settings.jsonbetter-icons 的检索入口better-icons 通过 MCP 接入需要在settings.json里声明服务{ mcpServers: { better-icons: { command: npx, args: [-y, better-icons, mcp], env: { BETTER_ICONS_DEFAULT_LIBRARY: lucide, BETTER_ICONS_ALLOWED_PREFIXES: lucide, BETTER_ICONS_ALLOW_EMOJI: false } } } }BETTER_ICONS_DEFAULT_LIBRARY和config.toml里的library保持一致两处对齐才不会出现「配置说用 lucide实际查了 mdi」的情况。BETTER_ICONS_ALLOWED_PREFIXES是第二道闸即使 Codex 想查别的库也会被拦下来。3.3 两处配置的对应关系config.toml 字段settings.json 环境变量作用libraryBETTER_ICONS_DEFAULT_LIBRARY默认检索库allowed_prefixesBETTER_ICONS_ALLOWED_PREFIXES库前缀白名单allow_emojiBETTER_ICONS_ALLOW_EMOJI是否允许 emoji 替代search_limit无对应检索返回条数download_dir无对应批量下载目录注意config.toml是给 Codex 看的约束settings.json是给 better-icons 看的入口。两处都要配只配一处会出现「约束写了但工具不认」或「工具认了但 Codex 不知道」的错位。4. 验证固定之后让 Codex 取一个图标配置写完不算完得验证 Codex 真的按约束走。下面是一套可复现的验证动作。4.1 先确认 CLI 可用better-icons 的 CLI 要先装好否则命令跑不起来npm install -g better-icons # 或者每次用 npx 代替 npx better-icons --version4.2 触发一次检索让 Codex 执行检索看它返回的候选是不是都来自 lucidebetter-icons search home --limit 5预期结果里每一条都应该是lucide:开头。如果冒出mdi:或heroicons:说明白名单没生效回去检查settings.json的环境变量。4.3 取回 SVG 并落盘better-icons get lucide:home ./src/assets/icons/home.svg打开这个文件应该是一段标准的svg内容viewBox和stroke属性齐全。如果文件是空的或者报错多半是图标名写错了——这时候正确的动作是回到检索换关键词而不是手写一个路径。4.4 批量下载验证better-icons search check -d ./src/assets/icons这条命令跑完./src/assets/icons目录下应该出现一批check相关的 SVG。Codex 需要哪个就从这里取来源可审计。4.5 存量项目盘点better-icons scan_project_icons输出会列出项目里用到的图标。对照一下如果发现混了多个库就是这次要收敛的目标。5. 本篇常见错排查5.1 命令跑不起来提示 command not foundCLI 没装。执行npm install -g better-icons或者把命令里的better-icons换成npx better-icons。这一步没做后面所有验证都无从谈起。5.2 检索结果里混了别的库allowed_prefixes没生效。检查settings.json里BETTER_ICONS_ALLOWED_PREFIXES的值多个前缀用逗号分隔只留一个lucide才是真正锁死。同时确认config.toml的allowed_prefixes和它一致。5.3 Codex 还是用了 emojiallow_emoji没配或配成了字符串false而不是布尔false。在config.toml里写allow_emoji false在settings.json里写BETTER_ICONS_ALLOW_EMOJI: false两处都要。5.4 取回的 SVG 是空的图标名不存在。lucide:home存在lucide:house可能不存在。正确做法是回到better-icons search换关键词而不是自己编一个名称。这也是固定图标库的意义——名称有据可查。5.5 同一个动作在不同页面图标不一致这是收敛前的典型症状。用scan_project_icons盘点找出同一个动作对应的多个图标名统一成一个。改完之后把config.toml的约束再确认一遍防止 Codex 下次又发挥。5.6 配置改了但 Codex 没反应MCP 服务需要重启才生效。改完settings.json后重启 Codex让它重新加载 MCP 配置。config.toml如果是项目级配置也要确认 Codex 读的是这个路径。6. 把图标来源收敛成单一入口固定图标库这件事价值不在选 lucide 还是 heroicons而在于「一个页面一个库」这个约束本身。约束立住了Codex 的「猜」就变成了「查」图标来源、风格、命名都有了可查的依据。交付前可以静态查这几样页面里有没有 emoji 当图标图标是不是统一来自同一个库引用的路径和名称是否存在同一个动作在不同页面用的是不是同一个图标。这几项都能靠 better-icons 的检索结果对照不需要打开页面猜。如果你还没配好接入入口可以先到 TaoToken API Keys 把密钥建好再对照 接入文档 把 MCP 服务接上。想先验证模型对话是否正常可以用 模型对话 跑一轮长期用 Codex 写代码或跑 AgentCoding Plan 更适合把这类 skill 固定进日常流程。配置骨架给到这里剩下的就是把你项目里的库名填进去跑一遍第 4 节的验证动作。跑通了图标这件事就不用再靠印象管了。