上个月我在整理前端项目的静态资源时被一堆散落在各个目录里的图标、字体和配置片段逼得受不了干脆自己做了一个叫 ponytail 的轻量级聚合插件。这篇博文就把 ponytail 插件是什么、能解决什么问题、怎么安装、怎么配置以及我实际使用过程中踩过的坑一次性讲清楚。如果你平时也要维护中大型前端项目经常为了某个图片到底在哪个目录这份路由配置怎么散在二十个模块里而头疼这篇文章应该可以直接帮到你。1. 为什么要做 ponytail被散装资源逼出来的插件1.1 问题现场散落一地的资源我先描述一个具体场景。某个中大型前端项目里组件大概有四五十个每个组件目录下都塞着自己的图标、切图和局部样式。刚开始还好项目一复杂就乱套了设计改了某个按钮图标你要先 grep 出这个图标出现在几个地方然后逐个目录去翻新增一个页面的时候光复制资源就得花小半天更别提上线前要手动把几十个目录的静态资源整理到一起漏一个就是线上事故。配置也是重灾区。新项目起步时大家图方便路由、菜单、权限这些配置经常是每个模块自己维护一份然后在入口文件里手动 import 拼接。模块少还好模块一多合并顺序、命名冲突、重复定义全靠人肉 review经常出现明明我改了配置却不生效这种问题查到最后发现是聚合的时候顺序错了。这种散装状态在团队协作时会格外痛苦因为没有任何一份清单告诉你项目里到底有哪些资源、它们被谁引用了。1.2 名字的由来把碎片拢成一个马尾ponytail 这个名字就是扎马尾的意思。小时候扎头发碎发多得用手拢几圈再拿皮筋一绑所有碎发就服服帖帖。这个插件做的事情一模一样把散落在项目各个角落的资源、配置片段收拢到一起打成一份干净、有序、可追踪的产物。我最初想要的不是又一个构建工具而是一个能随手接进任何项目、把整理资源这件事自动化的命令行工具。于是 ponytail 就诞生了。1.3 什么人适合用它根据我这几个月的使用体验下面这几类项目用 ponytail 收益最大中大型前端项目目录多、资源散人工维护资源清单已经不可行Monorepo 或者多模块仓库需要统一收集各 package 下的图标、图片、字体维护设计系统、图标库、静态站点需要定期重新生成资源映射表构建链路里希望有一层不碰业务代码打包逻辑的资源聚合层而不是把所有事塞给 webpack反过来如果只是一个单页面、几十个文件的小项目所有资源本来就在一个目录里那就没必要上这个工具手动整理更快。ponytail 是为乱而生的你的项目还不乱就别给自己加戏。2. ponytail 的核心原理扫描、匹配、聚合三步走很多人第一次用这类工具都会问这不就是一个递归遍历目录然后拷贝文件吗表面上确实如此但实际落地时有三件事必须处理干净扫描的效率、匹配的准确率、聚合时的依赖顺序。每一步都踩过坑。2.1 扫描阶段目录快照扫描阶段的核心是拿到一份目录快照每个文件的路径、相对路径、后缀、大小、修改时间。我在实现时没有用递归函数而是用了一个显式的栈来做迭代遍历原因是目录层级深的时候递归容易爆调用栈而且迭代写法后面要加并发控制会更方便。import fs from node:fs/promises import path from node:path export async function scan(root) { const results [] const stack [root] while (stack.length 0) { const current stack.pop() const entries await fs.readdir(current, { withFileTypes: true }) for (const entry of entries) { const fullPath path.join(current, entry.name) if (entry.isDirectory()) { stack.push(fullPath) } else { const stat await fs.stat(fullPath) results.push({ path: fullPath, relPath: path.relative(root, fullPath).split(path.sep).join(/), ext: path.extname(fullPath), size: stat.size, mtimeMs: stat.mtimeMs, }) } } } return results }这里有个细节relPath一定要把路径分隔符统一成/。在 Windows 上path.relative返回的是反斜杠如果你不处理后面所有 glob 匹配都会出问题这也是我在实践里排查了很久的一个坑。另外withFileTypes: true这个参数很关键它让你不用对每个 entry 再发一次fs.stat来判断是目录还是文件扫描大目录时性能差距非常明显。2.2 匹配阶段include 与 exclude 的组合规则拿到了文件列表之后接下来就是匹配。ponytail 的规则设计很简单include 负责收exclude 负责挡。import { picomatch } from ponytail/matcher export function isMatched(relPath, include, exclude) { const included include.some((pattern) picomatch(pattern, { dot: true })(relPath)) if (!included) return false const excluded exclude.some((pattern) picomatch(pattern, { dot: true })(relPath)) return !excluded }判定顺序是先看 include 是否命中没命中直接返回 false命中了再看 excludeexclude 命中就排除。换句话说exclude 的优先级永远高于 include。这个设计是为了满足一个常见场景我想收所有 svg但几个测试用的 svg 不要。如果 include 优先级更高你就只能把测试目录从 include 的根路径里绕开非常别扭。匹配使用的是 picomatch 风格的 glob 语法核心规则可以记成一张表模式含义示例*匹配单层路径内的任意字符*.svg匹配a.svg不匹配a/b.svg**匹配任意层路径**/*.svg匹配任意目录下的 svg?匹配单个字符icon-?.png匹配icon-1.png{a,b}花括号枚举{icon,logo}.svg匹配icon.svg和logo.svg!取反但一般建议直接用 exclude!**/*.test.svg2.3 聚合阶段三种输出模式匹配完成之后根据mode配置走不同的聚合逻辑。ponytail 目前支持四种模式manifest把收集到的文件映射成一份 JSON 清单不做内容合并适合我要知道项目里有什么资源的场景sprite把多个图片合并成一张雪碧图适合图标、小切图merge把同一类型的文件按依赖顺序拼接成一个文件适合路由配置、样式片段、入口脚本copy保留目录结构整体拷贝到输出目录适合静态资源部署其中merge模式最依赖依赖排序。比如你要合并多个 CSS 片段reset.css必须排在button.css前面否则后者的选择器可能被前者的样式覆盖。ponytail 在文件头支持// ponytail-deps ./base.css这样的注释声明然后内部用拓扑排序生成最终顺序。function buildOrder(nodes, edges) { const indegree new Map(nodes.map((n) [n.id, 0])) const graph new Map(nodes.map((n) [n.id, []])) for (const [from, to] of edges) { graph.get(from)?.push(to) indegree.set(to, (indegree.get(to) ?? 0) 1) } const queue [...indegree.keys()].filter((id) indegree.get(id) 0) const order [] while (queue.length) { const current queue.shift() order.push(current) for (const next of graph.get(current) ?? []) { indegree.set(next, indegree.get(next) - 1) if (indegree.get(next) 0) queue.push(next) } } if (order.length ! nodes.length) { throw new Error(PON-1001: circular dependency detected) } return order }注意最后的环形依赖检查。如果 A 依赖 B、B 又依赖 A队列永远清空不了这时如果不报错后面生成的合并文件顺序就是错的。我在实际使用中遇到过好几次后面专门讲这个坑。2.4 为什么不用 webpack/rollup 这类打包器有人会问webpack 不是有require.context、rollup 不是能处理静态资源吗何必再造一个轮子。我的回答是定位完全不同。webpack/rollup 的核心工作是构建 JavaScript 模块图处理 import/export 依赖资源只是它们附带处理的对象。而 ponytail 只做一件事按规则收集文件生成映射或合并产物不碰模块图不处理代码语法。这意味着它非常轻安装体积小运行速度快可以独立于项目现有构建链直接使用。比如我的一个静态站点项目根本没有 webpack只是想生成一份图标清单用 ponytail 一个 CLI 命令就搞定了完全没有必要为这点功能引入一整套打包器。它的定位是打包器之前的一道整理工序而不是打包器的替代品。3. 安装与最小配置五分钟跑通3.1 环境要求ponytail 是一个 Node.js 命令行工具环境要求很低Node.js 16 以上npm、pnpm、yarn 任意一个包管理器项目本身可以是任意前端框架Vite、Webpack、纯静态站都可以ponytail 不侵入你的框架逻辑3.2 安装命令在项目根目录执行npm install -D ponytail如果用的是 pnpm 或 yarn对应改成pnpm add -D ponytail yarn add -D ponytail安装完成后可以用下面两条命令验证是否可用npx ponytail --version npx ponytail --help--help输出里能看到所有子命令和参数。第一次用到这个命令的人建议先跑一遍比翻文档快。3.3 最小配置示例在项目根目录创建ponytail.config.mjs// ponytail.config.mjs export default { root: src, include: [**/*.svg, **/*.png], exclude: [**/*.test.png], mode: manifest, output: dist/assets, manifest: dist/asset-manifest.json, hash: true, }然后执行npx ponytail没有意外的话dist/assets下会出现收集到的资源文件同时生成dist/asset-manifest.json里面记录了每个逻辑名对应的产物路径和哈希。整个流程跑完不到一秒。4. 配置项详解每个参数的设计意图4.1 参数总表我把 ponytail 的常用配置项整理成一张表方便你对照查阅参数类型默认值作用rootstringsrc扫描根目录includestring[][]收集规则glob 模式数组excludestring[][]排除规则优先级高于 includemodestringmanifest聚合模式manifest / sprite / merge / copyoutputstringdist/assets产物输出目录manifeststring-manifest 文件完整路径不填则随 output 生成hashbooleantrue文件名是否追加内容哈希transformarray[]文件内容转换钩子见 4.4watchbooleanfalse是否开启监听模式concurrencynumber4文件读取并发数logLevelstringinfo日志级别silent / info / debugmergeobject-merge 模式专用配置见第 6 节4.2 root、include、exclude 的语义root是扫描的起点默认是src。我建议始终显式指定避免在项目根目录扫描到node_modules或者.git。include里的 glob 是相对于root的不是相对于项目根目录的。比如你要收src/components下的所有图标应该写components/**/*.svg而不是src/components/**/*.svg这个细节经常有人搞错。如果你的资源分散在多个完全不相关的区域include 数组里直接写多个模式就可以了不需要硬把它们凑到一个目录下。这也是 ponytail 有价值的地方它不要求你调整现有目录结构只是通过这些规则收集。4.3 mode 的选择mode决定了最终的产物形态我按使用频率给一个选择建议只是想知道项目里有哪些图标、有没有重复命名选manifest前端页面要渲染大量图标为了减少 HTTP 请求选sprite路由、菜单、样式这类代码文件片段要合成一份选merge部署前要把散落的静态资源收拾到一个带版本的目录里选copy一个项目可以同时跑多次 ponytail用不同的配置文件分别处理不同的资源类型。比如我经常在同一个项目里既跑 sprite 生成图标雪碧图又跑 merge 合并路由配置两者互不干扰。4.4 transform: 内容转换钩子transform是我用的最多的扩展点。它的作用是在文件被写进产物之前对内容做一次自定义处理。比如打包前需要把 SVG 里的注释和空白去掉可以这样写export default { root: src, include: [**/icons/**/*.svg, **/icon-*.png], exclude: [**/__tests__/**], mode: sprite, output: dist/assets/icons, manifest: dist/assets/icon-manifest.json, hash: true, transform: [ { test: /\.svg$/, handler: (content, file) content.replace(/!--[\s\S]*?--/g, ), }, ], }handler的入参是文件的原始 Buffer返回值可以是 Buffer 或字符串。如果返回null这个文件会被跳过不进产物。很多教程把 transform 当成简单的字符串替换实际上它也可以用来过滤文件、修改文件名、甚至把内容转成另一种格式。我在后面讲编码问题的场景时还会用 transform 来处理 BOM 头。4.5 watch: 增量构建与防抖watch: true会启动文件监听源文件一旦变化就重新聚合。这里有个必踩的坑如果监听器不加防抖你改一个文件保存三次它就可能触发三次重复构建。我的做法是把内部监听改成 200ms 防抖并且每次重启构建前先取消旧的监听器否则旧监听器还挂在已删除的文件上内存会一点点涨上去。如果你在大型仓库里用 watch建议同时在两个维度控制开销一是concurrency不要设太高磁盘 IO 会成为瓶颈二是排除掉.git目录否则监听器会遍历到大量历史对象文件。比如export default { root: src, watch: true, exclude: [**/.git/**], concurrency: 4, }监听构建的日志最好也开debug级别能清楚看到每个文件是被哪个规则命中的这对排查为什么我改了文件却没进产物极其有用。5. 实战场景一把图标资源收拢成一份清单5.1 需求拆解很多后台管理系统有几十个模块每个模块目录下都有icons/文件夹里面是一堆 svg 和 png。设计师经常改图标改完我要逐个通知依赖方还要保证线上资源是最新的。最合理的方式是把所有图标收进一个带哈希的产物目录同时生成一份 JSON 清单前端组件根据逻辑名去清单里找真实的 URL。这样只要重新跑一次 ponytail整个项目的图标引用就全部更新了。5.2 目录结构与配置假设项目有一个典型结构src/ features/ home/icons/icon-home.svg user/icons/icon-user.svg shared/icons/icon-logo.svg配置文件// ponytail.config.mjs export default { root: src, include: [**/icons/**/*.svg, **/icon-*.png], exclude: [**/__tests__/**, **/draft/**], mode: sprite, output: dist/assets/icons, manifest: dist/assets/icon-manifest.json, hash: true, transform: [ { test: /\.svg$/, handler: (content) content.replace(/!--[\s\S]*?--/g, ), }, ], }这里 include 写了两个模式一个收目录名是icons的 svg一个收散落在各处的以icon-开头的 png。exclude 把测试目录和草稿目录挡在外面。sprite mode 会把所有 svg 合成一张雪碧图png 因为格式原因不适合进雪碧图会被单独哈希拷贝。5.3 执行结果与产物解读执行npx ponytail之后生成的 manifest 大概是这样的{ icon-home.svg: { id: icon-home, url: /assets/icons/sprite.8302ab.svg#icon-home }, icon-user.svg: { id: icon-user, url: /assets/icons/sprite.8302ab.svg#icon-user }, icon-logo.png: { id: icon-logo, url: /assets/icons/icon-logo.7f3a91.png } }同一张雪碧图里的 svg 共享同一个文件名靠#icon-home这样的锚点区分。pn g 没有进雪碧图所以是独立的哈希文件。前端引用的时候一个统一 Icon 组件根据 manifest 里的 id 去查找 URL业务代码里只需要写Icon nameicon-home /不需要关心文件到底在哪。5.4 注意哈希变化的连锁反应加了hash: true之后只要文件内容变化哈希就会变引用它的地方要跟着刷新。所以在实际项目里我会把 manifest 的生成接入构建流程而不是手动引入前端组件在启动时先统一加载这份 JSON而不是把 URL 硬编码到代码里。这样设计师改了图标我只需要重新跑一次 ponytail然后提交增量产物线上页面自动拿到新的哈希 URL。6. 实战场景二合并散落的配置片段6.1 场景描述路由配置是最典型的该合并却没人合并的例子。项目模块多每个features目录下都有一份route.js入口文件里手动 import。每次新增页面开发者可能忘了把自己的路由 import 进去或者 import 顺序有误导致路由优先级不对。原始文件示例// src/features/home/route.js export const homeRoutes [ { path: /, component: HomePage, meta: { title: 首页 } }, ]// src/features/user/route.js // ponytail-deps ./account export const userRoutes [ { path: /user, component: UserPage, meta: { title: 用户 } }, ]6.2 配置与依赖声明用merge模式把这些片段拼成一份完整路由文件// ponytail.config.mjs export default { root: src, include: [**/route.js], mode: merge, output: dist/generated, merge: { type: js, content: export const routes [\n__PONYTAIL_FRAGMENTS__\n], separator: ,\n, }, }最终的dist/generated/routes.js会变成export const routes [ { path: /, component: HomePage, meta: { title: 首页 } }, { path: /user, component: UserPage, meta: { title: 用户 } }, ]__PONYTAIL_FRAGMENTS__是占位符ponytail 会把所有匹配到的route.js里的导出内容按拓扑排序后填入。上面user/route.js里写的ponytail-deps ./account声明了它依赖同目录下的account/route.js所以排序时 account 会排在 user 前面。这个依赖声明是 merge 模式最重要也最容易忽略的机制。6.3 merge 模式的注意点使用 merge 模式时有三个问题我在实践中反复遇到第一导出格式要统一。如果你某个route.js用的是export const另一个用的是module.exportsmerge 出来的文件就没法直接用。建议团队里定一个规范所有待聚合文件都用同一套导出格式否则就要在 transform 里做兼容。第二命名冲突不可避免。不同模块可能都定义了routes这个变量名merge 时同名导出会导致结果错乱。所以我在项目里约定被聚合的文件只写数组字面量不做变量命名由 ponytail 的 content 模板统一包一层。这也是上面配置里 content 模板设计的初衷。第三依赖声明要克制。不要轻易在两个模块之间加ponytail-deps加多了会出现环形依赖。环形依赖一旦出现聚合直接报错后续产物不会生成。这种设计是故意的因为宁可失败也不要给出一份顺序错误的路由配置。7. 踩过的坑与完整排查链路工具做得再顺手坑还是得踩出来。下面这几个问题是我在真实项目里遇到过的每个都花了至少半天才定位到根因。7.1 环形依赖聚合死循环第一个项目接入 merge 模式一周后就出问题了menus 模块依赖 permissions 模块permissions 模块又反向依赖 menus 模块的某个常量。拓扑排序直接抛错PON-1001: circular dependency detected。当时我第一反应是代码写错了但查了半天发现是语义上两边其实可以互相引用。后来我把公共常量抽到了shared/constants.js两边都改成依赖它环形依赖才消除。排查这类问题的关键思路是把依赖图打出来。在配置里把logLevel设为debugponytail 会输出每个文件依赖了谁、被谁依赖。我建议一看到环形依赖报错不要急着改代码先花五分钟看完整依赖图判断是抽公共层还是反向依赖。环形依赖不是 bug是你模块划分边界的信号。7.2 UTF-8 BOM 引发的幽灵字符另一个隐藏很深的坑是编码问题。某个老项目里有一批配置文件是 Windows 上编辑的带 UTF-8 BOM 头。manifest 生成本来没问题但前端读 JSON 时同一份文件里某些字段莫名多了\ufeff前缀导致 key 对不上。排查了一个下午最后用hexdump -C看文件头部才发现是EF BB BF。解决方案不复杂在 transform 里做一个前置清理transform: [ { test: /\.(js|json)$/, handler: (buf) { if (buf.length 2 buf[0] 0xef buf[1] 0xbb buf[2] 0xbf) { return buf.subarray(3) } return buf }, }, ]另外要留意历史遗留的 GBK 编码文件。这类文件只有中文注释用 UTF-8 解码会变成乱码merge 出来之后整个文件都受影响。我的处理方式是在项目里明确约定所有被聚合的源码必须 UTF-8并在 transform 里做一次Buffer.isUtf8()检查检测不过的直接在 debug 日志里警告。宁可让构建失败也不要让乱码静默进入产物。7.3 glob 通配的边界问题第三个坑来自 glob 匹配本身。很多人以为**/*.svg能匹配根目录下的home.svg但 picomatch 的语义里**匹配任意层路径至少包含一层分隔符所以根目录下的文件必须用*.svg单独匹配。我当时收集图标时发现根目录的icon-logo.svg一直没进 manifest就是这个问题。另一个容易踩的是大小写敏感。Linux 和 macOS 的文件系统默认区分大小写**/*.SVG匹配不到home.svg。我在代码里做了相对路径标准化但 glob 本身仍然按大小写敏感处理。排查时建议先用指令验证一下npx ponytail --debug-match **/*.svg src/icons/home.svg如果输出matched: true说明规则没问题问题出在文件路径或者 exclude 规则如果输出matched: false那就按上面讲的两个边界去排除。7.4 watch 模式下的资源占用最后一个是 watch 模式的性能问题。我最初在 monorepo 里开了 watch结果 IDE 都能感觉变卡。排查发现原因有三一是监听范围过大包含了所有 package 的 node_modules二是没有做防抖保存一次文件触发三次构建三是旧监听器没有释放。解决方案是把minDepth类和排除规则配合起来只监听 src 目录同时把防抖设为 200ms。实践下来watch 模式比较适合前端本地开发时边改图标边看效果的场景。而在 CI 构建场景我完全不用 watch直接跑一次全量聚合保证每次构建都从干净的快照开始避免增量构建状态污染。8. 几个我觉得很值的小调整文章最后分享几个我在实际使用中摸索出来的小经验不是工具文档里会写的东西。第一把 ponytail 接进 CI。我在每次 push 之后会自动重新生成 manifest并在 PR 里对 manifest 做 diff review。谁改了图标、删了哪个文件、哈希变了多少一眼就能看出来。这比任何口头规范都好使因为它是机器自动执行的不会因为某个人忘了跑命令而失效。第二给输出目录加一层版本号。我之前习惯让 output 直接指向dist/assets后来发现还是指向dist/assets/v3-xxxx这种带版本号的目录更省心回滚时只需要切换引用版本。虽然 hash 已经保证了内容级唯一但版本号在团队协作时更容易沟通。第三多配置文件并行。一个项目要用多种聚合方式时我建议拆成多个配置文件比如ponytail.config.icons.mjs管图标、ponytail.config.routes.mjs管路由然后在 npm scripts 里用ponytail -c xxx.mjs分别调用。这样每种聚合的产物路径、依赖规则、日志开关都可以独立调整出了问题也只需要单独看一份配置。ponytail 这个名字在别人听来可能像个玩笑但它解决的是资源治理里最琐碎也最磨人的那部分。我做完之后最大的体会是很多所谓的项目乱其实不是人的执行力问题而是缺少一层自动化的整理工序。把松散的东西定期收拢到一起并且让这个过程可重复、可审查项目自然就会清爽起来。如果你也在被散落的资源折磨不妨试试这个思路工具本身不复杂复杂的是你愿不愿意花一个下午把它接进日常流程。
上个月我在整理前端项目的静态资源时被一堆散落在各个目录里的图标、字体和配置片段逼得受不了干脆自己做了一个叫 ponytail 的轻量级聚合插件。这篇博文就把 ponytail 插件是什么、能解决什么问题、怎么安装、怎么配置以及我实际使用过程中踩过的坑一次性讲清楚。如果你平时也要维护中大型前端项目经常为了某个图片到底在哪个目录这份路由配置怎么散在二十个模块里而头疼这篇文章应该可以直接帮到你。1. 为什么要做 ponytail被散装资源逼出来的插件1.1 问题现场散落一地的资源我先描述一个具体场景。某个中大型前端项目里组件大概有四五十个每个组件目录下都塞着自己的图标、切图和局部样式。刚开始还好项目一复杂就乱套了设计改了某个按钮图标你要先 grep 出这个图标出现在几个地方然后逐个目录去翻新增一个页面的时候光复制资源就得花小半天更别提上线前要手动把几十个目录的静态资源整理到一起漏一个就是线上事故。配置也是重灾区。新项目起步时大家图方便路由、菜单、权限这些配置经常是每个模块自己维护一份然后在入口文件里手动 import 拼接。模块少还好模块一多合并顺序、命名冲突、重复定义全靠人肉 review经常出现明明我改了配置却不生效这种问题查到最后发现是聚合的时候顺序错了。这种散装状态在团队协作时会格外痛苦因为没有任何一份清单告诉你项目里到底有哪些资源、它们被谁引用了。1.2 名字的由来把碎片拢成一个马尾ponytail 这个名字就是扎马尾的意思。小时候扎头发碎发多得用手拢几圈再拿皮筋一绑所有碎发就服服帖帖。这个插件做的事情一模一样把散落在项目各个角落的资源、配置片段收拢到一起打成一份干净、有序、可追踪的产物。我最初想要的不是又一个构建工具而是一个能随手接进任何项目、把整理资源这件事自动化的命令行工具。于是 ponytail 就诞生了。1.3 什么人适合用它根据我这几个月的使用体验下面这几类项目用 ponytail 收益最大中大型前端项目目录多、资源散人工维护资源清单已经不可行Monorepo 或者多模块仓库需要统一收集各 package 下的图标、图片、字体维护设计系统、图标库、静态站点需要定期重新生成资源映射表构建链路里希望有一层不碰业务代码打包逻辑的资源聚合层而不是把所有事塞给 webpack反过来如果只是一个单页面、几十个文件的小项目所有资源本来就在一个目录里那就没必要上这个工具手动整理更快。ponytail 是为乱而生的你的项目还不乱就别给自己加戏。2. ponytail 的核心原理扫描、匹配、聚合三步走很多人第一次用这类工具都会问这不就是一个递归遍历目录然后拷贝文件吗表面上确实如此但实际落地时有三件事必须处理干净扫描的效率、匹配的准确率、聚合时的依赖顺序。每一步都踩过坑。2.1 扫描阶段目录快照扫描阶段的核心是拿到一份目录快照每个文件的路径、相对路径、后缀、大小、修改时间。我在实现时没有用递归函数而是用了一个显式的栈来做迭代遍历原因是目录层级深的时候递归容易爆调用栈而且迭代写法后面要加并发控制会更方便。import fs from node:fs/promises import path from node:path export async function scan(root) { const results [] const stack [root] while (stack.length 0) { const current stack.pop() const entries await fs.readdir(current, { withFileTypes: true }) for (const entry of entries) { const fullPath path.join(current, entry.name) if (entry.isDirectory()) { stack.push(fullPath) } else { const stat await fs.stat(fullPath) results.push({ path: fullPath, relPath: path.relative(root, fullPath).split(path.sep).join(/), ext: path.extname(fullPath), size: stat.size, mtimeMs: stat.mtimeMs, }) } } } return results }这里有个细节relPath一定要把路径分隔符统一成/。在 Windows 上path.relative返回的是反斜杠如果你不处理后面所有 glob 匹配都会出问题这也是我在实践里排查了很久的一个坑。另外withFileTypes: true这个参数很关键它让你不用对每个 entry 再发一次fs.stat来判断是目录还是文件扫描大目录时性能差距非常明显。2.2 匹配阶段include 与 exclude 的组合规则拿到了文件列表之后接下来就是匹配。ponytail 的规则设计很简单include 负责收exclude 负责挡。import { picomatch } from ponytail/matcher export function isMatched(relPath, include, exclude) { const included include.some((pattern) picomatch(pattern, { dot: true })(relPath)) if (!included) return false const excluded exclude.some((pattern) picomatch(pattern, { dot: true })(relPath)) return !excluded }判定顺序是先看 include 是否命中没命中直接返回 false命中了再看 excludeexclude 命中就排除。换句话说exclude 的优先级永远高于 include。这个设计是为了满足一个常见场景我想收所有 svg但几个测试用的 svg 不要。如果 include 优先级更高你就只能把测试目录从 include 的根路径里绕开非常别扭。匹配使用的是 picomatch 风格的 glob 语法核心规则可以记成一张表模式含义示例*匹配单层路径内的任意字符*.svg匹配a.svg不匹配a/b.svg**匹配任意层路径**/*.svg匹配任意目录下的 svg?匹配单个字符icon-?.png匹配icon-1.png{a,b}花括号枚举{icon,logo}.svg匹配icon.svg和logo.svg!取反但一般建议直接用 exclude!**/*.test.svg2.3 聚合阶段三种输出模式匹配完成之后根据mode配置走不同的聚合逻辑。ponytail 目前支持四种模式manifest把收集到的文件映射成一份 JSON 清单不做内容合并适合我要知道项目里有什么资源的场景sprite把多个图片合并成一张雪碧图适合图标、小切图merge把同一类型的文件按依赖顺序拼接成一个文件适合路由配置、样式片段、入口脚本copy保留目录结构整体拷贝到输出目录适合静态资源部署其中merge模式最依赖依赖排序。比如你要合并多个 CSS 片段reset.css必须排在button.css前面否则后者的选择器可能被前者的样式覆盖。ponytail 在文件头支持// ponytail-deps ./base.css这样的注释声明然后内部用拓扑排序生成最终顺序。function buildOrder(nodes, edges) { const indegree new Map(nodes.map((n) [n.id, 0])) const graph new Map(nodes.map((n) [n.id, []])) for (const [from, to] of edges) { graph.get(from)?.push(to) indegree.set(to, (indegree.get(to) ?? 0) 1) } const queue [...indegree.keys()].filter((id) indegree.get(id) 0) const order [] while (queue.length) { const current queue.shift() order.push(current) for (const next of graph.get(current) ?? []) { indegree.set(next, indegree.get(next) - 1) if (indegree.get(next) 0) queue.push(next) } } if (order.length ! nodes.length) { throw new Error(PON-1001: circular dependency detected) } return order }注意最后的环形依赖检查。如果 A 依赖 B、B 又依赖 A队列永远清空不了这时如果不报错后面生成的合并文件顺序就是错的。我在实际使用中遇到过好几次后面专门讲这个坑。2.4 为什么不用 webpack/rollup 这类打包器有人会问webpack 不是有require.context、rollup 不是能处理静态资源吗何必再造一个轮子。我的回答是定位完全不同。webpack/rollup 的核心工作是构建 JavaScript 模块图处理 import/export 依赖资源只是它们附带处理的对象。而 ponytail 只做一件事按规则收集文件生成映射或合并产物不碰模块图不处理代码语法。这意味着它非常轻安装体积小运行速度快可以独立于项目现有构建链直接使用。比如我的一个静态站点项目根本没有 webpack只是想生成一份图标清单用 ponytail 一个 CLI 命令就搞定了完全没有必要为这点功能引入一整套打包器。它的定位是打包器之前的一道整理工序而不是打包器的替代品。3. 安装与最小配置五分钟跑通3.1 环境要求ponytail 是一个 Node.js 命令行工具环境要求很低Node.js 16 以上npm、pnpm、yarn 任意一个包管理器项目本身可以是任意前端框架Vite、Webpack、纯静态站都可以ponytail 不侵入你的框架逻辑3.2 安装命令在项目根目录执行npm install -D ponytail如果用的是 pnpm 或 yarn对应改成pnpm add -D ponytail yarn add -D ponytail安装完成后可以用下面两条命令验证是否可用npx ponytail --version npx ponytail --help--help输出里能看到所有子命令和参数。第一次用到这个命令的人建议先跑一遍比翻文档快。3.3 最小配置示例在项目根目录创建ponytail.config.mjs// ponytail.config.mjs export default { root: src, include: [**/*.svg, **/*.png], exclude: [**/*.test.png], mode: manifest, output: dist/assets, manifest: dist/asset-manifest.json, hash: true, }然后执行npx ponytail没有意外的话dist/assets下会出现收集到的资源文件同时生成dist/asset-manifest.json里面记录了每个逻辑名对应的产物路径和哈希。整个流程跑完不到一秒。4. 配置项详解每个参数的设计意图4.1 参数总表我把 ponytail 的常用配置项整理成一张表方便你对照查阅参数类型默认值作用rootstringsrc扫描根目录includestring[][]收集规则glob 模式数组excludestring[][]排除规则优先级高于 includemodestringmanifest聚合模式manifest / sprite / merge / copyoutputstringdist/assets产物输出目录manifeststring-manifest 文件完整路径不填则随 output 生成hashbooleantrue文件名是否追加内容哈希transformarray[]文件内容转换钩子见 4.4watchbooleanfalse是否开启监听模式concurrencynumber4文件读取并发数logLevelstringinfo日志级别silent / info / debugmergeobject-merge 模式专用配置见第 6 节4.2 root、include、exclude 的语义root是扫描的起点默认是src。我建议始终显式指定避免在项目根目录扫描到node_modules或者.git。include里的 glob 是相对于root的不是相对于项目根目录的。比如你要收src/components下的所有图标应该写components/**/*.svg而不是src/components/**/*.svg这个细节经常有人搞错。如果你的资源分散在多个完全不相关的区域include 数组里直接写多个模式就可以了不需要硬把它们凑到一个目录下。这也是 ponytail 有价值的地方它不要求你调整现有目录结构只是通过这些规则收集。4.3 mode 的选择mode决定了最终的产物形态我按使用频率给一个选择建议只是想知道项目里有哪些图标、有没有重复命名选manifest前端页面要渲染大量图标为了减少 HTTP 请求选sprite路由、菜单、样式这类代码文件片段要合成一份选merge部署前要把散落的静态资源收拾到一个带版本的目录里选copy一个项目可以同时跑多次 ponytail用不同的配置文件分别处理不同的资源类型。比如我经常在同一个项目里既跑 sprite 生成图标雪碧图又跑 merge 合并路由配置两者互不干扰。4.4 transform: 内容转换钩子transform是我用的最多的扩展点。它的作用是在文件被写进产物之前对内容做一次自定义处理。比如打包前需要把 SVG 里的注释和空白去掉可以这样写export default { root: src, include: [**/icons/**/*.svg, **/icon-*.png], exclude: [**/__tests__/**], mode: sprite, output: dist/assets/icons, manifest: dist/assets/icon-manifest.json, hash: true, transform: [ { test: /\.svg$/, handler: (content, file) content.replace(/!--[\s\S]*?--/g, ), }, ], }handler的入参是文件的原始 Buffer返回值可以是 Buffer 或字符串。如果返回null这个文件会被跳过不进产物。很多教程把 transform 当成简单的字符串替换实际上它也可以用来过滤文件、修改文件名、甚至把内容转成另一种格式。我在后面讲编码问题的场景时还会用 transform 来处理 BOM 头。4.5 watch: 增量构建与防抖watch: true会启动文件监听源文件一旦变化就重新聚合。这里有个必踩的坑如果监听器不加防抖你改一个文件保存三次它就可能触发三次重复构建。我的做法是把内部监听改成 200ms 防抖并且每次重启构建前先取消旧的监听器否则旧监听器还挂在已删除的文件上内存会一点点涨上去。如果你在大型仓库里用 watch建议同时在两个维度控制开销一是concurrency不要设太高磁盘 IO 会成为瓶颈二是排除掉.git目录否则监听器会遍历到大量历史对象文件。比如export default { root: src, watch: true, exclude: [**/.git/**], concurrency: 4, }监听构建的日志最好也开debug级别能清楚看到每个文件是被哪个规则命中的这对排查为什么我改了文件却没进产物极其有用。5. 实战场景一把图标资源收拢成一份清单5.1 需求拆解很多后台管理系统有几十个模块每个模块目录下都有icons/文件夹里面是一堆 svg 和 png。设计师经常改图标改完我要逐个通知依赖方还要保证线上资源是最新的。最合理的方式是把所有图标收进一个带哈希的产物目录同时生成一份 JSON 清单前端组件根据逻辑名去清单里找真实的 URL。这样只要重新跑一次 ponytail整个项目的图标引用就全部更新了。5.2 目录结构与配置假设项目有一个典型结构src/ features/ home/icons/icon-home.svg user/icons/icon-user.svg shared/icons/icon-logo.svg配置文件// ponytail.config.mjs export default { root: src, include: [**/icons/**/*.svg, **/icon-*.png], exclude: [**/__tests__/**, **/draft/**], mode: sprite, output: dist/assets/icons, manifest: dist/assets/icon-manifest.json, hash: true, transform: [ { test: /\.svg$/, handler: (content) content.replace(/!--[\s\S]*?--/g, ), }, ], }这里 include 写了两个模式一个收目录名是icons的 svg一个收散落在各处的以icon-开头的 png。exclude 把测试目录和草稿目录挡在外面。sprite mode 会把所有 svg 合成一张雪碧图png 因为格式原因不适合进雪碧图会被单独哈希拷贝。5.3 执行结果与产物解读执行npx ponytail之后生成的 manifest 大概是这样的{ icon-home.svg: { id: icon-home, url: /assets/icons/sprite.8302ab.svg#icon-home }, icon-user.svg: { id: icon-user, url: /assets/icons/sprite.8302ab.svg#icon-user }, icon-logo.png: { id: icon-logo, url: /assets/icons/icon-logo.7f3a91.png } }同一张雪碧图里的 svg 共享同一个文件名靠#icon-home这样的锚点区分。pn g 没有进雪碧图所以是独立的哈希文件。前端引用的时候一个统一 Icon 组件根据 manifest 里的 id 去查找 URL业务代码里只需要写Icon nameicon-home /不需要关心文件到底在哪。5.4 注意哈希变化的连锁反应加了hash: true之后只要文件内容变化哈希就会变引用它的地方要跟着刷新。所以在实际项目里我会把 manifest 的生成接入构建流程而不是手动引入前端组件在启动时先统一加载这份 JSON而不是把 URL 硬编码到代码里。这样设计师改了图标我只需要重新跑一次 ponytail然后提交增量产物线上页面自动拿到新的哈希 URL。6. 实战场景二合并散落的配置片段6.1 场景描述路由配置是最典型的该合并却没人合并的例子。项目模块多每个features目录下都有一份route.js入口文件里手动 import。每次新增页面开发者可能忘了把自己的路由 import 进去或者 import 顺序有误导致路由优先级不对。原始文件示例// src/features/home/route.js export const homeRoutes [ { path: /, component: HomePage, meta: { title: 首页 } }, ]// src/features/user/route.js // ponytail-deps ./account export const userRoutes [ { path: /user, component: UserPage, meta: { title: 用户 } }, ]6.2 配置与依赖声明用merge模式把这些片段拼成一份完整路由文件// ponytail.config.mjs export default { root: src, include: [**/route.js], mode: merge, output: dist/generated, merge: { type: js, content: export const routes [\n__PONYTAIL_FRAGMENTS__\n], separator: ,\n, }, }最终的dist/generated/routes.js会变成export const routes [ { path: /, component: HomePage, meta: { title: 首页 } }, { path: /user, component: UserPage, meta: { title: 用户 } }, ]__PONYTAIL_FRAGMENTS__是占位符ponytail 会把所有匹配到的route.js里的导出内容按拓扑排序后填入。上面user/route.js里写的ponytail-deps ./account声明了它依赖同目录下的account/route.js所以排序时 account 会排在 user 前面。这个依赖声明是 merge 模式最重要也最容易忽略的机制。6.3 merge 模式的注意点使用 merge 模式时有三个问题我在实践中反复遇到第一导出格式要统一。如果你某个route.js用的是export const另一个用的是module.exportsmerge 出来的文件就没法直接用。建议团队里定一个规范所有待聚合文件都用同一套导出格式否则就要在 transform 里做兼容。第二命名冲突不可避免。不同模块可能都定义了routes这个变量名merge 时同名导出会导致结果错乱。所以我在项目里约定被聚合的文件只写数组字面量不做变量命名由 ponytail 的 content 模板统一包一层。这也是上面配置里 content 模板设计的初衷。第三依赖声明要克制。不要轻易在两个模块之间加ponytail-deps加多了会出现环形依赖。环形依赖一旦出现聚合直接报错后续产物不会生成。这种设计是故意的因为宁可失败也不要给出一份顺序错误的路由配置。7. 踩过的坑与完整排查链路工具做得再顺手坑还是得踩出来。下面这几个问题是我在真实项目里遇到过的每个都花了至少半天才定位到根因。7.1 环形依赖聚合死循环第一个项目接入 merge 模式一周后就出问题了menus 模块依赖 permissions 模块permissions 模块又反向依赖 menus 模块的某个常量。拓扑排序直接抛错PON-1001: circular dependency detected。当时我第一反应是代码写错了但查了半天发现是语义上两边其实可以互相引用。后来我把公共常量抽到了shared/constants.js两边都改成依赖它环形依赖才消除。排查这类问题的关键思路是把依赖图打出来。在配置里把logLevel设为debugponytail 会输出每个文件依赖了谁、被谁依赖。我建议一看到环形依赖报错不要急着改代码先花五分钟看完整依赖图判断是抽公共层还是反向依赖。环形依赖不是 bug是你模块划分边界的信号。7.2 UTF-8 BOM 引发的幽灵字符另一个隐藏很深的坑是编码问题。某个老项目里有一批配置文件是 Windows 上编辑的带 UTF-8 BOM 头。manifest 生成本来没问题但前端读 JSON 时同一份文件里某些字段莫名多了\ufeff前缀导致 key 对不上。排查了一个下午最后用hexdump -C看文件头部才发现是EF BB BF。解决方案不复杂在 transform 里做一个前置清理transform: [ { test: /\.(js|json)$/, handler: (buf) { if (buf.length 2 buf[0] 0xef buf[1] 0xbb buf[2] 0xbf) { return buf.subarray(3) } return buf }, }, ]另外要留意历史遗留的 GBK 编码文件。这类文件只有中文注释用 UTF-8 解码会变成乱码merge 出来之后整个文件都受影响。我的处理方式是在项目里明确约定所有被聚合的源码必须 UTF-8并在 transform 里做一次Buffer.isUtf8()检查检测不过的直接在 debug 日志里警告。宁可让构建失败也不要让乱码静默进入产物。7.3 glob 通配的边界问题第三个坑来自 glob 匹配本身。很多人以为**/*.svg能匹配根目录下的home.svg但 picomatch 的语义里**匹配任意层路径至少包含一层分隔符所以根目录下的文件必须用*.svg单独匹配。我当时收集图标时发现根目录的icon-logo.svg一直没进 manifest就是这个问题。另一个容易踩的是大小写敏感。Linux 和 macOS 的文件系统默认区分大小写**/*.SVG匹配不到home.svg。我在代码里做了相对路径标准化但 glob 本身仍然按大小写敏感处理。排查时建议先用指令验证一下npx ponytail --debug-match **/*.svg src/icons/home.svg如果输出matched: true说明规则没问题问题出在文件路径或者 exclude 规则如果输出matched: false那就按上面讲的两个边界去排除。7.4 watch 模式下的资源占用最后一个是 watch 模式的性能问题。我最初在 monorepo 里开了 watch结果 IDE 都能感觉变卡。排查发现原因有三一是监听范围过大包含了所有 package 的 node_modules二是没有做防抖保存一次文件触发三次构建三是旧监听器没有释放。解决方案是把minDepth类和排除规则配合起来只监听 src 目录同时把防抖设为 200ms。实践下来watch 模式比较适合前端本地开发时边改图标边看效果的场景。而在 CI 构建场景我完全不用 watch直接跑一次全量聚合保证每次构建都从干净的快照开始避免增量构建状态污染。8. 几个我觉得很值的小调整文章最后分享几个我在实际使用中摸索出来的小经验不是工具文档里会写的东西。第一把 ponytail 接进 CI。我在每次 push 之后会自动重新生成 manifest并在 PR 里对 manifest 做 diff review。谁改了图标、删了哪个文件、哈希变了多少一眼就能看出来。这比任何口头规范都好使因为它是机器自动执行的不会因为某个人忘了跑命令而失效。第二给输出目录加一层版本号。我之前习惯让 output 直接指向dist/assets后来发现还是指向dist/assets/v3-xxxx这种带版本号的目录更省心回滚时只需要切换引用版本。虽然 hash 已经保证了内容级唯一但版本号在团队协作时更容易沟通。第三多配置文件并行。一个项目要用多种聚合方式时我建议拆成多个配置文件比如ponytail.config.icons.mjs管图标、ponytail.config.routes.mjs管路由然后在 npm scripts 里用ponytail -c xxx.mjs分别调用。这样每种聚合的产物路径、依赖规则、日志开关都可以独立调整出了问题也只需要单独看一份配置。ponytail 这个名字在别人听来可能像个玩笑但它解决的是资源治理里最琐碎也最磨人的那部分。我做完之后最大的体会是很多所谓的项目乱其实不是人的执行力问题而是缺少一层自动化的整理工序。把松散的东西定期收拢到一起并且让这个过程可重复、可审查项目自然就会清爽起来。如果你也在被散落的资源折磨不妨试试这个思路工具本身不复杂复杂的是你愿不愿意花一个下午把它接进日常流程。
