接手这个后台项目的第一周，我差点想直接把 F12 Network 面板截图发到群里当段子。整页加载下来 40 多个 CSS 和 JS 请求，有些文件早就在页面里找不到对应功能了，但没人敢删。项目从最初的 11 个文件长到了 200 多个，每个需求进来都往入口 HTML 里加一行 link 或 script，像不停往马尾辫里夹发卡，最后乱成一团。后来我在 release 前接了一个叫 ponytail 的小插件，它的作用简单说就是：把散落在各个目录里的 CSS/JS 引用关系扫描出来，按页面和公共依赖重新分组，再合并成少数几个产物，顺便告诉你哪些文件其实没人用。如果你也在维护一个历史包袱很重的老项目，ponytail 可能就是你需要的那根橡皮筋。
1. 项目为什么会烂到需要 ponytail：一个后台系统的失控过程
1.1 症状：不是代码能力问题，是管理问题
那个项目的失控轨迹其实很典型。最开始只有一个reset.css、一个app.js，后来 UI 组件库升级，加了components.css；然后项目经理说首页要在导航栏上加个动态提示，前端同事不想动老代码，直接新写了notice.js，在页面里<script>引用了事。再后来换了一批前端，每个人习惯不同，有人爱写style.css，有人非要建一个0908_fix.css。到我去接手的时候，页面里光<link>就有 23 个，<script>有 17 个。
真正叫人头疼的不是请求多，而是文件之间的依赖关系没人讲得清。common.js依赖jquery.js，list.js又依赖common.js里某个全局函数，但 HTML 里的引用顺序还是老的，某次升级后功能莫名其妙就没了。我想清理，但是打开每个文件看一遍作用范围，工作量比改需求还大。
这种问题的本质不是代码水平，而是缺少一个"资源状态可视化"的手段。每个文件都像一根头发，平时看着都长在头上，但哪一根是从哪一根分出去的，没人知道。如果用手一个个去理，得耗几天；如果直接上构建工具，改动范围又太大。
1.2 为什么不直接上 Webpack 或 Vite
很多人第一反应是：这种乱象，直接换成 Webpack/Vite 不就重启了吗？我以前也这么想，后来发现老项目上构建工具的隐性成本远高于想象。
第一，老项目的 JS 大量使用全局函数和window.xxx互相调用，没有模块化。用 Webpack 打包，必须手动把所有跨文件依赖改成import/export，或者用expose-loader这种奇怪姿势。一个 200 个文件的项目，要保证每个全局变量不冲突，哪怕自动化迁移，验证回归也要一两周。
第二，CSS 里的选择器全是全局的，没有 BEM 约束，合并到构建链后 PurgeCSS 根本不敢开——因为很多样式是通过 JS 动态拼 class 名加上去的，PurgeCSS 扫不到就给你删了，页面瞬间崩。
第三，老项目还在用相对路径引图片和字体，url(../images/xxx.png)在原有目录结构下能跑，一旦上构建工具，路径问题会从 CSS 里的 @import 一直蔓延到 JS 里的字符串拼接。
所以当时我对团队的态度很明确：不要动源头，先治产物。把散乱的资源在发布前合并、去重、给出冲突报告，如果能做到，就不需要花三周重构。ponytail 的切入点就在这：它不改变你项目原本的目录结构和开发方式，HTML 里该写多少个引用还写多少个，只是在 build 的时候帮你扎一遍。
2. 接入 ponytail 的正确姿势：从 npm 安装到第一次出包
2.1 安装和初始化
ponytail 是一个 npm 包，提供ponytail命令行工具。安装到项目里作为 devDependency：
npm install -D ponytail装完之后先跑一行初始化命令：
npx ponytail init它会在项目根目录生成一个ponytail.config.js，同时自动探测你的页面入口目录。这一步我建议不用默认参数，因为默认的入口扫描可能会把node_modules里的 HTML 也扫进去。最好先打开生成的配置文件，把input改成你真实的入口目录。
我在这类项目里的习惯是：
npx ponytail init --input ./src/pages --output ./dist/static这个工具的设计逻辑是：以 HTML 为起点，而不是以整个目录为起点。所以input指向的是所有需要处理的 HTML 页面，工具会顺着每个 HTML 里的link和script去找资源，不存在的文件会直接报错，而不是默默跳过。
2.2 最小配置样例与第一次 scan
初始化完成后的配置文件大致长这样：
module.exports = { // 页面入口，支持 glob 表达式 input: './src/pages/**/*.html', // 合并后的产物输出目录 output: './dist/static', // 浏览器访问资源时的公共路径前缀 publicPath: '/static/', // 只处理这些类型文件 include: [/\.css$/, /\.js$/], // 自定义分组规则，优先级从上到下 groupRules: [ { test: /common|vendor|lib|jquery/, group: 'vendor' }, { test: /pages\/order/, group: 'order-page' }, ], };配置好之后跑扫描命令：
npx ponytail scan它不会马上改任何文件，只会输出一份依赖报告。我这边第一次跑出来的结果直接让人脸绿：order.html引用了 29 个外部资源，其中jquery.min.js被引用了 7 次，common.css被 11 个页面重复引用但内容有 3 个版本。这就是老项目最典型的"看起来都有用得上的，其实已经在互相覆盖"。
scan这个命令是整个工具里最重要的，因为它把所有不可见的问题变成了白纸黑字的清单。我建议不管最后要不要用 ponytail 执行合并，都先跑一遍 scan 看看报告，就当给项目做一次资源体检。
3. ponytail 的资源扫描与"扎马尾"算法：分组策略剖析
3.1 扫描索引：让 HTML 当入口，而不是让文件系统当入口
我最初使用 ponytail 时有个疑惑：它为什么不直接在目录里跑到所有 CSS/JS 然后合并？后来看了它的扫描逻辑才明白，以 HTML 为入口是刻意的。
如果直接扫目录，会遇到两个问题：一是目录里有历史遗留的死文件，扫进来只会增加合并体积；二是 HTML 里引用顺序本身包含业务逻辑——比如某个 jQuery 插件必须在jquery.js之后加载，这个顺序关系一旦被打散，页面功能就完蛋了。
ponytail 的扫描路径就清晰很多：
- 读取 HTML，用解析器提取所有
<link rel="stylesheet">和<script src>。 - 解析这些外部资源的相对路径，去本地磁盘找文件。
- 如果资源是 CSS，再递归解析 CSS 内部的
@import语句。 - 如果资源是 JS，做一层轻量的依赖解析，识别同步
import/require（传统项目里不常用，但遇到会处理）。 - 生成依赖图，节点是文件，边是引用关系。
扫描结果会保存到.ponytail-cache目录，下次 scan 如果文件没变，会直接读缓存，速度非常快。
3.2 分组策略：橡皮筋扎在哪，谁说了算
"扎马尾"这个词用到分组策略上特别贴切。把所有头发拢成一根是马尾，先扎上半截再扎下半截也是马尾，关键看你想露出什么样的形态。ponytail 的分组规则也是同样道理，默认按页面分：
- 每个 HTML 页面默认生成一个
page-{页面名}分组； groupRules里命中的文件会从默认分组里抽出来，放进指定分组；- 最后所有分组合并输出，页面 HTML 里的引用会被重写成合并后的产物路径。
groupRules 的执行有优先级，从上到下第一条命中的规则生效。所以你应该把最通用的依赖放最前面，比如 jQuery、公司内部的 common.js、UI 组件库，它们会被归到vendor分组；再把当前页面独有的业务样式放后面，归到page-xxx。
除了规则匹配，也支持在 HTML 标签上手动指定，这个我觉得是救命功能：
<link rel="stylesheet" href="js/a.css">npx ponytail build产物会输出到配置的output目录，结构大致是：
dist/static/ common/ vendor.css vendor.js pages/ order-page.css order-page.js同时 HTML 文件会被复制到 dist 目录下，原本 20 多行<link>和<script>会被重写成：
<link rel="stylesheet" href="/static/common/vendor.css" /> <link rel="stylesheet" href="/static/pages/order-page.css" /> <script src="/static/common/vendor.js"></script> <script src="/static/pages/order-page.js"></script>这一步是 ponytail 真正值钱的地方：开发期不需要改任何代码，发布前却能得到一套干净利落的资源引用。我第一次跑完看到重写后的 HTML，几乎是扶着额头说了一句：这才像个发布产物该有的样子。
4. 真实案例：订单管理页从 40 个请求降到 4 个请求
4.1 这个页面的资源引用到底有多乱
拿一个订单管理页面举例。这个页面在项目里属于最核心的业务页，但它的 HTML 头部是这样的节奏：一个公共 reset，一个老版 UI 组件样式，一个新版 UI 组件样式，一个列表页样式，一个当天修复的补丁样式，两个第三方日期插件样式……<script>更是从 jQuery 1.x 到 jQuery 插件、公共工具方法、订单列表逻辑、导出组件一路排下来。
我没有夸张，这个页面总共引用了 23 个 CSS 和 17 个 JS。网络面板打开都能看到瀑布图里一堆请求在排队，用户每次打开页面都要等将近 3 秒才可交互，还经常因为某个插件加载顺序不对而报$ is not defined。
4.2 优化配置和结果
我在这个页面上没有做特别复杂的规则，只抓两条主线：
module.exports = { input: './src/pages/order.html', output: './dist/static', publicPath: '/static/', groupRules: [ { test: /jquery|ui|plugin|common|utils/, group: 'vendor' }, { test: /order/, group: 'order-page' }, ], };因为order.html是单页入口，默认分组和规则叠加后，最终只产生了 4 个文件：vendor.css、order-page.css、vendor.js、order-page.js。构建命令跑完以后，页面里的引用从 40 个 JS/CSS 资源变成了 4 个。
优化前后的数据是这样的：
| 指标 | 优化前 | 优化后 | 变化 |
|---|---|---|---|
| 页面发起的静态资源请求数 | 40 | 4 | 减少 90% |
| CSS 总体积（不含图片字体） | 486 KB | 312 KB | 减少 35.8% |
| JS 总体积（不含第三方文件） | 1.1 MB | 782 KB | 减少 28.9% |
| 首屏可交互时间（本地模拟） | 2.8 s | 1.5 s | 提升 46% |
这里要特别说明，体积减少不是只靠文件合并。合并本身只会减少请求数，不会减少体积；真正让体积降下来的是 ponytail 的重复资源识别——我在 scan 报告里发现jquery.min.js被引用了 7 次，其中 5 次是不同版本。合并时它默认保留版本号最高的那个，并把其它引用重写到新产物上，这省下的就是白花花的流量。
4.3 为什么首屏变快的不只是请求数
请求数从 40 降到 4，对 HTTP/1.1 的项目来说提升是立竿见影的。就算用的是 HTTP/2，浏览器要建立和处理的关键请求链路也短了很多。但真正影响首屏的是阻塞资源的数量。原来 17 个 JS 里有 10 个是渲染阻塞的，浏览器必须按顺序下载完才能继续渲染；合并成 2 个 JS 后，阻塞次数从 17 次降到 2 次，即使体积没有减少太多，等待瀑布图也会变得短得多。
如果你要说服团队用类似工具，不要只说"合并了文件"，把请求数变化和可交互时间变化摆出来，才是最直观的论据。
5. 我最想提醒的三个坑：作用域冲突、动态插标签和 @import 嵌套
5.1 作用域冲突：合并之后 .btn 到底听谁的
这是所有静态资源合并工具都会踩的雷，ponytail 也没法完全避免。一个老项目里几乎不可能只有一个.btn样式定义。A 组件文件的btn是蓝色按钮，B 文件里定义了一个同名覆盖类想让它变成红色。分开加载时，后加载的那个生效；合并之后，ponytail 会把两个文件按扫描时的引用顺序拼接，结果可能是 B 的定义被放到了 A 前面，页面上一排按钮全变蓝了。
ponytail 的应对方式是"冲突检测 + 报告"，而不是自作主张去重命名同名选择器。它在 build 阶段会解析每个 CSS 文件的选择器，生成一张哈希表，发现有同名的规则就记录进 conflict report：
[conflict] .btn - src/components/btn-a.css: line 12 - src/pages/order/order-fix.css: line 203 处理结果：保留 order-fix.css 的定义（后加载优先级）这么设计是合理的。老项目里的同名选择器到底谁生效，业务逻辑心里有数，真让工具自动改 class 名反而容易崩。我建议的做法是：每次 build 后都把 conflict report 存在 CI 的 artifact 里，让前端同事自己 review，发现有问题的再手动调整引用顺序，而不是直接信任工具。
5.2 动态插入的 script 标签和 link 标签
老项目里有一种很常见的操作：点某个按钮时才通过 JS 动态创建<script>标签加载一个图表插件。这种动态加载的资源，ponytail 在扫描 HTML 的时候根本看不到，所以也不会把它合并进产物。结果就是，你跑完 build 一看页面功能全好，等测试去点某个弹窗，图表加载不出来了。
解决方案有两个。一个是在配置里显式声明动态模块：
module.exports = { dynamicModules: [ './src/vendor/charts.js', './src/vendor/export-excel.js', ], };另一个是在 HTML 里给初始标签加标记，让 ponytail 修改扫描逻辑，在页面加载时预留一个异步加载的位置。我个人更推荐第一个，因为它更显式，以后别人维护代码一眼能看出这些文件是动态依赖。
5.3 CSS 的 @import 嵌套和相对路径陷阱
CSS 里的@import不像 HTML 里的<link>那么透明，它经常多层嵌套：a.css里@import b.css，b.css里又@import c.css。如果扫描时只处理一层，合并出来的 CSS 里还会残留@import语句，而这些语句必须出现在样式表最前面，否则浏览器会直接忽略。ponytail 的做法是递归解析每一层@import，把它引用的内容内联到最终产物中，并把所有@import提升到文件头部。这一步看起来简单，实际上稍有不慎，就会把一个url(../images/bg.png)处理成错误路径。
因为 CSS 合并之后，文件物理位置从原来的深层目录跑到了dist/static，相对路径已经失效。ponytail 在递归解析时会把原文件路径和输出路径做一次换算，把相对路径改写成相对于publicPath的绝对路径。我在这个坑上吃过好几次亏，所以建议你配置完以后，抽查一下合并产物里的url()地址是否还能找到资源。
6. ponytail 和 PurgeCSS、SplitChunks 的定位区别，到底怎么选
6.1 同类工具的对比视角
我经常被问一个问题：有 PurgeCSS 和 Webpack 的 SplitChunks，为什么还需要 ponytail？因为它们的战场完全不同。PurgeCSS 解决的是"没用的 CSS 被删掉"的问题，SplitChunks 解决的是"构建模块怎么拆"的问题，而 ponytail 解决的是"一堆没有模块化体系的静态文件怎么在不改源码的前提下重新组织"的问题。
| 工具 | 核心能力 | 适用场景 | 不能做的事 |
|---|---|---|---|
| PurgeCSS | 删除未使用 CSS 规则 | 已经接入构建链的项目，配合 PostCSS 使用 | 不合并请求数，不改 HTML 引用，无法处理动态 class 拼接 |
| Webpack SplitChunks | 将公共依赖拆成独立 chunk | 基于模块系统的现代项目 | 对纯 HTML + 全局全局变量的老项目基本无效 |
| gulp-concat / postcss-combine | 直接拼接文件 | 简单的资源合并 | 没有依赖分析，不会查冲突，不会重写 HTML |
| ponytail | 扫描 + 分组 + 合并 + HTML 重写 + 冲突报告 | 老的多页应用、无构建链的存量项目 | 不能替代模块化开发，也不适合已有的现代工程 |
从这张表也能看出，ponytail 不是万能的。如果你的项目已经 Webpack 化了，老老实实用 SplitChunks 和 PurgeCSS 才是正道。但如果你手里是那种"除了 HTML 引入没有任何构建"的祖传系统，ponytail 的侵入性是最低的。
6.2 我建议的接入策略：先体检，再局部试点，最后全量
不要第一天就把整个项目的页面全部交给 ponytail 去合并。我踩过的坑是第一次就跑了全量模式，结果一个全局 CSS 被抽到了 vendor 分组，另一个页面里的历史代码因为依赖顺序变化直接白屏。后来我总结了一套稳妥的节奏：
- 先跑
scan，只出报告不改文件，把每个页面的资源依赖树、重复引用、冲突选择器全部过一遍。 - 选两个流量比较低、结构相对简单的页面做试点，比如关于页、协议页，跑通完整 build 流程，看合并产物和页面渲染是否正常。
- 试点稳定后，把
ponytail build挂到 CI 的 postbuild 阶段，每次发布前自动生成合并产物，同时把 conflict report 作为构建产物存档。 - 全量铺开时，一个页面一个页面地切，不要一个 PR 里动所有页面。每个页面合并后单独回归一遍，确认功能没问题再继续下一个。
这样做的好处是风险可控。毕竟工具只是把头发扎起来，扎之前你得先知道每根头发属于谁，才不会把型扎坏。
最后分享一个我在接入过程中常用的技巧
在老项目里跑ponytail scan之后，我会刻意留出半小时做一件事：把所有被标记为"未被任何 HTML 引用"的文件拖到一个deprecated/目录，而不是直接删。因为很多老文件可能被后端模板动态拼路径引用，扫描器不一定看得到。把这些文件隔离保留一个月，确认线上没有报错再彻底删除。这个习惯帮我避过两次线上事故，也给团队留下了安全的清理缓冲期。如果你也打算用 ponytail 整理旧项目，强烈建议保留这个环节。
