做前端这几年，我遇到最多的“小事”之一就是：界面需要一张头像，设计稿还没出，临时找的图又有版权问题，用 Lorem Picsum 又觉得太不上心。后来我把一个内部用的占位图小工具整理成了一个开源插件，给它取名叫 ponytail——字面是马尾辫，寓意是“把临时素材像扎辫子一样收拾利索，随手就能用”。这篇文章就来聊聊这个叫 ponytail 的插件是怎么设计的、怎么接入项目、以及我从维护它到现在踩过的坑和积累的经验。

先说 ponytail 能做什么：它是一个轻量级的 SVG 占位图/头像生成插件，可以根据尺寸、文字、颜色、seed 种子等参数，在本地快速生成风格统一的占位图，支持命令行、JS API 和 Vite 插件三种用法。适合前端开发、全栈开发、UI 走查、以及任何需要在项目早期准备 mock 数据的场景。如果你也烦透了“开局一张图，内容全靠猜”的尴尬期，ponytail 这招技能（有人管它叫 ponytail skill，其实就是一套快速生成占位图的玩法）值得花几分钟学会。

1. ponytail 想解决什么问题：从一个临时头像需求说起

1.1 场景还原：从 UI 稿到代码之间的空窗期

先还原一个我反复遇到的场景。需求评审通过之后，设计师开始出正式稿，但前端不能干等。产品说“先搭页面，头像用占位图就行”，于是我开始找图。第一反应是去图片网站下载几张企业头像，但很快就遇到问题：风格不统一，有的偏写真、有的偏插画，放在同一个用户列表里非常违和；版权也不清楚，总不能给客户演示的时候用一张别人网站上随意下载的照片。

更麻烦的是，这些图片需要手动裁剪成不同尺寸。列表页要 80x80，详情页要 200x200，消息页要 48x48，同一个人的头像在不同位置如果比例不统一，看起来就像三个人。我需要的是一个能“按需生成、风格一致、本地离线可用”的占位图方案，而不是反复去图库挑图、切图。

1.2 为什么不用现成的占位图网站

可能有人会说，网上有那么多占位图服务，直接用不就行了。说实话，我也用过，但用着用着就会发现几个硬伤。

第一个是稳定性。占位图服务本质上是一个远程接口，接口挂了或者网络慢，页面上的图片就会被浏览器标记为加载失败，轻则显示破图图标，重则影响布局。第二个是可控性。第三方服务返回的图片风格、颜色、文字样式都是固定的，我想把文字改成“用户名”“待上传”都做不到，更不要说统一色调。第三个是协作问题，在很多企业内网或离线开发环境下，外网图片根本加载不出来。

我自己比较喜欢的一个类比是：外链占位图就像跟邻居借菜刀，偶尔用一次可以，天天做饭还要看邻居脸色就太难受了。自己本地准备一套工具，虽然前期花十几分钟配置，之后每天都能顺手用，体验完全不同。

1.3 ponytail 的功能定位

所以 ponytail 从设计之初就没打算做复杂的图片处理，只专注三个核心能力：尺寸规范化、颜色随机但可调、输出本地 SVG 文件或 data URL。它不替代真正的图片处理工具，只解决“开发阶段缺一张风格统一的临时图”这一个点。

听起来简单，但真正做起来有一些细节值得聊。

2. 技术选型：为什么是 SVG 而不是 Canvas 或 Sharp

2.1 三种技术方案对比

在决定 ponytail 的底层实现时，我其实在 SVG、Canvas、Sharp 之间纠结了很久。下面这张表可以说明我当时是怎么想的：

最后我选了 SVG，原因有三点。第一，SVG 本质是纯文本，我可以直接拼字符串生成，完全不需要引入二进制依赖，安装起来快，而且在 Linux 服务器、Windows 本地打包都稳定。第二，SVG 是矢量格式，无论前端把它放大缩到多少，边缘都不会模糊，占位图最重要的就是“看得清”。第三，SVG 可以直接转换成 data URL 塞进 标签，也可以简单保存成 .svg 文件，对前端来说零成本。

2.2 核心实现思路：一行模板字符串拼接出的图片

ponytail 的核心其实很简单，没有高深算法。我预置了一套色板，根据 seed 参数计算出一个稳定索引，然后用这个索引选前景色和背景色，再把尺寸、文字填充进一个 SVG 模板。

用代码来表达大概是这样：

// 伪代码，演示核心思路 const PALETTE = [ { bg: '#E8F1FF', fg: '#2E5BFF' }, { bg: '#FFEFE6', fg: '#FF7A45' }, // ... 更多配色 ]; export function generateSvg({ width = 200, height = 200, seed = 'default', text, }: Options) { // 根据 seed 生成稳定的 hash const hash = simpleHash(seed); const palette = PALETTE[hash % PALETTE.length]; const finalText = text ?? seed; return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"> <rect width="100%" height="100%" fill="${palette.bg}"/> <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="system-ui, sans-serif" font-size="${Math.floor(width / 6)}" fill="${palette.fg}">${finalText}</text> </svg>`; }

实际实现会多一些细节，比如文字超长时的截断、特殊字符转义、自定义颜色覆盖等，但骨架就是这个。用 seed 而不是随机数，是为了保证同一个 seed 永远生成同一张图，这样在列表页、详情页引用同一个用户时，头像是一致的，不会刷一次页面换一个颜色。

2.3 从“个人工具”到“开源插件”做的三件事

早期的 ponytail 只是项目里一个 util 函数，慢慢用着用着觉得不错，就想着独立出来，做成一个可以给更多人用的插件。这个过程中我做了三件事，这也是后来大家在 README 里看到的能力。

第一，提供命令行入口，方便用来批量生成文件。第二，提供编程接口，让开发者在 Node.js 脚本里动态生成占位图存入变量或直接写入磁盘。第三，针对 Vite 做了插件封装，把 ponytail 暴露成一个虚拟模块，这样构建时按需加载，页面里可以直接 import 一张占位图，不需要手动保存文件。

3. 插件 ponytail 如何使用：安装与三种典型用法

3.1 快速安装

ponytail 是一个开发期依赖，装到 devDependencies 里就好，生产打包完全不会存在。安装命令和其他 npm 包没有区别：

npm install -D ponytail # 或者用 pnpm pnpm add -D ponytail

由于核心实现是 SVG 字符串拼接，安装后不会引入任何二进制依赖，包体积很小，我实测下来在 pnpm 环境下几乎瞬间完成。

3.2 用法一：命令行批量生成

如果我只是想要一批现成的头像文件放到 public 目录，用 CLI 是最省事的。比如生成一张 400x400 的占位图：

ponytail --width 400 --height 400 --text "ZY" --seed user-001 --out ./public/avatars

执行后，会在 ./public/avatars 下生成一个类似 user-001-400x400.svg 的文件。需要注意 text 参数如果包含空格，建议用引号包起来，否则会被 shell 拆成两个参数。文本内容我建议用纯英文或拼音，后面踩坑部分会说为什么。

3.3 用法二：在 Node 脚本里调用 JS API

有时候我不想生成实体文件，只希望在页面渲染时动态拿到一个 data URL，就可以直接调用 JS API：

import { generateDataUrl } from 'ponytail'; const url = generateDataUrl({ width: 80, height: 80, seed: 'zhang3', text: '张三' }); console.log(url); // data:image/svg+xml;utf8,... // 然后塞进一个 <img src={url}> 即可

这个方式很适合组件库的默认头像。用户没有上传头像时，前端根据用户 ID 生成一个有颜色区分度的 SVG data URL 作为兜底，比所有用户共用一张灰色剪影要直观得多。

3.4 用法三：在 Vite 项目里当插件用

第三种用法是这篇文章标题里提到的“ponytail 插件”的真正含义。在 Vite 项目中，把它加到插件列表里：

// vite.config.ts import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; import ponytail from 'ponytail/vite'; export default defineConfig({ plugins: [ vue(), ponytail({ prefix: '/mock-assets', dir: './public/mock', }), ], });

配置好之后，组件里可以直接通过虚拟模块导入占位图：

import avatar from 'virtual:ponytail/160x160?seed=zhang3';

Vite 插件做的事情是拦截 /mock-assets 前缀的请求，实时生成 SVG 并返回，省掉了预先批量生成文件的步骤。做组件库 or 中后台项目时，我尤其推荐这种方案，页面里那些“用户头像”“商品主图”在没接入真实接口前都指向这个虚拟模块，后面接真实数据时只要把 import 语句删掉即可，改动非常小。

3.5 参数速查表

不管用哪种方式，核心参数都是下面这些：

{ "scripts": { "generate:mock": "ponytail --width 200 --height 200 --seed demo --out ./public/mock", "predev": "npm run generate:mock", "dev": "vite" } }