最近前端群里好几个人都在问 ponytail 插件到底怎么用尤其是“ponytail skill”这个叫法听起来像是个新出的玩具。其实它是一套专门用来给 CSS 样式文件“收辫子”的工具——扫描、标记、清理、重构把散落各处的冗余样式统一归拢所以叫 ponytail马尾辫。如果你经常被几百行没人敢动的global.css劝退或者每次改完 HTML 都要提心吊胆地查样式有没有挂掉这篇就是给你写的。ponytail 不是一个花哨的 UI 组件库也不是动画库它更像是前端工程化里的“样式整理师”。我会从设计思路讲起再给出一套可以直接照抄的安装、配置、实操流程最后把我踩过的坑和排查逻辑一并整理出来。不管你是刚接触前端工程化的新人还是维护老项目到头疼的资深开发应该都能从中拿到点能立刻用得上的东西。1. 先搞清楚 ponytail 是什么以及它想解决什么问题1.1 一个很形象的命名马尾辫“ponytail”直译过来是马尾辫这个命名其实特别直白。一个项目跑久了几乎不可避免地会出现这类状况.btn定义了好几次有的在基础样式里有的在页面级样式里当年做活动页留下的.active-banner-2023早就没人用了但文件里还堂而皇之地躺着还有一些选择器嵌套五六层拆开来看全是重复声明。这时候整个样式文件就像一头没梳理的乱发看着厚重实际上有用的大概只有一半。ponytail 想做的就是拿一根皮筋把这些头发扎起来——先梳顺再扎紧最后让那些飘在外面、已经失去作用的碎发直接剪掉。这根“皮筋”就是它的核心流程通过静态分析扫描项目里所有 CSS/SCSS 文件和匹配的模板文件找出真正被引用的选择器、真正生效的声明块然后把冗余部分标记出来给你一份可执行的清理报告。所以 ponytail 不适合用“样式检查工具”来简单定义。它更像一个带有重构建议的“样式瘦身器”重点不在挑错而在帮你安全地做减法。尤其当你面对一个没有测试覆盖、样式文件历史包袱很重的老项目时这种“先分析、再报告、最后动手”的方式会比人工眼睛排查可靠得多。1.2 ponytail skill 和 ponytail 插件之间的关系很多人在搜索“ponytail skill”和“ponytail 插件”时容易把它们当成两个东西。实际上它们指的是同一个工具在不同形态下的两种使用方式。“插件”形态通常是可以直接安装的 CLI 工具通过npx ponytail或全局命令执行扫描、输出报告、自动修剪。这种形态适合本地开发、CI 流水线一切都在命令行里完成输出是 JSON 格式的报告方便后续处理。“skill”形态则是给 AI 编程助手用的封装。现在很多 AI 编程环境支持“自定义技能”本质上是把一个结构化的操作手册Markdown和配套脚本放进指定的skills目录AI 在回答相关问题时会自动加载这个技能知道应该调用哪些命令、怎么解析报告、怎么安全地修改样式文件。你可以把 skill 理解成“教 AI 使用 ponytail 的说明书”而说明书背后仍然是那套 CLI 在干活。这两种形态并不互斥。我实际使用时的做法是本地先装好 CLI把配置写好、规则调好然后在 AI 助手的工作区里放一份对应版本的 skill 文件。这样如果需要 AI 帮忙批量处理样式它就能按照我给它的操作流程去调用 CLI、读懂结果而不是凭空猜测该怎么清理。1.3 适用场景与不适合的场景先说它擅长的场景。第一类是多年没敢大动的业务项目样式文件成百上千行注释里写着“此处不要删线上正在用”但没人知道到底哪部分在用这时候 ponytail 能给出基于代码引用关系的客观判断。第二类是重构前的摸底比如准备把老项目从 jQuery 迁移到 Vue或者准备引入 Tailwind你需要在动手前知道现有样式体系里哪些是可以放弃的哪些是必须保留的。第三类是 CI 卡点要求在合并请求前把冗余样式比例控制在一定阈值以内ponytail 可以无缝接进流水线。但它也有明显不适合的场景。如果你的项目是纯组件库每一个样式类都直接对应组件 API而且已经有完善的单元测试那么用 stylelint 或者 TypeScript 类型检查可能更直接ponytail 的“扫描引用”反而会因组件动态用法太多而误报。如果你用了 CSS-in-JS比如 styled-components样式不是以独立文件存在的ponytail 也基本派不上用场因为它擅长的是静态文件层面的分析。所以选择工具之前先对号入座有历史包袱、有静态样式文件、有模板可查这三条都满足的时候ponytail 就是那个能把头发扎起来的皮筋。2. 上手前需要理解的核心设计2.1 为什么 AST 比正则靠谱我见过不少人第一次拿到 ponytail 的扫描结果第一反应是“这不就是正则匹配吗”实际上它底层用的是样式解析器先把 CSS 转成 AST抽象语法树再对模板里的 class 引用做标记最后把两者比对。简单来说AST 是把样式文件的结构拆成可编程操作的树形数据而不是像正则那样只看字符层面的匹配。正则方案最大的问题是容易误伤。比如注释里写了一行.old-style {}的示例代码正则可能就把它当成真实选择器了又比如字符串里包含.btn-primary正则也会算作引用。但 AST 方案会明确区分注释、字符串、真正的选择器节点不会把这些干扰项算进去。类似“媒体查询里的嵌套选择器”“带伪元素的.btn:hover这种复合选择器”在 AST 眼里都能准确还原结构这是正则想做到却很难做好的。可以这样理解正则就像拿照妖镜扫人看到长得像就喊“妖”AST 则像看身份证一条一条核对姓名、住址、关系。前者快但容易误判后者多花了一点时间但结论可靠得多。2.2 三阶段流水线scan → report → pruneponytail 的工作方式可以分成三个阶段。第一个阶段是scan扫描。它会读取你指定的 CSS/SCSS 源文件同时扫描匹配的模板文件HTML、Vue、JSX、TSX 等都靠配置里的patterns字段来声明。这一步输出的是一份原始分析数据标记出每个选择器被引用的情况、每个声明块的重复情况。第二个阶段是report生成报告。scan拿到数据后ponytail 会按规则整理成一份结构化报告哪些选择器从未被引用、哪些选择器被多次重复定义、哪些声明块是冗余的、每个文件的冗余体积占比等等。报告是 JSON 格式的方便导入其他工具或让 AI 读取。第三个阶段是prune修剪。报告确认无误后可以用prune指令执行清理比如删除未被引用的选择器、合并重复声明、简化可缩短的选择器写法。这一步可以预演、可以备份、可以输出 diff防止出现“清理一时爽上线火葬场”的情况。这个三阶段设计最大的好处是“扫描和清理分离”。我可以在上午跑完scan中午把报告交给同事 review下午再执行prune。谁也不想让一个工具不经确认就直接删代码分离之后人工判断的空间就出来了。2.3 配置文件的字段设计和安全机制ponytail 的配置文件默认是ponytail.config.js用起来很像eslint.config.js或者prettier.config.js导出一个对象就行。我常用的配置项大概有这几类source要分析样式文件的位置。patterns要匹配的模板文件支持 glob 语法比如**/*.html、src/**/*.vue。ignore哪些样式文件完全不参与分析比如第三方库的覆盖文件。whitelist白名单选择器即使没在模板中找到引用也强制保留通常用于动态拼接类名。dynamicPatterns动态类名模式比如/^is-|^has-|^js-/用来识别 JS 中拼接出来的类名。output报告输出路径。threshold冗余比例阈值超过该值则让 CI 失败。backup是否在修剪前自动备份原文件。安全机制主要靠“先预演再修改”的默认行为。prune命令默认不直接改文件必须显式加上--apply才会写入。没有--apply时它只输出一份类似git diff的内容。这个设计让我在团队里推行时底气足了很多毕竟同事最担心的就是“这工具会不会一跑就把我线上样式全删了”。3. 从零开始安装、配置、跑通第一条扫描3.1 安装的两种方式CLI 直装和 Skill 封装如果你是第一次接触我建议先通过 npm 以 CLI 方式安装快速体验一遍它的完整流程。npm install -D ponytail-cli也可以不装到项目里直接用 npx 临时执行npx ponytail-cli --version等对命令和输出都熟悉了再考虑把它以 “ponytail skill” 的形式接入 AI 工作流。接入 AI 时一般要先把 CLI 装到当前项目里然后创建一个skills/ponytail/SKILL.md文件内容大致包括这个 skill 是做什么的负责扫描、分析、清理 CSS 样式冗余。可执行的命令清单比如npx ponytail-cli scan --config ponytail.config.js。输出的位置和格式比如会生成ponytail-report.jsonAI 直接读这个文件。安全规则AI 不能跳过 dry-run不能直接执行带--apply的修剪除非用户明确确认。这样配置好以后当你在 AI 对话框里说“帮我看一下目前样式里有哪几个未使用的类名”AI 会自动加载 skill然后执行命令并阅读报告。说白了就是你把 ponytail 的操作手册塞给了 AIAI 变成会用工具的操作员而工具本身还是那个 CLI。3.2 最小配置一份能直接用的 ponytail.config.js我习惯先写一份最简配置跑通流程后再慢慢加规则。比如这样一个项目结构my-project/ ├── src/ │ ├── styles/ │ │ └── global.css │ └── pages/ │ ├── index.html │ └── about.html └── ponytail.config.js配置文件可以这样写// ponytail.config.js module.exports { source: [src/**/*.css], patterns: [src/**/*.html], ignore: [], whitelist: [is-active, has-error], dynamicPatterns: [/^js-/], output: ponytail-report.json, backup: true, };这里dynamicPatterns里的/^js-/常见于老项目里这样的代码div classjs-modal js-modal--open/div如果 ponytail 只扫描 HTML它确实能看到js-modal--open这个具体字符串但如果项目里有 JS 负责拼接类名比如el.className js-modal flag ? is-open : ;那is-open就不会出现在任何模板文件里这时候白名单whitelist或者dynamicPatterns就起到了保命作用。3.3 第一次实操扫描一个老项目并读懂报告配置文件写好后运行npx ponytail-cli scan命令执行完控制台会看到简要统计同时生成ponytail-report.json。我拿一个模拟场景来演示假设global.css中有以下几个类.header { background: #fff; } .header__logo { width: 120px; } .is-active { color: red; } .unused-box { padding: 20px; } .js-modal { display: none; }index.html里实际用到了header classheader img classheader__logo srclogo.png altlogo /header对应的 JSON 报告会是这样我简化了部分字段{ files: { src/styles/global.css: { totalRules: 5, unusedSelectors: [.unused-box], usedSelectors: [.header, .header__logo, .is-active, .js-modal], redundantBytes: 28, redundantRatio: 0.18 } }, summary: { totalFiles: 1, totalRedundantBytes: 28, totalRedundantRatio: 0.18 } }注意这里的.is-active和.js-modal虽然没在index.html里出现但它们命中了我配置里的whitelist和dynamicPatterns所以被标记为已使用。.unused-box则确认是未使用状态可以直接进入清理流程。第一次看到报告时别急着执行清理。先检查几个地方第一有没有你以为在用、但实际上完全没被引用的类名这类往往是活动页遗留第二有没有动态拼接类的模式没配全这类需要加到whitelist第三有没有第三方库的样式被错误地当成了项目自己的样式这类需要移入ignore。4. 核心实操如何安全地清理样式4.1 用 dry-run 预演让修改可见、可控清理是对代码动手最忌讳的是闷头直接改。ponytail 的prune命令默认就是 dry-run意思是它会算出该怎么改但不动文件。npx ponytail-cli prune执行后输出会类似git diff清清楚楚地显示哪些选择器要被删掉、哪些声明块会被合并。比如上面的.unused-box预期输出是- .unused-box { - padding: 20px; - }确认无误后再真正应用修改npx ponytail-cli prune --apply如果你开了backup: true运行前会生成一份带时间戳的备份文件比如global.css.20240612-153000.bak。我强烈建议不要关掉这个备份尤其是首次在大项目上操作时。即使报告看起来再准确也难免有业务逻辑里的黑魔法多个备份就是多一条后悔路。4.2 自动简化选择器与合并重复声明清理不只是“删未使用的样式”它还包含两个很实用的能力简化选择器和合并重复声明。所谓简化选择器典型场景是这样.header .header .header__logo { width: 120px; }如果项目里不存在嵌套层级这个第三层.header就是冗余的ponytail 可以把它简化为.header__logo { width: 120px; }这个能力用 AST 算起来比较稳因为它会就地分析层级是否真的重复不是无脑删选择器。还有一类是重复声明合并.card { margin: 16px; } .card { padding: 8px; }这两条规则完全可以合到一条里.card { margin: 16px; padding: 8px; }重复声明合并能减少文件体积也能让后续维护的人一眼看清某类名下到底挂了多少属性。尤其在老项目里同一种类名在三个地方各写一半属性是常态合并以后简直像打开了“乱发打结处”。清理结束后可以再跑一次scan看对比数据。上面的示例项目本来冗余比例是 18%清理后会变成 0%。实际项目可能不会一次清零但每轮迭代后那份报告会变成你和同事沟通的好依据。4.3 对接 AI 工作流ponytail skill 的提示词设计如果你已经安装好 CLI也配置好了 skill 文件真正让 AI 跑起来其实只需要一段很自然的对话。比如帮我看一下src/styles/global.css里有哪些未使用的样式先扫描并输出报告不要删除任何东西。AI 在后台会加载 ponytail skill执行类似这样的命令npx ponytail-cli scan --config ponytail.config.js然后读取生成的 JSON用自然语言总结给你。等你确认“可以清理”之后再说根据刚才的报告执行清理但先不要应用修改只给我看 diff。这就会调用npx ponytail-cli prune最后你看到 diff 没问题再说“应用修改”AI 再执行npx ponytail-cli prune --apply这个“AI 只负责调用和总结、你负责最终确认”的模式是我觉得最稳妥的用法。因为 AI 的能力长处是理解上下文和生成操作但对每一个线上项目的业务逻辑并不真正了解。真正了解的是你所以最终确认权必须留给自己。5. 常见问题与排查技巧实录5.1 动态类名导致误报最常见的误报场景就是动态类名。很多现代前端项目不会把所有类名都写死在模板里而是通过状态控制拼接比如is-开头的状态类、has-开头的存在类甚至还有col-${n}这种循环生成的栅格类。如果 ponytail 报告里出现了“误报”先别急着把选择器加入白名单。先检查项目里有没有下面的写法className{btn ${isLoading ? is-loading : }}这种情况下is-loading在模板文件里确实没有字符串出现但它是真实会生效的。解决办法有两个方向一是把这类模式补进dynamicPatterns比如用正则/^is-/、/^has-/二是如果你知道所有可能的取值直接写进whitelist。我更推荐在项目初期就把动态类名的规则收集齐。因为一旦清理报告被误报污染真正冗余的样式会被埋没在一堆假信号里工具的可信度就大打折扣。5.2 框架 scoped 样式和 CSS Modules 的处理Vue 的 scoped 样式、CSS Modules 这类技术会让选择器带上特殊标记比如.header[data-v-xxxx]、.footer_abc123__box。ponytail 默认对标准 CSS 的 AST 解析是没问题的但你需要额外注意模板引用的匹配方式。以 Vue 为例要在patterns里加上.vue文件patterns: [src/**/*.vue],同时如果组件里写了非 scoped 的:global()规则而这些规则可能被其他组件引用你需要把对应类名纳入白名单因为只扫描单个组件文件时ponytail 是看不到全局引用的。在处理 CSS Modules 时类名经过编译后会变成哈希值ponytail 扫描源码是无法直接对应上的。我的建议是让扫描器匹配源码里写的最初类名比如.box而不是编译后的.box_abc123所以你需要确认项目里的模板文件使用的是源码类名。如果项目里同时存在 scoped 和全局样式文件建议把 scoped 文件单独分组处理不要和全局样式混在一次source配置里。否则全局扫描会把 scoped 样式大量标记为未使用造成误报。5.3 命令行超时、内存不足和提速技巧样式文件一旦多起来比如几千个 CSS 文件和上万个模板文件扫描可能遇到两个问题内存占用高、执行时间长。内存问题通常和 glob patterns 太宽有关。比如你把node_modules也包含进去了那扫描会卡到怀疑人生。务必在source和patterns中明确范围或者用ignore排除ignore: [node_modules/**, dist/**, .next/**],如果项目实在太大还可以限制并发分析。ponytail 内部是多线程并行解析文件有时并发过高反而会拖垮机器可以降低并发数比如npx ponytail-cli scan --concurrency 4执行时间方面最省事的办法是分模块扫描。不要一次性扫描整个项目的所有 CSS而是按业务模块拆分命令把报告输出到不同文件。这样不仅快而且更容易定位问题哪个模块报告异常就直接看哪个模块。我还习惯在 CI 里给扫描设置一个“宽限期”。第一次接入时先不设threshold跑一两周建立基线然后再设置阈值比如“冗余比例不得超过 5%”。这样不会因为历史债务太厚导致 CI 直接挂掉而是给团队一个逐步清理的缓冲空间。5.4 常见的误删场景与如何恢复尽管工具设计得再安全执行prune --apply后偶尔还是会出现样式丢失的情况。比较典型的几种场景类名和 ID 选择器同时存在模板里只引用了 ID但 CSS 里还有基于类名的样式且这个类名是其他脚本动态加上的。使用import引入了另一个文件被引入文件中的样式在扫描主文件时没有被标记到。第三方插件在运行时往 DOM 上追加类名不在模板文件里也不在 JS 源码里完全无法通过静态分析发现。针对这三种情况我的实操建议是第一凡是在报告里标记为“未使用”的类名先全局搜索一下源码包括 JS 文件和 JSON 配置确认真的没有引用再删第二把import的文件独立加入source让 ponytail 单独分析第三给项目里所有第三方插件前缀的类名建一个固定的whitelist段比如slick-、tab-、swiper-这类直接声明“凡是这种前缀都保留”。如果已经误删并推送了代码不要慌张只要开了backup: true就能从备份文件恢复。备份文件一般在项目根目录或源文件同目录下按时间戳命名。恢复以后记得把对应的类名加进whitelist避免下次再被误删。6. 我实际使用后的几点体会工具再好最终还是看用的人怎么和它相处。我在把 ponytail 接入老项目以后最大的感受是样式清理这件事终于不再靠“谁胆大谁删”来推动了。以前每次做样式重构都得开一堆浏览器标签页反复比对小心翼翼注释掉一块样式再刷新看效果效率低不说还容易漏。现在有了报告和数据团队里讨论“这个类能不能删”时可以直接把扫描记录贴出来省掉很多无效争论。同时我也想说不要把 ponytail 的报告当成绝对真理。静态分析能发现的是“在当前代码库里存在或不存在引用”但业务系统里总有动态加载、第三方脚本、线上配置这些它看不见的部分。它的价值是帮你把 90% 的确定性冗余挑出来剩下 10% 的不确定项还是需要人来做最终判断。我给自己定的规矩是凡是要删的类名先看报告再全局搜一遍最后在测试环境过一遍相关页面。这套流程下来我使用期间基本没有出现过线上样式事故。如果后续你还想继续扩展可以试试把 ponytail 和覆盖率统计结合起来定期扫描报告里的冗余比例趋势看看团队在样式维护上是变好了还是变糟了。数据不会说谎样式文件从 200KB 瘦到 80KB 以后同事再也不敢随手往全局样式里塞一个只服务于单个页面的类名了。这也是我越来越愿意把这套工具分享出去的原因。
ponytail插件：用AST给CSS样式“扎辫子”，安全清理冗余样式
最近前端群里好几个人都在问 ponytail 插件到底怎么用尤其是“ponytail skill”这个叫法听起来像是个新出的玩具。其实它是一套专门用来给 CSS 样式文件“收辫子”的工具——扫描、标记、清理、重构把散落各处的冗余样式统一归拢所以叫 ponytail马尾辫。如果你经常被几百行没人敢动的global.css劝退或者每次改完 HTML 都要提心吊胆地查样式有没有挂掉这篇就是给你写的。ponytail 不是一个花哨的 UI 组件库也不是动画库它更像是前端工程化里的“样式整理师”。我会从设计思路讲起再给出一套可以直接照抄的安装、配置、实操流程最后把我踩过的坑和排查逻辑一并整理出来。不管你是刚接触前端工程化的新人还是维护老项目到头疼的资深开发应该都能从中拿到点能立刻用得上的东西。1. 先搞清楚 ponytail 是什么以及它想解决什么问题1.1 一个很形象的命名马尾辫“ponytail”直译过来是马尾辫这个命名其实特别直白。一个项目跑久了几乎不可避免地会出现这类状况.btn定义了好几次有的在基础样式里有的在页面级样式里当年做活动页留下的.active-banner-2023早就没人用了但文件里还堂而皇之地躺着还有一些选择器嵌套五六层拆开来看全是重复声明。这时候整个样式文件就像一头没梳理的乱发看着厚重实际上有用的大概只有一半。ponytail 想做的就是拿一根皮筋把这些头发扎起来——先梳顺再扎紧最后让那些飘在外面、已经失去作用的碎发直接剪掉。这根“皮筋”就是它的核心流程通过静态分析扫描项目里所有 CSS/SCSS 文件和匹配的模板文件找出真正被引用的选择器、真正生效的声明块然后把冗余部分标记出来给你一份可执行的清理报告。所以 ponytail 不适合用“样式检查工具”来简单定义。它更像一个带有重构建议的“样式瘦身器”重点不在挑错而在帮你安全地做减法。尤其当你面对一个没有测试覆盖、样式文件历史包袱很重的老项目时这种“先分析、再报告、最后动手”的方式会比人工眼睛排查可靠得多。1.2 ponytail skill 和 ponytail 插件之间的关系很多人在搜索“ponytail skill”和“ponytail 插件”时容易把它们当成两个东西。实际上它们指的是同一个工具在不同形态下的两种使用方式。“插件”形态通常是可以直接安装的 CLI 工具通过npx ponytail或全局命令执行扫描、输出报告、自动修剪。这种形态适合本地开发、CI 流水线一切都在命令行里完成输出是 JSON 格式的报告方便后续处理。“skill”形态则是给 AI 编程助手用的封装。现在很多 AI 编程环境支持“自定义技能”本质上是把一个结构化的操作手册Markdown和配套脚本放进指定的skills目录AI 在回答相关问题时会自动加载这个技能知道应该调用哪些命令、怎么解析报告、怎么安全地修改样式文件。你可以把 skill 理解成“教 AI 使用 ponytail 的说明书”而说明书背后仍然是那套 CLI 在干活。这两种形态并不互斥。我实际使用时的做法是本地先装好 CLI把配置写好、规则调好然后在 AI 助手的工作区里放一份对应版本的 skill 文件。这样如果需要 AI 帮忙批量处理样式它就能按照我给它的操作流程去调用 CLI、读懂结果而不是凭空猜测该怎么清理。1.3 适用场景与不适合的场景先说它擅长的场景。第一类是多年没敢大动的业务项目样式文件成百上千行注释里写着“此处不要删线上正在用”但没人知道到底哪部分在用这时候 ponytail 能给出基于代码引用关系的客观判断。第二类是重构前的摸底比如准备把老项目从 jQuery 迁移到 Vue或者准备引入 Tailwind你需要在动手前知道现有样式体系里哪些是可以放弃的哪些是必须保留的。第三类是 CI 卡点要求在合并请求前把冗余样式比例控制在一定阈值以内ponytail 可以无缝接进流水线。但它也有明显不适合的场景。如果你的项目是纯组件库每一个样式类都直接对应组件 API而且已经有完善的单元测试那么用 stylelint 或者 TypeScript 类型检查可能更直接ponytail 的“扫描引用”反而会因组件动态用法太多而误报。如果你用了 CSS-in-JS比如 styled-components样式不是以独立文件存在的ponytail 也基本派不上用场因为它擅长的是静态文件层面的分析。所以选择工具之前先对号入座有历史包袱、有静态样式文件、有模板可查这三条都满足的时候ponytail 就是那个能把头发扎起来的皮筋。2. 上手前需要理解的核心设计2.1 为什么 AST 比正则靠谱我见过不少人第一次拿到 ponytail 的扫描结果第一反应是“这不就是正则匹配吗”实际上它底层用的是样式解析器先把 CSS 转成 AST抽象语法树再对模板里的 class 引用做标记最后把两者比对。简单来说AST 是把样式文件的结构拆成可编程操作的树形数据而不是像正则那样只看字符层面的匹配。正则方案最大的问题是容易误伤。比如注释里写了一行.old-style {}的示例代码正则可能就把它当成真实选择器了又比如字符串里包含.btn-primary正则也会算作引用。但 AST 方案会明确区分注释、字符串、真正的选择器节点不会把这些干扰项算进去。类似“媒体查询里的嵌套选择器”“带伪元素的.btn:hover这种复合选择器”在 AST 眼里都能准确还原结构这是正则想做到却很难做好的。可以这样理解正则就像拿照妖镜扫人看到长得像就喊“妖”AST 则像看身份证一条一条核对姓名、住址、关系。前者快但容易误判后者多花了一点时间但结论可靠得多。2.2 三阶段流水线scan → report → pruneponytail 的工作方式可以分成三个阶段。第一个阶段是scan扫描。它会读取你指定的 CSS/SCSS 源文件同时扫描匹配的模板文件HTML、Vue、JSX、TSX 等都靠配置里的patterns字段来声明。这一步输出的是一份原始分析数据标记出每个选择器被引用的情况、每个声明块的重复情况。第二个阶段是report生成报告。scan拿到数据后ponytail 会按规则整理成一份结构化报告哪些选择器从未被引用、哪些选择器被多次重复定义、哪些声明块是冗余的、每个文件的冗余体积占比等等。报告是 JSON 格式的方便导入其他工具或让 AI 读取。第三个阶段是prune修剪。报告确认无误后可以用prune指令执行清理比如删除未被引用的选择器、合并重复声明、简化可缩短的选择器写法。这一步可以预演、可以备份、可以输出 diff防止出现“清理一时爽上线火葬场”的情况。这个三阶段设计最大的好处是“扫描和清理分离”。我可以在上午跑完scan中午把报告交给同事 review下午再执行prune。谁也不想让一个工具不经确认就直接删代码分离之后人工判断的空间就出来了。2.3 配置文件的字段设计和安全机制ponytail 的配置文件默认是ponytail.config.js用起来很像eslint.config.js或者prettier.config.js导出一个对象就行。我常用的配置项大概有这几类source要分析样式文件的位置。patterns要匹配的模板文件支持 glob 语法比如**/*.html、src/**/*.vue。ignore哪些样式文件完全不参与分析比如第三方库的覆盖文件。whitelist白名单选择器即使没在模板中找到引用也强制保留通常用于动态拼接类名。dynamicPatterns动态类名模式比如/^is-|^has-|^js-/用来识别 JS 中拼接出来的类名。output报告输出路径。threshold冗余比例阈值超过该值则让 CI 失败。backup是否在修剪前自动备份原文件。安全机制主要靠“先预演再修改”的默认行为。prune命令默认不直接改文件必须显式加上--apply才会写入。没有--apply时它只输出一份类似git diff的内容。这个设计让我在团队里推行时底气足了很多毕竟同事最担心的就是“这工具会不会一跑就把我线上样式全删了”。3. 从零开始安装、配置、跑通第一条扫描3.1 安装的两种方式CLI 直装和 Skill 封装如果你是第一次接触我建议先通过 npm 以 CLI 方式安装快速体验一遍它的完整流程。npm install -D ponytail-cli也可以不装到项目里直接用 npx 临时执行npx ponytail-cli --version等对命令和输出都熟悉了再考虑把它以 “ponytail skill” 的形式接入 AI 工作流。接入 AI 时一般要先把 CLI 装到当前项目里然后创建一个skills/ponytail/SKILL.md文件内容大致包括这个 skill 是做什么的负责扫描、分析、清理 CSS 样式冗余。可执行的命令清单比如npx ponytail-cli scan --config ponytail.config.js。输出的位置和格式比如会生成ponytail-report.jsonAI 直接读这个文件。安全规则AI 不能跳过 dry-run不能直接执行带--apply的修剪除非用户明确确认。这样配置好以后当你在 AI 对话框里说“帮我看一下目前样式里有哪几个未使用的类名”AI 会自动加载 skill然后执行命令并阅读报告。说白了就是你把 ponytail 的操作手册塞给了 AIAI 变成会用工具的操作员而工具本身还是那个 CLI。3.2 最小配置一份能直接用的 ponytail.config.js我习惯先写一份最简配置跑通流程后再慢慢加规则。比如这样一个项目结构my-project/ ├── src/ │ ├── styles/ │ │ └── global.css │ └── pages/ │ ├── index.html │ └── about.html └── ponytail.config.js配置文件可以这样写// ponytail.config.js module.exports { source: [src/**/*.css], patterns: [src/**/*.html], ignore: [], whitelist: [is-active, has-error], dynamicPatterns: [/^js-/], output: ponytail-report.json, backup: true, };这里dynamicPatterns里的/^js-/常见于老项目里这样的代码div classjs-modal js-modal--open/div如果 ponytail 只扫描 HTML它确实能看到js-modal--open这个具体字符串但如果项目里有 JS 负责拼接类名比如el.className js-modal flag ? is-open : ;那is-open就不会出现在任何模板文件里这时候白名单whitelist或者dynamicPatterns就起到了保命作用。3.3 第一次实操扫描一个老项目并读懂报告配置文件写好后运行npx ponytail-cli scan命令执行完控制台会看到简要统计同时生成ponytail-report.json。我拿一个模拟场景来演示假设global.css中有以下几个类.header { background: #fff; } .header__logo { width: 120px; } .is-active { color: red; } .unused-box { padding: 20px; } .js-modal { display: none; }index.html里实际用到了header classheader img classheader__logo srclogo.png altlogo /header对应的 JSON 报告会是这样我简化了部分字段{ files: { src/styles/global.css: { totalRules: 5, unusedSelectors: [.unused-box], usedSelectors: [.header, .header__logo, .is-active, .js-modal], redundantBytes: 28, redundantRatio: 0.18 } }, summary: { totalFiles: 1, totalRedundantBytes: 28, totalRedundantRatio: 0.18 } }注意这里的.is-active和.js-modal虽然没在index.html里出现但它们命中了我配置里的whitelist和dynamicPatterns所以被标记为已使用。.unused-box则确认是未使用状态可以直接进入清理流程。第一次看到报告时别急着执行清理。先检查几个地方第一有没有你以为在用、但实际上完全没被引用的类名这类往往是活动页遗留第二有没有动态拼接类的模式没配全这类需要加到whitelist第三有没有第三方库的样式被错误地当成了项目自己的样式这类需要移入ignore。4. 核心实操如何安全地清理样式4.1 用 dry-run 预演让修改可见、可控清理是对代码动手最忌讳的是闷头直接改。ponytail 的prune命令默认就是 dry-run意思是它会算出该怎么改但不动文件。npx ponytail-cli prune执行后输出会类似git diff清清楚楚地显示哪些选择器要被删掉、哪些声明块会被合并。比如上面的.unused-box预期输出是- .unused-box { - padding: 20px; - }确认无误后再真正应用修改npx ponytail-cli prune --apply如果你开了backup: true运行前会生成一份带时间戳的备份文件比如global.css.20240612-153000.bak。我强烈建议不要关掉这个备份尤其是首次在大项目上操作时。即使报告看起来再准确也难免有业务逻辑里的黑魔法多个备份就是多一条后悔路。4.2 自动简化选择器与合并重复声明清理不只是“删未使用的样式”它还包含两个很实用的能力简化选择器和合并重复声明。所谓简化选择器典型场景是这样.header .header .header__logo { width: 120px; }如果项目里不存在嵌套层级这个第三层.header就是冗余的ponytail 可以把它简化为.header__logo { width: 120px; }这个能力用 AST 算起来比较稳因为它会就地分析层级是否真的重复不是无脑删选择器。还有一类是重复声明合并.card { margin: 16px; } .card { padding: 8px; }这两条规则完全可以合到一条里.card { margin: 16px; padding: 8px; }重复声明合并能减少文件体积也能让后续维护的人一眼看清某类名下到底挂了多少属性。尤其在老项目里同一种类名在三个地方各写一半属性是常态合并以后简直像打开了“乱发打结处”。清理结束后可以再跑一次scan看对比数据。上面的示例项目本来冗余比例是 18%清理后会变成 0%。实际项目可能不会一次清零但每轮迭代后那份报告会变成你和同事沟通的好依据。4.3 对接 AI 工作流ponytail skill 的提示词设计如果你已经安装好 CLI也配置好了 skill 文件真正让 AI 跑起来其实只需要一段很自然的对话。比如帮我看一下src/styles/global.css里有哪些未使用的样式先扫描并输出报告不要删除任何东西。AI 在后台会加载 ponytail skill执行类似这样的命令npx ponytail-cli scan --config ponytail.config.js然后读取生成的 JSON用自然语言总结给你。等你确认“可以清理”之后再说根据刚才的报告执行清理但先不要应用修改只给我看 diff。这就会调用npx ponytail-cli prune最后你看到 diff 没问题再说“应用修改”AI 再执行npx ponytail-cli prune --apply这个“AI 只负责调用和总结、你负责最终确认”的模式是我觉得最稳妥的用法。因为 AI 的能力长处是理解上下文和生成操作但对每一个线上项目的业务逻辑并不真正了解。真正了解的是你所以最终确认权必须留给自己。5. 常见问题与排查技巧实录5.1 动态类名导致误报最常见的误报场景就是动态类名。很多现代前端项目不会把所有类名都写死在模板里而是通过状态控制拼接比如is-开头的状态类、has-开头的存在类甚至还有col-${n}这种循环生成的栅格类。如果 ponytail 报告里出现了“误报”先别急着把选择器加入白名单。先检查项目里有没有下面的写法className{btn ${isLoading ? is-loading : }}这种情况下is-loading在模板文件里确实没有字符串出现但它是真实会生效的。解决办法有两个方向一是把这类模式补进dynamicPatterns比如用正则/^is-/、/^has-/二是如果你知道所有可能的取值直接写进whitelist。我更推荐在项目初期就把动态类名的规则收集齐。因为一旦清理报告被误报污染真正冗余的样式会被埋没在一堆假信号里工具的可信度就大打折扣。5.2 框架 scoped 样式和 CSS Modules 的处理Vue 的 scoped 样式、CSS Modules 这类技术会让选择器带上特殊标记比如.header[data-v-xxxx]、.footer_abc123__box。ponytail 默认对标准 CSS 的 AST 解析是没问题的但你需要额外注意模板引用的匹配方式。以 Vue 为例要在patterns里加上.vue文件patterns: [src/**/*.vue],同时如果组件里写了非 scoped 的:global()规则而这些规则可能被其他组件引用你需要把对应类名纳入白名单因为只扫描单个组件文件时ponytail 是看不到全局引用的。在处理 CSS Modules 时类名经过编译后会变成哈希值ponytail 扫描源码是无法直接对应上的。我的建议是让扫描器匹配源码里写的最初类名比如.box而不是编译后的.box_abc123所以你需要确认项目里的模板文件使用的是源码类名。如果项目里同时存在 scoped 和全局样式文件建议把 scoped 文件单独分组处理不要和全局样式混在一次source配置里。否则全局扫描会把 scoped 样式大量标记为未使用造成误报。5.3 命令行超时、内存不足和提速技巧样式文件一旦多起来比如几千个 CSS 文件和上万个模板文件扫描可能遇到两个问题内存占用高、执行时间长。内存问题通常和 glob patterns 太宽有关。比如你把node_modules也包含进去了那扫描会卡到怀疑人生。务必在source和patterns中明确范围或者用ignore排除ignore: [node_modules/**, dist/**, .next/**],如果项目实在太大还可以限制并发分析。ponytail 内部是多线程并行解析文件有时并发过高反而会拖垮机器可以降低并发数比如npx ponytail-cli scan --concurrency 4执行时间方面最省事的办法是分模块扫描。不要一次性扫描整个项目的所有 CSS而是按业务模块拆分命令把报告输出到不同文件。这样不仅快而且更容易定位问题哪个模块报告异常就直接看哪个模块。我还习惯在 CI 里给扫描设置一个“宽限期”。第一次接入时先不设threshold跑一两周建立基线然后再设置阈值比如“冗余比例不得超过 5%”。这样不会因为历史债务太厚导致 CI 直接挂掉而是给团队一个逐步清理的缓冲空间。5.4 常见的误删场景与如何恢复尽管工具设计得再安全执行prune --apply后偶尔还是会出现样式丢失的情况。比较典型的几种场景类名和 ID 选择器同时存在模板里只引用了 ID但 CSS 里还有基于类名的样式且这个类名是其他脚本动态加上的。使用import引入了另一个文件被引入文件中的样式在扫描主文件时没有被标记到。第三方插件在运行时往 DOM 上追加类名不在模板文件里也不在 JS 源码里完全无法通过静态分析发现。针对这三种情况我的实操建议是第一凡是在报告里标记为“未使用”的类名先全局搜索一下源码包括 JS 文件和 JSON 配置确认真的没有引用再删第二把import的文件独立加入source让 ponytail 单独分析第三给项目里所有第三方插件前缀的类名建一个固定的whitelist段比如slick-、tab-、swiper-这类直接声明“凡是这种前缀都保留”。如果已经误删并推送了代码不要慌张只要开了backup: true就能从备份文件恢复。备份文件一般在项目根目录或源文件同目录下按时间戳命名。恢复以后记得把对应的类名加进whitelist避免下次再被误删。6. 我实际使用后的几点体会工具再好最终还是看用的人怎么和它相处。我在把 ponytail 接入老项目以后最大的感受是样式清理这件事终于不再靠“谁胆大谁删”来推动了。以前每次做样式重构都得开一堆浏览器标签页反复比对小心翼翼注释掉一块样式再刷新看效果效率低不说还容易漏。现在有了报告和数据团队里讨论“这个类能不能删”时可以直接把扫描记录贴出来省掉很多无效争论。同时我也想说不要把 ponytail 的报告当成绝对真理。静态分析能发现的是“在当前代码库里存在或不存在引用”但业务系统里总有动态加载、第三方脚本、线上配置这些它看不见的部分。它的价值是帮你把 90% 的确定性冗余挑出来剩下 10% 的不确定项还是需要人来做最终判断。我给自己定的规矩是凡是要删的类名先看报告再全局搜一遍最后在测试环境过一遍相关页面。这套流程下来我使用期间基本没有出现过线上样式事故。如果后续你还想继续扩展可以试试把 ponytail 和覆盖率统计结合起来定期扫描报告里的冗余比例趋势看看团队在样式维护上是变好了还是变糟了。数据不会说谎样式文件从 200KB 瘦到 80KB 以后同事再也不敢随手往全局样式里塞一个只服务于单个页面的类名了。这也是我越来越愿意把这套工具分享出去的原因。