最近前端群里好幾個人都在問 ponytail 插件到底怎么用尤其是“ponytail skill”這個叫法聽起來像是個新出的玩具。其實它是一套專門用來給 CSS 樣式文件“收辮子”的工具——掃描、標(biāo)記、清理、重構(gòu)把散落各處的冗余樣式統(tǒng)一歸攏所以叫 ponytail馬尾辮。如果你經(jīng)常被幾百行沒人敢動的global.css勸退或者每次改完 HTML 都要提心吊膽地查樣式有沒有掛掉這篇就是給你寫的。ponytail 不是一個花哨的 UI 組件庫也不是動畫庫它更像是前端工程化里的“樣式整理師”。我會從設(shè)計思路講起再給出一套可以直接照抄的安裝、配置、實操流程最后把我踩過的坑和排查邏輯一并整理出來。不管你是剛接觸前端工程化的新人還是維護(hù)老項目到頭疼的資深開發(fā)應(yīng)該都能從中拿到點能立刻用得上的東西。1. 先搞清楚 ponytail 是什么以及它想解決什么問題1.1 一個很形象的命名馬尾辮“ponytail”直譯過來是馬尾辮這個命名其實特別直白。一個項目跑久了幾乎不可避免地會出現(xiàn)這類狀況.btn定義了好幾次有的在基礎(chǔ)樣式里有的在頁面級樣式里當(dāng)年做活動頁留下的.active-banner-2023早就沒人用了但文件里還堂而皇之地躺著還有一些選擇器嵌套五六層拆開來看全是重復(fù)聲明。這時候整個樣式文件就像一頭沒梳理的亂發(fā)看著厚重實際上有用的大概只有一半。ponytail 想做的就是拿一根皮筋把這些頭發(fā)扎起來——先梳順再扎緊最后讓那些飄在外面、已經(jīng)失去作用的碎發(fā)直接剪掉。這根“皮筋”就是它的核心流程通過靜態(tài)分析掃描項目里所有 CSS/SCSS 文件和匹配的模板文件找出真正被引用的選擇器、真正生效的聲明塊然后把冗余部分標(biāo)記出來給你一份可執(zhí)行的清理報告。所以 ponytail 不適合用“樣式檢查工具”來簡單定義。它更像一個帶有重構(gòu)建議的“樣式瘦身器”重點不在挑錯而在幫你安全地做減法。尤其當(dāng)你面對一個沒有測試覆蓋、樣式文件歷史包袱很重的老項目時這種“先分析、再報告、最后動手”的方式會比人工眼睛排查可靠得多。1.2 ponytail skill 和 ponytail 插件之間的關(guān)系很多人在搜索“ponytail skill”和“ponytail 插件”時容易把它們當(dāng)成兩個東西。實際上它們指的是同一個工具在不同形態(tài)下的兩種使用方式。“插件”形態(tài)通常是可以直接安裝的 CLI 工具通過npx ponytail或全局命令執(zhí)行掃描、輸出報告、自動修剪。這種形態(tài)適合本地開發(fā)、CI 流水線一切都在命令行里完成輸出是 JSON 格式的報告方便后續(xù)處理?！皊kill”形態(tài)則是給 AI 編程助手用的封裝。現(xiàn)在很多 AI 編程環(huán)境支持“自定義技能”本質(zhì)上是把一個結(jié)構(gòu)化的操作手冊Markdown和配套腳本放進(jìn)指定的skills目錄AI 在回答相關(guān)問題時會自動加載這個技能知道應(yīng)該調(diào)用哪些命令、怎么解析報告、怎么安全地修改樣式文件。你可以把 skill 理解成“教 AI 使用 ponytail 的說明書”而說明書背后仍然是那套 CLI 在干活。這兩種形態(tài)并不互斥。我實際使用時的做法是本地先裝好 CLI把配置寫好、規(guī)則調(diào)好然后在 AI 助手的工作區(qū)里放一份對應(yīng)版本的 skill 文件。這樣如果需要 AI 幫忙批量處理樣式它就能按照我給它的操作流程去調(diào)用 CLI、讀懂結(jié)果而不是憑空猜測該怎么清理。1.3 適用場景與不適合的場景先說它擅長的場景。第一類是多年沒敢大動的業(yè)務(wù)項目樣式文件成百上千行注釋里寫著“此處不要刪線上正在用”但沒人知道到底哪部分在用這時候 ponytail 能給出基于代碼引用關(guān)系的客觀判斷。第二類是重構(gòu)前的摸底比如準(zhǔn)備把老項目從 jQuery 遷移到 Vue或者準(zhǔn)備引入 Tailwind你需要在動手前知道現(xiàn)有樣式體系里哪些是可以放棄的哪些是必須保留的。第三類是 CI 卡點要求在合并請求前把冗余樣式比例控制在一定閾值以內(nèi)ponytail 可以無縫接進(jìn)流水線。但它也有明顯不適合的場景。如果你的項目是純組件庫每一個樣式類都直接對應(yīng)組件 API而且已經(jīng)有完善的單元測試那么用 stylelint 或者 TypeScript 類型檢查可能更直接ponytail 的“掃描引用”反而會因組件動態(tài)用法太多而誤報。如果你用了 CSS-in-JS比如 styled-components樣式不是以獨立文件存在的ponytail 也基本派不上用場因為它擅長的是靜態(tài)文件層面的分析。所以選擇工具之前先對號入座有歷史包袱、有靜態(tài)樣式文件、有模板可查這三條都滿足的時候ponytail 就是那個能把頭發(fā)扎起來的皮筋。2. 上手前需要理解的核心設(shè)計2.1 為什么 AST 比正則靠譜我見過不少人第一次拿到 ponytail 的掃描結(jié)果第一反應(yīng)是“這不就是正則匹配嗎”實際上它底層用的是樣式解析器先把 CSS 轉(zhuǎn)成 AST抽象語法樹再對模板里的 class 引用做標(biāo)記最后把兩者比對。簡單來說AST 是把樣式文件的結(jié)構(gòu)拆成可編程操作的樹形數(shù)據(jù)而不是像正則那樣只看字符層面的匹配。正則方案最大的問題是容易誤傷。比如注釋里寫了一行.old-style {}的示例代碼正則可能就把它當(dāng)成真實選擇器了又比如字符串里包含.btn-primary正則也會算作引用。但 AST 方案會明確區(qū)分注釋、字符串、真正的選擇器節(jié)點不會把這些干擾項算進(jìn)去。類似“媒體查詢里的嵌套選擇器”“帶偽元素的.btn:hover這種復(fù)合選擇器”在 AST 眼里都能準(zhǔn)確還原結(jié)構(gòu)這是正則想做到卻很難做好的?？梢赃@樣理解正則就像拿照妖鏡掃人看到長得像就喊“妖”AST 則像看身份證一條一條核對姓名、住址、關(guān)系。前者快但容易誤判后者多花了一點時間但結(jié)論可靠得多。2.2 三階段流水線scan → report → pruneponytail 的工作方式可以分成三個階段。第一個階段是scan掃描。它會讀取你指定的 CSS/SCSS 源文件同時掃描匹配的模板文件HTML、Vue、JSX、TSX 等都靠配置里的patterns字段來聲明。這一步輸出的是一份原始分析數(shù)據(jù)標(biāo)記出每個選擇器被引用的情況、每個聲明塊的重復(fù)情況。第二個階段是report生成報告。scan拿到數(shù)據(jù)后ponytail 會按規(guī)則整理成一份結(jié)構(gòu)化報告哪些選擇器從未被引用、哪些選擇器被多次重復(fù)定義、哪些聲明塊是冗余的、每個文件的冗余體積占比等等。報告是 JSON 格式的方便導(dǎo)入其他工具或讓 AI 讀取。第三個階段是prune修剪。報告確認(rèn)無誤后可以用prune指令執(zhí)行清理比如刪除未被引用的選擇器、合并重復(fù)聲明、簡化可縮短的選擇器寫法。這一步可以預(yù)演、可以備份、可以輸出 diff防止出現(xiàn)“清理一時爽上線火葬場”的情況。這個三階段設(shè)計最大的好處是“掃描和清理分離”。我可以在上午跑完scan中午把報告交給同事 review下午再執(zhí)行prune。誰也不想讓一個工具不經(jīng)確認(rèn)就直接刪代碼分離之后人工判斷的空間就出來了。2.3 配置文件的字段設(shè)計和安全機(jī)制ponytail 的配置文件默認(rèn)是ponytail.config.js用起來很像eslint.config.js或者prettier.config.js導(dǎo)出一個對象就行。我常用的配置項大概有這幾類source要分析樣式文件的位置。patterns要匹配的模板文件支持 glob 語法比如**/*.html、src/**/*.vue。ignore哪些樣式文件完全不參與分析比如第三方庫的覆蓋文件。whitelist白名單選擇器即使沒在模板中找到引用也強(qiáng)制保留通常用于動態(tài)拼接類名。dynamicPatterns動態(tài)類名模式比如/^is-|^has-|^js-/用來識別 JS 中拼接出來的類名。output報告輸出路徑。threshold冗余比例閾值超過該值則讓 CI 失敗。backup是否在修剪前自動備份原文件。安全機(jī)制主要靠“先預(yù)演再修改”的默認(rèn)行為。prune命令默認(rèn)不直接改文件必須顯式加上--apply才會寫入。沒有--apply時它只輸出一份類似git diff的內(nèi)容。這個設(shè)計讓我在團(tuán)隊里推行時底氣足了很多畢竟同事最擔(dān)心的就是“這工具會不會一跑就把我線上樣式全刪了”。3. 從零開始安裝、配置、跑通第一條掃描3.1 安裝的兩種方式CLI 直裝和 Skill 封裝如果你是第一次接觸我建議先通過 npm 以 CLI 方式安裝快速體驗一遍它的完整流程。npm install -D ponytail-cli也可以不裝到項目里直接用 npx 臨時執(zhí)行npx ponytail-cli --version等對命令和輸出都熟悉了再考慮把它以 “ponytail skill” 的形式接入 AI 工作流。接入 AI 時一般要先把 CLI 裝到當(dāng)前項目里然后創(chuàng)建一個skills/ponytail/SKILL.md文件內(nèi)容大致包括這個 skill 是做什么的負(fù)責(zé)掃描、分析、清理 CSS 樣式冗余。可執(zhí)行的命令清單比如npx ponytail-cli scan --config ponytail.config.js。輸出的位置和格式比如會生成ponytail-report.jsonAI 直接讀這個文件。安全規(guī)則AI 不能跳過 dry-run不能直接執(zhí)行帶--apply的修剪除非用戶明確確認(rèn)。這樣配置好以后當(dāng)你在 AI 對話框里說“幫我看一下目前樣式里有哪幾個未使用的類名”AI 會自動加載 skill然后執(zhí)行命令并閱讀報告。說白了就是你把 ponytail 的操作手冊塞給了 AIAI 變成會用工具的操作員而工具本身還是那個 CLI。3.2 最小配置一份能直接用的 ponytail.config.js我習(xí)慣先寫一份最簡配置跑通流程后再慢慢加規(guī)則。比如這樣一個項目結(jié)構(gòu)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它確實能看到j(luò)s-modal--open這個具體字符串但如果項目里有 JS 負(fù)責(zé)拼接類名比如el.className js-modal flag ? is-open : ;那is-open就不會出現(xiàn)在任何模板文件里這時候白名單whitelist或者dynamicPatterns就起到了保命作用。3.3 第一次實操掃描一個老項目并讀懂報告配置文件寫好后運行npx ponytail-cli scan命令執(zhí)行完控制臺會看到簡要統(tǒng)計同時生成ponytail-report.json。我拿一個模擬場景來演示假設(shè)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對應(yīng)的 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里出現(xiàn)但它們命中了我配置里的whitelist和dynamicPatterns所以被標(biāo)記為已使用。.unused-box則確認(rèn)是未使用狀態(tài)可以直接進(jìn)入清理流程。第一次看到報告時別急著執(zhí)行清理。先檢查幾個地方第一有沒有你以為在用、但實際上完全沒被引用的類名這類往往是活動頁遺留第二有沒有動態(tài)拼接類的模式?jīng)]配全這類需要加到whitelist第三有沒有第三方庫的樣式被錯誤地當(dāng)成了項目自己的樣式這類需要移入ignore。4. 核心實操如何安全地清理樣式4.1 用 dry-run 預(yù)演讓修改可見、可控清理是對代碼動手最忌諱的是悶頭直接改。ponytail 的prune命令默認(rèn)就是 dry-run意思是它會算出該怎么改但不動文件。npx ponytail-cli prune執(zhí)行后輸出會類似git diff清清楚楚地顯示哪些選擇器要被刪掉、哪些聲明塊會被合并。比如上面的.unused-box預(yù)期輸出是- .unused-box { - padding: 20px; - }確認(rèn)無誤后再真正應(yīng)用修改npx ponytail-cli prune --apply如果你開了backup: true運行前會生成一份帶時間戳的備份文件比如global.css.20240612-153000.bak。我強(qiáng)烈建議不要關(guān)掉這個備份尤其是首次在大項目上操作時。即使報告看起來再準(zhǔn)確也難免有業(yè)務(wù)邏輯里的黑魔法多個備份就是多一條后悔路。4.2 自動簡化選擇器與合并重復(fù)聲明清理不只是“刪未使用的樣式”它還包含兩個很實用的能力簡化選擇器和合并重復(fù)聲明。所謂簡化選擇器典型場景是這樣.header .header .header__logo { width: 120px; }如果項目里不存在嵌套層級這個第三層.header就是冗余的ponytail 可以把它簡化為.header__logo { width: 120px; }這個能力用 AST 算起來比較穩(wěn)因為它會就地分析層級是否真的重復(fù)不是無腦刪選擇器。還有一類是重復(fù)聲明合并.card { margin: 16px; } .card { padding: 8px; }這兩條規(guī)則完全可以合到一條里.card { margin: 16px; padding: 8px; }重復(fù)聲明合并能減少文件體積也能讓后續(xù)維護(hù)的人一眼看清某類名下到底掛了多少屬性。尤其在老項目里同一種類名在三個地方各寫一半屬性是常態(tài)合并以后簡直像打開了“亂發(fā)打結(jié)處”。清理結(jié)束后可以再跑一次scan看對比數(shù)據(jù)。上面的示例項目本來冗余比例是 18%清理后會變成 0%。實際項目可能不會一次清零但每輪迭代后那份報告會變成你和同事溝通的好依據(jù)。4.3 對接 AI 工作流ponytail skill 的提示詞設(shè)計如果你已經(jīng)安裝好 CLI也配置好了 skill 文件真正讓 AI 跑起來其實只需要一段很自然的對話。比如幫我看一下src/styles/global.css里有哪些未使用的樣式先掃描并輸出報告不要刪除任何東西。AI 在后臺會加載 ponytail skill執(zhí)行類似這樣的命令npx ponytail-cli scan --config ponytail.config.js然后讀取生成的 JSON用自然語言總結(jié)給你。等你確認(rèn)“可以清理”之后再說根據(jù)剛才的報告執(zhí)行清理但先不要應(yīng)用修改只給我看 diff。這就會調(diào)用npx ponytail-cli prune最后你看到 diff 沒問題再說“應(yīng)用修改”AI 再執(zhí)行npx ponytail-cli prune --apply這個“AI 只負(fù)責(zé)調(diào)用和總結(jié)、你負(fù)責(zé)最終確認(rèn)”的模式是我覺得最穩(wěn)妥的用法。因為 AI 的能力長處是理解上下文和生成操作但對每一個線上項目的業(yè)務(wù)邏輯并不真正了解。真正了解的是你所以最終確認(rèn)權(quán)必須留給自己。5. 常見問題與排查技巧實錄5.1 動態(tài)類名導(dǎo)致誤報最常見的誤報場景就是動態(tài)類名。很多現(xiàn)代前端項目不會把所有類名都寫死在模板里而是通過狀態(tài)控制拼接比如is-開頭的狀態(tài)類、has-開頭的存在類甚至還有col-${n}這種循環(huán)生成的柵格類。如果 ponytail 報告里出現(xiàn)了“誤報”先別急著把選擇器加入白名單。先檢查項目里有沒有下面的寫法className{btn ${isLoading ? is-loading : }}這種情況下is-loading在模板文件里確實沒有字符串出現(xiàn)但它是真實會生效的。解決辦法有兩個方向一是把這類模式補進(jìn)dynamicPatterns比如用正則/^is-/、/^has-/二是如果你知道所有可能的取值直接寫進(jìn)whitelist。我更推薦在項目初期就把動態(tài)類名的規(guī)則收集齊。因為一旦清理報告被誤報污染真正冗余的樣式會被埋沒在一堆假信號里工具的可信度就大打折扣。5.2 框架 scoped 樣式和 CSS Modules 的處理Vue 的 scoped 樣式、CSS Modules 這類技術(shù)會讓選擇器帶上特殊標(biāo)記比如.header[data-v-xxxx]、.footer_abc123__box。ponytail 默認(rèn)對標(biāo)準(zhǔn) CSS 的 AST 解析是沒問題的但你需要額外注意模板引用的匹配方式。以 Vue 為例要在patterns里加上.vue文件patterns: [src/**/*.vue],同時如果組件里寫了非 scoped 的:global()規(guī)則而這些規(guī)則可能被其他組件引用你需要把對應(yīng)類名納入白名單因為只掃描單個組件文件時ponytail 是看不到全局引用的。在處理 CSS Modules 時類名經(jīng)過編譯后會變成哈希值ponytail 掃描源碼是無法直接對應(yīng)上的。我的建議是讓掃描器匹配源碼里寫的最初類名比如.box而不是編譯后的.box_abc123所以你需要確認(rèn)項目里的模板文件使用的是源碼類名。如果項目里同時存在 scoped 和全局樣式文件建議把 scoped 文件單獨分組處理不要和全局樣式混在一次source配置里。否則全局掃描會把 scoped 樣式大量標(biāo)記為未使用造成誤報。5.3 命令行超時、內(nèi)存不足和提速技巧樣式文件一旦多起來比如幾千個 CSS 文件和上萬個模板文件掃描可能遇到兩個問題內(nèi)存占用高、執(zhí)行時間長。內(nèi)存問題通常和 glob patterns 太寬有關(guān)。比如你把node_modules也包含進(jìn)去了那掃描會卡到懷疑人生。務(wù)必在source和patterns中明確范圍或者用ignore排除ignore: [node_modules/**, dist/**, .next/**],如果項目實在太大還可以限制并發(fā)分析。ponytail 內(nèi)部是多線程并行解析文件有時并發(fā)過高反而會拖垮機(jī)器可以降低并發(fā)數(shù)比如npx ponytail-cli scan --concurrency 4執(zhí)行時間方面最省事的辦法是分模塊掃描。不要一次性掃描整個項目的所有 CSS而是按業(yè)務(wù)模塊拆分命令把報告輸出到不同文件。這樣不僅快而且更容易定位問題哪個模塊報告異常就直接看哪個模塊。我還習(xí)慣在 CI 里給掃描設(shè)置一個“寬限期”。第一次接入時先不設(shè)threshold跑一兩周建立基線然后再設(shè)置閾值比如“冗余比例不得超過 5%”。這樣不會因為歷史債務(wù)太厚導(dǎo)致 CI 直接掛掉而是給團(tuán)隊一個逐步清理的緩沖空間。5.4 常見的誤刪場景與如何恢復(fù)盡管工具設(shè)計得再安全執(zhí)行prune --apply后偶爾還是會出現(xiàn)樣式丟失的情況。比較典型的幾種場景類名和 ID 選擇器同時存在模板里只引用了 ID但 CSS 里還有基于類名的樣式且這個類名是其他腳本動態(tài)加上的。使用import引入了另一個文件被引入文件中的樣式在掃描主文件時沒有被標(biāo)記到。第三方插件在運行時往 DOM 上追加類名不在模板文件里也不在 JS 源碼里完全無法通過靜態(tài)分析發(fā)現(xiàn)。針對這三種情況我的實操建議是第一凡是在報告里標(biāo)記為“未使用”的類名先全局搜索一下源碼包括 JS 文件和 JSON 配置確認(rèn)真的沒有引用再刪第二把import的文件獨立加入source讓 ponytail 單獨分析第三給項目里所有第三方插件前綴的類名建一個固定的whitelist段比如slick-、tab-、swiper-這類直接聲明“凡是這種前綴都保留”。如果已經(jīng)誤刪并推送了代碼不要慌張只要開了backup: true就能從備份文件恢復(fù)。備份文件一般在項目根目錄或源文件同目錄下按時間戳命名。恢復(fù)以后記得把對應(yīng)的類名加進(jìn)whitelist避免下次再被誤刪。6. 我實際使用后的幾點體會工具再好最終還是看用的人怎么和它相處。我在把 ponytail 接入老項目以后最大的感受是樣式清理這件事終于不再靠“誰膽大誰刪”來推動了。以前每次做樣式重構(gòu)都得開一堆瀏覽器標(biāo)簽頁反復(fù)比對小心翼翼注釋掉一塊樣式再刷新看效果效率低不說還容易漏?，F(xiàn)在有了報告和數(shù)據(jù)團(tuán)隊里討論“這個類能不能刪”時可以直接把掃描記錄貼出來省掉很多無效爭論。同時我也想說不要把 ponytail 的報告當(dāng)成絕對真理。靜態(tài)分析能發(fā)現(xiàn)的是“在當(dāng)前代碼庫里存在或不存在引用”但業(yè)務(wù)系統(tǒng)里總有動態(tài)加載、第三方腳本、線上配置這些它看不見的部分。它的價值是幫你把 90% 的確定性冗余挑出來剩下 10% 的不確定項還是需要人來做最終判斷。我給自己定的規(guī)矩是凡是要刪的類名先看報告再全局搜一遍最后在測試環(huán)境過一遍相關(guān)頁面。這套流程下來我使用期間基本沒有出現(xiàn)過線上樣式事故。如果后續(xù)你還想繼續(xù)擴(kuò)展可以試試把 ponytail 和覆蓋率統(tǒng)計結(jié)合起來定期掃描報告里的冗余比例趨勢看看團(tuán)隊在樣式維護(hù)上是變好了還是變糟了。數(shù)據(jù)不會說謊樣式文件從 200KB 瘦到 80KB 以后同事再也不敢隨手往全局樣式里塞一個只服務(wù)于單個頁面的類名了。這也是我越來越愿意把這套工具分享出去的原因。 ponytail插件：用AST給CSS樣式“扎辮子”，安全清理冗余樣式
最近前端群里好幾個人都在問 ponytail 插件到底怎么用尤其是“ponytail skill”這個叫法聽起來像是個新出的玩具。其實它是一套專門用來給 CSS 樣式文件“收辮子”的工具——掃描、標(biāo)記、清理、重構(gòu)把散落各處的冗余樣式統(tǒng)一歸攏所以叫 ponytail馬尾辮。如果你經(jīng)常被幾百行沒人敢動的global.css勸退或者每次改完 HTML 都要提心吊膽地查樣式有沒有掛掉這篇就是給你寫的。ponytail 不是一個花哨的 UI 組件庫也不是動畫庫它更像是前端工程化里的“樣式整理師”。我會從設(shè)計思路講起再給出一套可以直接照抄的安裝、配置、實操流程最后把我踩過的坑和排查邏輯一并整理出來。不管你是剛接觸前端工程化的新人還是維護(hù)老項目到頭疼的資深開發(fā)應(yīng)該都能從中拿到點能立刻用得上的東西。1. 先搞清楚 ponytail 是什么以及它想解決什么問題1.1 一個很形象的命名馬尾辮“ponytail”直譯過來是馬尾辮這個命名其實特別直白。一個項目跑久了幾乎不可避免地會出現(xiàn)這類狀況.btn定義了好幾次有的在基礎(chǔ)樣式里有的在頁面級樣式里當(dāng)年做活動頁留下的.active-banner-2023早就沒人用了但文件里還堂而皇之地躺著還有一些選擇器嵌套五六層拆開來看全是重復(fù)聲明。這時候整個樣式文件就像一頭沒梳理的亂發(fā)看著厚重實際上有用的大概只有一半。ponytail 想做的就是拿一根皮筋把這些頭發(fā)扎起來——先梳順再扎緊最后讓那些飄在外面、已經(jīng)失去作用的碎發(fā)直接剪掉。這根“皮筋”就是它的核心流程通過靜態(tài)分析掃描項目里所有 CSS/SCSS 文件和匹配的模板文件找出真正被引用的選擇器、真正生效的聲明塊然后把冗余部分標(biāo)記出來給你一份可執(zhí)行的清理報告。所以 ponytail 不適合用“樣式檢查工具”來簡單定義。它更像一個帶有重構(gòu)建議的“樣式瘦身器”重點不在挑錯而在幫你安全地做減法。尤其當(dāng)你面對一個沒有測試覆蓋、樣式文件歷史包袱很重的老項目時這種“先分析、再報告、最后動手”的方式會比人工眼睛排查可靠得多。1.2 ponytail skill 和 ponytail 插件之間的關(guān)系很多人在搜索“ponytail skill”和“ponytail 插件”時容易把它們當(dāng)成兩個東西。實際上它們指的是同一個工具在不同形態(tài)下的兩種使用方式。“插件”形態(tài)通常是可以直接安裝的 CLI 工具通過npx ponytail或全局命令執(zhí)行掃描、輸出報告、自動修剪。這種形態(tài)適合本地開發(fā)、CI 流水線一切都在命令行里完成輸出是 JSON 格式的報告方便后續(xù)處理?！皊kill”形態(tài)則是給 AI 編程助手用的封裝。現(xiàn)在很多 AI 編程環(huán)境支持“自定義技能”本質(zhì)上是把一個結(jié)構(gòu)化的操作手冊Markdown和配套腳本放進(jìn)指定的skills目錄AI 在回答相關(guān)問題時會自動加載這個技能知道應(yīng)該調(diào)用哪些命令、怎么解析報告、怎么安全地修改樣式文件。你可以把 skill 理解成“教 AI 使用 ponytail 的說明書”而說明書背后仍然是那套 CLI 在干活。這兩種形態(tài)并不互斥。我實際使用時的做法是本地先裝好 CLI把配置寫好、規(guī)則調(diào)好然后在 AI 助手的工作區(qū)里放一份對應(yīng)版本的 skill 文件。這樣如果需要 AI 幫忙批量處理樣式它就能按照我給它的操作流程去調(diào)用 CLI、讀懂結(jié)果而不是憑空猜測該怎么清理。1.3 適用場景與不適合的場景先說它擅長的場景。第一類是多年沒敢大動的業(yè)務(wù)項目樣式文件成百上千行注釋里寫著“此處不要刪線上正在用”但沒人知道到底哪部分在用這時候 ponytail 能給出基于代碼引用關(guān)系的客觀判斷。第二類是重構(gòu)前的摸底比如準(zhǔn)備把老項目從 jQuery 遷移到 Vue或者準(zhǔn)備引入 Tailwind你需要在動手前知道現(xiàn)有樣式體系里哪些是可以放棄的哪些是必須保留的。第三類是 CI 卡點要求在合并請求前把冗余樣式比例控制在一定閾值以內(nèi)ponytail 可以無縫接進(jìn)流水線。但它也有明顯不適合的場景。如果你的項目是純組件庫每一個樣式類都直接對應(yīng)組件 API而且已經(jīng)有完善的單元測試那么用 stylelint 或者 TypeScript 類型檢查可能更直接ponytail 的“掃描引用”反而會因組件動態(tài)用法太多而誤報。如果你用了 CSS-in-JS比如 styled-components樣式不是以獨立文件存在的ponytail 也基本派不上用場因為它擅長的是靜態(tài)文件層面的分析。所以選擇工具之前先對號入座有歷史包袱、有靜態(tài)樣式文件、有模板可查這三條都滿足的時候ponytail 就是那個能把頭發(fā)扎起來的皮筋。2. 上手前需要理解的核心設(shè)計2.1 為什么 AST 比正則靠譜我見過不少人第一次拿到 ponytail 的掃描結(jié)果第一反應(yīng)是“這不就是正則匹配嗎”實際上它底層用的是樣式解析器先把 CSS 轉(zhuǎn)成 AST抽象語法樹再對模板里的 class 引用做標(biāo)記最后把兩者比對。簡單來說AST 是把樣式文件的結(jié)構(gòu)拆成可編程操作的樹形數(shù)據(jù)而不是像正則那樣只看字符層面的匹配。正則方案最大的問題是容易誤傷。比如注釋里寫了一行.old-style {}的示例代碼正則可能就把它當(dāng)成真實選擇器了又比如字符串里包含.btn-primary正則也會算作引用。但 AST 方案會明確區(qū)分注釋、字符串、真正的選擇器節(jié)點不會把這些干擾項算進(jìn)去。類似“媒體查詢里的嵌套選擇器”“帶偽元素的.btn:hover這種復(fù)合選擇器”在 AST 眼里都能準(zhǔn)確還原結(jié)構(gòu)這是正則想做到卻很難做好的?？梢赃@樣理解正則就像拿照妖鏡掃人看到長得像就喊“妖”AST 則像看身份證一條一條核對姓名、住址、關(guān)系。前者快但容易誤判后者多花了一點時間但結(jié)論可靠得多。2.2 三階段流水線scan → report → pruneponytail 的工作方式可以分成三個階段。第一個階段是scan掃描。它會讀取你指定的 CSS/SCSS 源文件同時掃描匹配的模板文件HTML、Vue、JSX、TSX 等都靠配置里的patterns字段來聲明。這一步輸出的是一份原始分析數(shù)據(jù)標(biāo)記出每個選擇器被引用的情況、每個聲明塊的重復(fù)情況。第二個階段是report生成報告。scan拿到數(shù)據(jù)后ponytail 會按規(guī)則整理成一份結(jié)構(gòu)化報告哪些選擇器從未被引用、哪些選擇器被多次重復(fù)定義、哪些聲明塊是冗余的、每個文件的冗余體積占比等等。報告是 JSON 格式的方便導(dǎo)入其他工具或讓 AI 讀取。第三個階段是prune修剪。報告確認(rèn)無誤后可以用prune指令執(zhí)行清理比如刪除未被引用的選擇器、合并重復(fù)聲明、簡化可縮短的選擇器寫法。這一步可以預(yù)演、可以備份、可以輸出 diff防止出現(xiàn)“清理一時爽上線火葬場”的情況。這個三階段設(shè)計最大的好處是“掃描和清理分離”。我可以在上午跑完scan中午把報告交給同事 review下午再執(zhí)行prune。誰也不想讓一個工具不經(jīng)確認(rèn)就直接刪代碼分離之后人工判斷的空間就出來了。2.3 配置文件的字段設(shè)計和安全機(jī)制ponytail 的配置文件默認(rèn)是ponytail.config.js用起來很像eslint.config.js或者prettier.config.js導(dǎo)出一個對象就行。我常用的配置項大概有這幾類source要分析樣式文件的位置。patterns要匹配的模板文件支持 glob 語法比如**/*.html、src/**/*.vue。ignore哪些樣式文件完全不參與分析比如第三方庫的覆蓋文件。whitelist白名單選擇器即使沒在模板中找到引用也強(qiáng)制保留通常用于動態(tài)拼接類名。dynamicPatterns動態(tài)類名模式比如/^is-|^has-|^js-/用來識別 JS 中拼接出來的類名。output報告輸出路徑。threshold冗余比例閾值超過該值則讓 CI 失敗。backup是否在修剪前自動備份原文件。安全機(jī)制主要靠“先預(yù)演再修改”的默認(rèn)行為。prune命令默認(rèn)不直接改文件必須顯式加上--apply才會寫入。沒有--apply時它只輸出一份類似git diff的內(nèi)容。這個設(shè)計讓我在團(tuán)隊里推行時底氣足了很多畢竟同事最擔(dān)心的就是“這工具會不會一跑就把我線上樣式全刪了”。3. 從零開始安裝、配置、跑通第一條掃描3.1 安裝的兩種方式CLI 直裝和 Skill 封裝如果你是第一次接觸我建議先通過 npm 以 CLI 方式安裝快速體驗一遍它的完整流程。npm install -D ponytail-cli也可以不裝到項目里直接用 npx 臨時執(zhí)行npx ponytail-cli --version等對命令和輸出都熟悉了再考慮把它以 “ponytail skill” 的形式接入 AI 工作流。接入 AI 時一般要先把 CLI 裝到當(dāng)前項目里然后創(chuàng)建一個skills/ponytail/SKILL.md文件內(nèi)容大致包括這個 skill 是做什么的負(fù)責(zé)掃描、分析、清理 CSS 樣式冗余。可執(zhí)行的命令清單比如npx ponytail-cli scan --config ponytail.config.js。輸出的位置和格式比如會生成ponytail-report.jsonAI 直接讀這個文件。安全規(guī)則AI 不能跳過 dry-run不能直接執(zhí)行帶--apply的修剪除非用戶明確確認(rèn)。這樣配置好以后當(dāng)你在 AI 對話框里說“幫我看一下目前樣式里有哪幾個未使用的類名”AI 會自動加載 skill然后執(zhí)行命令并閱讀報告。說白了就是你把 ponytail 的操作手冊塞給了 AIAI 變成會用工具的操作員而工具本身還是那個 CLI。3.2 最小配置一份能直接用的 ponytail.config.js我習(xí)慣先寫一份最簡配置跑通流程后再慢慢加規(guī)則。比如這樣一個項目結(jié)構(gòu)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它確實能看到j(luò)s-modal--open這個具體字符串但如果項目里有 JS 負(fù)責(zé)拼接類名比如el.className js-modal flag ? is-open : ;那is-open就不會出現(xiàn)在任何模板文件里這時候白名單whitelist或者dynamicPatterns就起到了保命作用。3.3 第一次實操掃描一個老項目并讀懂報告配置文件寫好后運行npx ponytail-cli scan命令執(zhí)行完控制臺會看到簡要統(tǒng)計同時生成ponytail-report.json。我拿一個模擬場景來演示假設(shè)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對應(yīng)的 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里出現(xiàn)但它們命中了我配置里的whitelist和dynamicPatterns所以被標(biāo)記為已使用。.unused-box則確認(rèn)是未使用狀態(tài)可以直接進(jìn)入清理流程。第一次看到報告時別急著執(zhí)行清理。先檢查幾個地方第一有沒有你以為在用、但實際上完全沒被引用的類名這類往往是活動頁遺留第二有沒有動態(tài)拼接類的模式?jīng)]配全這類需要加到whitelist第三有沒有第三方庫的樣式被錯誤地當(dāng)成了項目自己的樣式這類需要移入ignore。4. 核心實操如何安全地清理樣式4.1 用 dry-run 預(yù)演讓修改可見、可控清理是對代碼動手最忌諱的是悶頭直接改。ponytail 的prune命令默認(rèn)就是 dry-run意思是它會算出該怎么改但不動文件。npx ponytail-cli prune執(zhí)行后輸出會類似git diff清清楚楚地顯示哪些選擇器要被刪掉、哪些聲明塊會被合并。比如上面的.unused-box預(yù)期輸出是- .unused-box { - padding: 20px; - }確認(rèn)無誤后再真正應(yīng)用修改npx ponytail-cli prune --apply如果你開了backup: true運行前會生成一份帶時間戳的備份文件比如global.css.20240612-153000.bak。我強(qiáng)烈建議不要關(guān)掉這個備份尤其是首次在大項目上操作時。即使報告看起來再準(zhǔn)確也難免有業(yè)務(wù)邏輯里的黑魔法多個備份就是多一條后悔路。4.2 自動簡化選擇器與合并重復(fù)聲明清理不只是“刪未使用的樣式”它還包含兩個很實用的能力簡化選擇器和合并重復(fù)聲明。所謂簡化選擇器典型場景是這樣.header .header .header__logo { width: 120px; }如果項目里不存在嵌套層級這個第三層.header就是冗余的ponytail 可以把它簡化為.header__logo { width: 120px; }這個能力用 AST 算起來比較穩(wěn)因為它會就地分析層級是否真的重復(fù)不是無腦刪選擇器。還有一類是重復(fù)聲明合并.card { margin: 16px; } .card { padding: 8px; }這兩條規(guī)則完全可以合到一條里.card { margin: 16px; padding: 8px; }重復(fù)聲明合并能減少文件體積也能讓后續(xù)維護(hù)的人一眼看清某類名下到底掛了多少屬性。尤其在老項目里同一種類名在三個地方各寫一半屬性是常態(tài)合并以后簡直像打開了“亂發(fā)打結(jié)處”。清理結(jié)束后可以再跑一次scan看對比數(shù)據(jù)。上面的示例項目本來冗余比例是 18%清理后會變成 0%。實際項目可能不會一次清零但每輪迭代后那份報告會變成你和同事溝通的好依據(jù)。4.3 對接 AI 工作流ponytail skill 的提示詞設(shè)計如果你已經(jīng)安裝好 CLI也配置好了 skill 文件真正讓 AI 跑起來其實只需要一段很自然的對話。比如幫我看一下src/styles/global.css里有哪些未使用的樣式先掃描并輸出報告不要刪除任何東西。AI 在后臺會加載 ponytail skill執(zhí)行類似這樣的命令npx ponytail-cli scan --config ponytail.config.js然后讀取生成的 JSON用自然語言總結(jié)給你。等你確認(rèn)“可以清理”之后再說根據(jù)剛才的報告執(zhí)行清理但先不要應(yīng)用修改只給我看 diff。這就會調(diào)用npx ponytail-cli prune最后你看到 diff 沒問題再說“應(yīng)用修改”AI 再執(zhí)行npx ponytail-cli prune --apply這個“AI 只負(fù)責(zé)調(diào)用和總結(jié)、你負(fù)責(zé)最終確認(rèn)”的模式是我覺得最穩(wěn)妥的用法。因為 AI 的能力長處是理解上下文和生成操作但對每一個線上項目的業(yè)務(wù)邏輯并不真正了解。真正了解的是你所以最終確認(rèn)權(quán)必須留給自己。5. 常見問題與排查技巧實錄5.1 動態(tài)類名導(dǎo)致誤報最常見的誤報場景就是動態(tài)類名。很多現(xiàn)代前端項目不會把所有類名都寫死在模板里而是通過狀態(tài)控制拼接比如is-開頭的狀態(tài)類、has-開頭的存在類甚至還有col-${n}這種循環(huán)生成的柵格類。如果 ponytail 報告里出現(xiàn)了“誤報”先別急著把選擇器加入白名單。先檢查項目里有沒有下面的寫法className{btn ${isLoading ? is-loading : }}這種情況下is-loading在模板文件里確實沒有字符串出現(xiàn)但它是真實會生效的。解決辦法有兩個方向一是把這類模式補進(jìn)dynamicPatterns比如用正則/^is-/、/^has-/二是如果你知道所有可能的取值直接寫進(jìn)whitelist。我更推薦在項目初期就把動態(tài)類名的規(guī)則收集齊。因為一旦清理報告被誤報污染真正冗余的樣式會被埋沒在一堆假信號里工具的可信度就大打折扣。5.2 框架 scoped 樣式和 CSS Modules 的處理Vue 的 scoped 樣式、CSS Modules 這類技術(shù)會讓選擇器帶上特殊標(biāo)記比如.header[data-v-xxxx]、.footer_abc123__box。ponytail 默認(rèn)對標(biāo)準(zhǔn) CSS 的 AST 解析是沒問題的但你需要額外注意模板引用的匹配方式。以 Vue 為例要在patterns里加上.vue文件patterns: [src/**/*.vue],同時如果組件里寫了非 scoped 的:global()規(guī)則而這些規(guī)則可能被其他組件引用你需要把對應(yīng)類名納入白名單因為只掃描單個組件文件時ponytail 是看不到全局引用的。在處理 CSS Modules 時類名經(jīng)過編譯后會變成哈希值ponytail 掃描源碼是無法直接對應(yīng)上的。我的建議是讓掃描器匹配源碼里寫的最初類名比如.box而不是編譯后的.box_abc123所以你需要確認(rèn)項目里的模板文件使用的是源碼類名。如果項目里同時存在 scoped 和全局樣式文件建議把 scoped 文件單獨分組處理不要和全局樣式混在一次source配置里。否則全局掃描會把 scoped 樣式大量標(biāo)記為未使用造成誤報。5.3 命令行超時、內(nèi)存不足和提速技巧樣式文件一旦多起來比如幾千個 CSS 文件和上萬個模板文件掃描可能遇到兩個問題內(nèi)存占用高、執(zhí)行時間長。內(nèi)存問題通常和 glob patterns 太寬有關(guān)。比如你把node_modules也包含進(jìn)去了那掃描會卡到懷疑人生。務(wù)必在source和patterns中明確范圍或者用ignore排除ignore: [node_modules/**, dist/**, .next/**],如果項目實在太大還可以限制并發(fā)分析。ponytail 內(nèi)部是多線程并行解析文件有時并發(fā)過高反而會拖垮機(jī)器可以降低并發(fā)數(shù)比如npx ponytail-cli scan --concurrency 4執(zhí)行時間方面最省事的辦法是分模塊掃描。不要一次性掃描整個項目的所有 CSS而是按業(yè)務(wù)模塊拆分命令把報告輸出到不同文件。這樣不僅快而且更容易定位問題哪個模塊報告異常就直接看哪個模塊。我還習(xí)慣在 CI 里給掃描設(shè)置一個“寬限期”。第一次接入時先不設(shè)threshold跑一兩周建立基線然后再設(shè)置閾值比如“冗余比例不得超過 5%”。這樣不會因為歷史債務(wù)太厚導(dǎo)致 CI 直接掛掉而是給團(tuán)隊一個逐步清理的緩沖空間。5.4 常見的誤刪場景與如何恢復(fù)盡管工具設(shè)計得再安全執(zhí)行prune --apply后偶爾還是會出現(xiàn)樣式丟失的情況。比較典型的幾種場景類名和 ID 選擇器同時存在模板里只引用了 ID但 CSS 里還有基于類名的樣式且這個類名是其他腳本動態(tài)加上的。使用import引入了另一個文件被引入文件中的樣式在掃描主文件時沒有被標(biāo)記到。第三方插件在運行時往 DOM 上追加類名不在模板文件里也不在 JS 源碼里完全無法通過靜態(tài)分析發(fā)現(xiàn)。針對這三種情況我的實操建議是第一凡是在報告里標(biāo)記為“未使用”的類名先全局搜索一下源碼包括 JS 文件和 JSON 配置確認(rèn)真的沒有引用再刪第二把import的文件獨立加入source讓 ponytail 單獨分析第三給項目里所有第三方插件前綴的類名建一個固定的whitelist段比如slick-、tab-、swiper-這類直接聲明“凡是這種前綴都保留”。如果已經(jīng)誤刪并推送了代碼不要慌張只要開了backup: true就能從備份文件恢復(fù)。備份文件一般在項目根目錄或源文件同目錄下按時間戳命名。恢復(fù)以后記得把對應(yīng)的類名加進(jìn)whitelist避免下次再被誤刪。6. 我實際使用后的幾點體會工具再好最終還是看用的人怎么和它相處。我在把 ponytail 接入老項目以后最大的感受是樣式清理這件事終于不再靠“誰膽大誰刪”來推動了。以前每次做樣式重構(gòu)都得開一堆瀏覽器標(biāo)簽頁反復(fù)比對小心翼翼注釋掉一塊樣式再刷新看效果效率低不說還容易漏?，F(xiàn)在有了報告和數(shù)據(jù)團(tuán)隊里討論“這個類能不能刪”時可以直接把掃描記錄貼出來省掉很多無效爭論。同時我也想說不要把 ponytail 的報告當(dāng)成絕對真理。靜態(tài)分析能發(fā)現(xiàn)的是“在當(dāng)前代碼庫里存在或不存在引用”但業(yè)務(wù)系統(tǒng)里總有動態(tài)加載、第三方腳本、線上配置這些它看不見的部分。它的價值是幫你把 90% 的確定性冗余挑出來剩下 10% 的不確定項還是需要人來做最終判斷。我給自己定的規(guī)矩是凡是要刪的類名先看報告再全局搜一遍最后在測試環(huán)境過一遍相關(guān)頁面。這套流程下來我使用期間基本沒有出現(xiàn)過線上樣式事故。如果后續(xù)你還想繼續(xù)擴(kuò)展可以試試把 ponytail 和覆蓋率統(tǒng)計結(jié)合起來定期掃描報告里的冗余比例趨勢看看團(tuán)隊在樣式維護(hù)上是變好了還是變糟了。數(shù)據(jù)不會說謊樣式文件從 200KB 瘦到 80KB 以后同事再也不敢隨手往全局樣式里塞一個只服務(wù)于單個頁面的類名了。這也是我越來越愿意把這套工具分享出去的原因。