Codex 写的页面图标总是不一致？把图标当成代码质量来管

1. Codex 生成页面时图标为什么总在漂移用 Codex 生成一个后台管理页表格、表单、分页器都能一次跑通唯独图标区域让人皱眉侧边栏是 emoji 垃圾桶工具栏是图标库的 trash弹窗关闭按钮又变成一张本地 png。同一个「删除」动作三种长相、三种命名、三种来源页面拼在一起一眼就能看出是拼凑的。这不是 Codex 能力问题而是图标在它的输入里属于「没有明确依据」的部分。页面结构能从需求描述推出来字段能从接口定义推出来唯独图标需求里通常一个字都不提。没有依据就只能猜猜一个常见图标名、塞一个永远能显示的 emoji、或者写一个自以为存在的路径。三种结果里只有第一种勉强可用后两种分别带来视觉漂移和 404 空白。把这件事拆开看图标混乱分三层越往后越难收拾。第一层是视觉层emoji 与 SVG 混用、线性图标与填充图标混用、尺寸从 16px 到 24px 随机跳、颜色直接写死十六进制。第二层是命名层同一个删除在代码里叫 delete、trash、remove下次让 Codex 查「删除图标用在哪」它得顺着三个名字各搜一遍。第三层是来源层图标路径是猜的写之前不知道项目里到底有没有这个文件编译能过但运行时报 404。这三层不是平行的来源乱会带来命名乱命名乱会加剧视觉乱。所以堵漏要往前堵把图标当成代码质量的一部分来约束而不是等页面拼完再返工。下面这套配置骨架目标就是让 Codex 在写图标时有据可依——统一来源、统一命名、统一尺寸与颜色并且能被 lint 规则拦住。2. 用 TaoToken 统一 Key 与 API 通道做前置准备在动手写图标规范之前先把 AI 工具的接入通道理顺。原因很实际图标规范落地后你需要反复让 Codex 或同类模型检查「这个页面有没有用 emoji 当图标」「图标命名是否和现有组件一致」如果每个工具各配一套 Key、各记一个地址排查问题时连请求发到哪都说不清。TaoToken 在这里的作用是提供一个统一的 Key 和 API 通道把模型对话、编码计划、控制台管理收敛到同一个入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时直接填这个。具体操作分三步。第一步打开控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后立刻复制保存页面刷新后不再完整显示。第二步如果你主要做长期编码和 Agent 任务去 Coding Plan 页面看套餐说明地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按自己的调用量选不要一上来就买最大档。第三步把 Key 写进项目根目录的.env.local不要提交到 Git# .env.local TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类命令行工具接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有环境变量写法和验证命令。Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时吊销泄露的 Key。注意Key 只放在本地环境变量或密钥管理服务里不要硬编码进前端代码也不要贴进聊天记录。前端能读到的 Key 等于公开。通道理顺之后后面所有让模型检查图标规范的请求都走同一个入口出问题时只需要看一处日志排查成本直接降一半。3. 可复制的图标规范配置骨架这一节是全文的核心交付一套能直接抄进项目的骨架一个统一的 SVG 图标组件、一份图标清单、一条 lint 规则。三者配合才能让 Codex 在生成页面时「有据可依」。3.1 统一 SVG 图标组件先建一个components/Icon目录里面放一个Icon.tsx。它的职责是只接受白名单里的图标名统一尺寸和颜色禁止外部传入任意路径。// components/Icon/Icon.tsx import type { SVGProps } from react; import { iconMap, type IconName } from ./icon-map; type IconProps SVGPropsSVGSVGElement { name: IconName; size?: 16 | 20 | 24; color?: string; }; export function Icon({ name, size 20, color currentColor, ...rest }: IconProps) { const Glyph iconMap[name]; if (!Glyph) { throw new Error([Icon] 未注册的图标名: ${name}); } return ( Glyph width{size} height{size} fill{color} aria-hiddentrue focusablefalse {...rest} / ); }关键点有三个。name的类型是IconName来自icon-map的联合类型写错名字 TypeScript 直接报错不用等运行时。size只允许 16、20、24 三档从类型层面堵住 18px、22px 这种随手写的值。color默认currentColor图标颜色跟随父级文字颜色不再各处写死十六进制。3.2 图标清单与命名映射icon-map.ts是唯一允许出现图标来源的地方。所有图标从同一个库引入命名用「动作 对象」的语义化写法不用库的原始导出名。// components/Icon/icon-map.ts import { Trash2, Pencil, Plus, Search, ChevronDown, X, } from lucide-react; export const iconMap { action-delete: Trash2, action-edit: Pencil, action-create: Plus, action-search: Search, nav-expand: ChevronDown, action-close: X, } as const; export type IconName keyof typeof iconMap;这样做的收益很直接。业务代码里只写Icon nameaction-delete /不关心底层是 lucide 还是别的库。将来要换图标库只改这一个文件全项目跟着变。命名统一成action-*、nav-*前缀后让 Codex 查「删除图标用在哪」搜action-delete一次就够。3.3 用 lint 规则拦住 emoji 和裸路径光有组件不够还得有规则拦住绕过组件的行为。用 ESLint 的no-restricted-syntax加两条限制禁止在 JSX 里直接写 emoji 字符禁止img标签的 src 指向图标目录。// .eslintrc.cjs module.exports { rules: { no-restricted-syntax: [ error, { selector: JSXText[value/[\\u{1F300}-\\u{1FAFF}\\u{2600}-\\u{27BF}]/u], message: 不要用 emoji 当图标请使用 Icon name... /, }, { selector: JSXAttribute[name.namesrc][value.value/\\/icons?\\//], message: 图标不要用 img 裸路径请使用 Icon name... /, }, ], }, };第一条规则的正则覆盖常见 emoji 区段命中就报错。第二条拦住src/icons/trash.svg这类写法因为这种路径是 Codex 猜出来的项目里未必存在。两条规则配合emoji 和裸路径在提交前就会被拦下。3.4 尺寸与颜色的约束表把允许的值固定成表Codex 生成时照着选评审时照着对。场景尺寸颜色说明行内文字旁16currentColor跟随正文颜色按钮内20currentColor跟随按钮文字色导航栏20currentColor选中态由父级控制空状态插图24currentColor不放大到 32 以上危险操作20currentColor颜色由按钮 danger 类控制这张表的价值在于消除「随手写」的空间。尺寸只有三档颜色一律currentColor危险色通过父级 class 传递图标组件本身不感知业务语义。4. 验证请求与成功结果配置写完得验证它真的生效。分三步走每步都有明确的成功标志。第一步验证 TypeScript 类型约束。故意写一个不存在的图标名Icon nameaction-remove /保存后编辑器应立即标红提示action-remove不在IconName联合类型里。如果没报错检查icon-map.ts是否用了as const以及IconName是否正确导出。第二步验证 lint 规则。在任意组件里写一个 emojibutton 删除/button运行npx eslint src --ext .tsx应输出类似下面的报错error 不要用 emoji 当图标请使用 Icon name... / no-restricted-syntax如果没报错检查 ESLint 配置是否被项目根配置覆盖以及正则里的u标志是否加上。第三步让模型按规范检查现有页面。通过 TaoToken 的模型对话入口发一条请求地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 把下面这段提示词贴进去附上你的页面代码请检查以下页面代码是否符合图标规范 1. 是否存在 emoji 当图标的情况 2. 是否存在 img 直接引用图标路径的情况 3. 所有图标是否通过 Icon name... / 使用 4. 图标尺寸是否只在 16/20/24 三档内。 逐条列出问题行号和修改建议。成功的结果是模型逐条给出问题位置且建议里出现的图标名都在你的icon-map.ts白名单内。如果它建议了一个不存在的图标名说明提示词里要补上「只能从以下清单选择」并附上清单。实测下来这三步走完新生成的页面里 emoji 和裸路径基本绝迹剩下的问题集中在命名是否语义化这个靠 code review 补。5. 本篇常见错排查配置落地过程中下面几个坑出现频率最高逐个说清楚。报错一[Icon] 未注册的图标名: xxx。运行时抛这个错说明业务代码用了icon-map.ts里没有的名字。解决方式是先在icon-map.ts注册再在业务里引用。不要为了图快在组件里加 fallback 返回空那样会把问题藏到线上。报错二lint 规则不生效。常见原因是项目用了 flat configeslint.config.js而不是.eslintrc.cjs两套配置的写法不同。flat config 下要写成// eslint.config.js export default [ { rules: { no-restricted-syntax: [ error, { selector: JSXText[value/[\\u{1F300}-\\u{1FAFF}]/u], message: 不要用 emoji 当图标请使用 Icon name... /, }, ], }, }, ];报错三图标颜色不跟随。如果图标写死了fill#333父级改文字颜色时它不动。检查Icon.tsx里fill是否默认currentColor以及 SVG 源文件里有没有硬编码的fill属性覆盖了它。lucide 这类库默认用currentColor一般不用改。报错四尺寸在移动端被拉伸。如果 SVG 只设了width没设height在某些布局下会被拉伸变形。Icon.tsx里同时设width和height就是为了避免这个不要只传一个。报错五模型检查时漏报。如果让模型检查页面却什么都没发现先确认代码是不是真的贴全了再确认提示词里有没有明确列出检查项。模型不会主动猜你的规范规范得写进提示词。提示把上面这段排查清单存成项目里的docs/icon-troubleshooting.md下次有人问同样的问题直接甩链接。6. 把图标纳入验收清单让 Codex 有据可依回到最初的问题Codex 写的页面图标为什么总不一致因为图标是它写页面时少数几个没有明确输入的部分没有约束就只能猜。解法不是抱怨它猜得不准而是把「图标从哪来、用什么、怎么命名、尺寸颜色怎么定」写成它看得见的约束。这套骨架的最小闭环是四件事一个只接受白名单名字的Icon组件、一份集中管理来源和命名的icon-map.ts、两条拦住 emoji 和裸路径的 lint 规则、一张尺寸颜色对照表。四件事做完图标就从「随手写」变成了「按规范选」。验收清单里值得固定加上图标这一项有没有用 emoji 当图标、图标来源是不是统一的库、命名有没有和项目现状一致、路径是不是真实存在。这些检查不需要很深的技术含量难的是有人把它写进标准。一旦清单里有这一条Codex 写的时候就会收敛。如果你还在用多个工具各配一套 Key建议先把通道统一到 TaoToken模型对话、编码计划、Key 管理都在同一处排查图标规范这类跨工具问题时不用来回切换。接入文档和 API Keys 页面都在前面给过按需取用。下一篇会推荐一个专门解决图标检索的 skill让 Codex 不再猜图标而是从一个统一的图标库里检索、拿到可用的 SVG来源和风格都有据可依。