机缘巧合，我在整理开源项目收藏夹的时候又翻到了 Caveman 这个库。第一次看到它时，我就被这个另类的数据可视化思路吸引了：一个图表库，不画折线也不画柱状，而是把所有数据映射成一群手持棍棒的洞穴人，数值越高，人画得越大。这个点子乍看像恶搞，细看却有一套严谨的视觉编码逻辑。前阵子我正好把一个内部运营报表改成了 Caveman 风格，分享给团队之后反响意外地好，今天就以我这次的实操过程为主线，把 Caveman 的用法、原理以及坑位完整梳理一遍。
Caveman 适合谁？如果你做数据报表已经做到审美疲劳，想在周报、数据大屏或者活动页里放一张一眼就能记住的图；如果你想在小团队里快速把某个指标“画出”故事感，又不想引入 D3 那样重的工程依赖；或者你只是想在技术分享会上给大家留个印象——那 Caveman 是一张性价比极高的牌。下文所有代码示例，都基于我在项目中实际跑通的版本和封装方式，你可以直接抄作业，也可以按自己的数据口径改造。
1. 先说清楚：Caveman 到底是个什么东西
1.1 它解决的痛点
日常开发里，图表库的选择一般围绕 ECharts、Chart.js、D3 这三类打转。它们覆盖面广、社区成熟，但也正因为太成熟，产出图表的气质高度统一：平滑的曲线、渐变色的柱状图、悬浮提示框。这些东西放在严肃的数据分析报告里没问题，放在需要传播、需要让人停下来的场景里，就差点意思。
Caveman 解决的是“数据传达的注意力问题”。它把每个数据点画成一个洞穴壁画风格的小人，人的体型、位置、数量都能编码数据。读者不需要看坐标轴也能瞬间理解“谁大谁小、谁多谁少”，这种粗糙、原始、甚至有点笨拙的视觉语言，反而在高信息过载的看板里制造出一种反差感，让人愿意多看两眼。
我当时的应用场景是：一个面向运营团队的渠道质量周报。原来用 ECharts 画了一堆条形图，大家看了就忘。换成 Caveman 之后，同一个指标，变成了“一排拿着棍子的小人在墙上排排站”，谁的渠道贡献高，对应的小人就又高又壮。运营同事看完直接截图发到群里，这就是这个库的价值：它让数据具备了某种被传播的气质。
1.2 能用在哪，不能用在哪
Caveman 首先适合轻量级的、叙事性的数据呈现。比如活动战报页、团队 OKR 展示、个人博客的访问统计趣味化展示、内部系统的周边数据大屏。它也适合放在文章或 PPT 里作为插图和配图，视觉冲击力远胜普通截图。
但要说清楚的是，它不是一个严肃的数据分析工具。坐标轴、网格线、精确的数值标注，这些传统图表的基本配置在 Caveman 里都很弱。如果老板要看精确到小数点的转化率，或者你需要做严格的趋势回归分析，老老实实去用 ECharts，别把 Caveman 硬套进不合适的位置。它的定位更接近“数据涂鸦”，而不是“数据制图”。
1.3 和主流图表库的对比
我在选型的时候做了个小对比，整理如下：
| 对比维度 | Caveman | ECharts | D3.js |
|---|---|---|---|
| 视觉风格 | 洞穴壁画、涂鸦风、识别度极高 | 现代商务风，标准化程度高 | 完全自由，但需要自己实现一切 |
| 上手成本 | 很低，一个核心方法就能出图 | 中等，配置项丰富但文档齐全 | 高，学习曲线陡峭 |
| 定制能力 | 中等，适合配色与基础形状微调 | 很强，但配置复杂度同步上升 | 极强，理论上能画任何图形 |
| 适合场景 | 趣味看板、传播页、内部展示 | 标准报表、管理后台、大屏 | 复杂定制可视化、科研绘图 |
| 体积与依赖 | 轻量，无复杂依赖 | 较大 | 核心库较大，模块化使用稍好些 |
这个小表格让你看明白：Caveman 不是要和谁竞争，它是在主流方案之外提供了一个独特的风格选项。
2. 上手做一张洞穴壁画：最小可运行示例
2.1 环境准备与引入方式
Caveman 的引入方式有两种，我做项目时用的是 script 标签直接引入，因为它不需要构建步骤，对后端模板项目尤其友好。把下载好的 caveman.js 放进静态目录，在页面底部引入即可：
<script src="/js/caveman.js"></script>如果你用的是前端工程化项目，也可以通过打包器引入，但需要注意排查模块导出的兼容性。就我的经验，直接挂到 window 上是最稳的，后面封装用起来也顺手。
2.2 初始化图表与数据结构
Caveman 的核心思想是把你准备好的数据“映射”成壁画。在跑通最小示例之前，先理解它喜欢什么样的数据结构。我实际使用的简化结构是这样的：
var data = { labels: ["直接访问", "搜索跳转", "外链点击"], values: [320, 210, 88] };labels 是每个洞穴人的名字，values 是每个名字对应的数值。这个结构够简单、够直白，不需要像 D3 那样先把数据绑定到 DOM 再慢慢推导比例尺。
初始化也很简单：
var chart = new Caveman({ container: document.getElementById("chart"), data: data, width: 800, height: 320 }); chart.render();跑起来之后，页面上会出现一个浅色纹理的背景，上面站着一排洞穴人。体型根据 values 自动缩放。整个画面不需要你手动设置坐标轴范围，Caveman 内部已经把数据归一化处理好了。第一次看到这张图的时候，我愣了几秒，然后笑了出来。这个反应本身就说明它成功了。
2.3 options 核心参数逐项解读
在你开始改样式之前，先把高频参数吃透。我把项目里经常用到的配置项整理成一张速查表：
| 参数名 | 作用 | 我的建议 |
|---|---|---|
| container | 图表挂载的 DOM 容器 | 只传 DOM 元素，不要传选择器字符串 |
| data | 包含 labels 和 values 的数据对象 | 单组数据最省心，多组数据需要改造 |
| width / height | 画布整体尺寸 | 按容器实际宽度计算，别写死 |
| background | 背景色或背景纹理 | 默认仿岩石纹理，可以改成纯色 |
| padding | 画布内边距 | 值太小洞穴人容易贴边 |
| animationSpeed | 入场动画速度 | 建议适中，太快会丢失仪式感 |
| showTooltip | 是否展示悬浮提示 | 作展示用途时开启，默认关闭 |
| colors | 自定义洞穴人和装饰的颜色 | 可以配合品牌色做统一 |
这些配置看着简单，但每一项直接影响成图气质。我尤其建议你在 colors 和 background 上花一点时间，因为默认的棕黄色调虽然地道，但不一定适配你页面的整体视觉风格。
3. 画面背后：Caveman 的绘制原理拆解
3.1 数据到形体的映射逻辑
Caveman 看起来是个玩乐派库，核心算法却很实在。它把数值映射大致分为三步：归一化、对数压缩、绘图坐标换算。
归一化很好理解，把所有数值线性压到 0 到 1 之间的百分比，这一步保证整个画布里的大只不大于天际、小只不小于芝麻。但我实际测试后发现，如果你的数据里有极端值，比如一个是 5，一个是 10000，线性归一化会导致 5 对应的小人几乎看不见。这时候 Caveman 内部会启动对数压缩逻辑，拉开小数值之间的视觉差距，同时避免大数值撑爆画布。
做完归一化之后，它把每个值映射成洞穴人的“体块大小”。在坐标系里，每个穴居人底部中心点对齐在横向等距的位置上，高度则由体块倍数决定。这个映射逻辑让我想起小时候玩的《帝国时代》，村民采集资源的数量会改变角色动画里携带物资的视觉重量。Caveman 做的是同样的事：用一个抽象的、可感知的视觉锚点去编码数字。
3.2 canvas 绘制与动画的实现方式
Caveman 底层是基于 Canvas 绘制的。这就意味着它本质上是在一块画布上不断重新绘制图形，而不是像 DOM 图表那样靠多个元素堆叠。
具体绘制过程是这样的：第一次 render 时，Caveman 会清空画布，画上岩石纹理背景；接着逐个绘制洞穴人的身体、头、武器和阴影。每个洞穴人其实是由若干圆形、椭圆和线条组合出来的，所谓“人”，并不是图片素材，而是程序化生成的一组矢量图形。
动画则依赖 requestAnimationFrame 实现。每一帧都会根据当前动画进度重新计算洞穴人的身高和位置，从而形成从地面“长出来”的效果。我后来扒了一下源码，发现这个动画循环写得相当克制，并没有复杂的缓动库。它靠的是一个简单的插值函数，把起始高度和最终高度平滑过渡。明白了这一点，你就知道为什么把 animationSpeed 调到很高时会看着很突兀——因为它根本没有做花哨的回弹效果，调太高了反而削弱了动画的叙事感。
3.3 二次封装：给洞穴人加上颜色和文字标签
原版 Cavean 的展示信息比较克制，只有悬浮提示能看到具体数值。我在实际项目里的做法是封装了一层，让每个洞穴人脚下显示名称、头顶显示数值，这样截图传播时信息才完整。
我采用了这样的思路：在 caveman.render() 完成后，往容器里叠加一个透明定位的 HTML 覆盖层。覆盖层里根据坐标插入一排 span 标签。坐标计算可以通过回顾内部映射逻辑手动推算：
var chart = new Caveman({ ... }); chart.render(); var itemWidth = chart.width / chart.data.labels.length; chart.data.labels.forEach(function (label, index) { var labelEl = document.createElement("span"); labelEl.innerText = label; labelEl.style.position = "absolute"; labelEl.style.left = index * itemWidth + itemWidth / 2 + "px"; labelEl.style.transform = "translateX(-50%)"; chart.container.appendChild(labelEl); });这里的关键是让 HTML 覆盖层定位基于同一个容器，而不是页面全局坐标。我最初直接按页面坐标系计算，滚动后全部错位，后来改用容器作为偏移基准就解决了。这个封装能让图表在周报截图里信息自洽，不需要额外配文字说明。
4. 实战：把一个真实业务指标做成洞穴壁画
4.1 需求与数据准备
我这次实战的背景是为团队做一个“渠道质量周报”。原始数据来自后端接口，返回的是一个 JSON 数组，里面包含渠道名、曝光量、点击量、转化率等字段。需求很朴素：一眼看出哪个渠道整体贡献最高。
为了方便 Caveman 使用，我先把接口数据转换成了它需要的 labels + values 结构。这里我选择用“加权贡献分”作为 values，而不是单一曝光量。计算公式很简单：
var channels = [ { name: "小红书", pv: 60000, uv: 3000, order: 45 }, { name: "公众号", pv: 20000, uv: 1800, order: 38 }, { name: "抖音", pv: 90000, uv: 4000, order: 20 } ]; var data = { labels: channels.map(function (c) { return c.name; }), values: channels.map(function (c) { return c.pv * 0.3 + c.uv * 0.5 + c.order * 100; }) };加权逻辑可以根据业务自己定，目的只是让单值能综合表达某个维度。如果你不需要综合维度，直接用原始数值也是一样的效果。
4.2 改造过程：从原生 JSON 到贴合业务的数据格式
真正接业务数据时，你八成会遇到接口字段名不一致的问题。比如后端给你的是 exposure_count，你要的是 labels 里的 channel_name。不要期待 Caveman 帮你做这件事，写一个轻量的数据适配层是最佳实践。
我封装了一个 convert 函数，核心思路是把业务字段名映射成 Caveman 约定字段：
function toCavemanData(rawList, labelField, valueField) { return { labels: rawList.map(function (item) { return item[labelField]; }), values: rawList.map(function (item) { return Number(item[valueField]); }) }; } var cavemanData = toCavemanData(apiData, "channel_name", "weighted_score");这一步看起来多余，但在项目里价值很大。因为 Caveman 的数据结构固定，你不可能为了每种接口形态都去改图表代码。适配层相当于在所有数据源和图表之间加了一个稳定的协议，后端怎么变，你只需改一行字段名映射。
4.3 效果展示与性能表现
改造完成后，页面上渲染了 7 个洞穴人，每个代表一个渠道，体型差异很直观。我关了动画，整图渲染时间实测在 20 毫秒左右。开启入场动画后，页面加载过程会有半秒左右的趣味等待，但不影响滚动页面。
这里有一个经验想分享：如果你的画布尺寸超过 1000 像素宽，建议把洞穴人数量控制在 8 个以内。超过 8 个的时候，横向排列的间距会被压缩，洞穴人之间会产生重叠。尤其是当相邻两个值差距很大时，大个子的手臂和小个子的头部容易“打架”，视觉上显得有些凌乱。不是库的 bug，而是画布内容密度的自然限制。
5. 踩坑记录：动画卡顿、白色背景、中文标签
5.1 常见问题速查表
在实际使用和给同事做技术支持的过程中，我整理了这张问题速查表，基本覆盖了 Caveman 最常见的雷区：
| 问题表现 | 原因分析 | 处理方法 |
|---|---|---|
| 动画卡顿 | 画布尺寸过大且同时渲染数量过多 | 减小画布尺寸，或用配置项关掉动画 |
| 背景泛白无纹理 | 覆盖层或父容器背景色覆盖了 canvas | 检查父级 CSS 背景色，调成透明 |
| 中文标签乱码或缺失 | 字体渲染兼容问题或容器被遮挡 | 在覆盖层样式中显式设置中文字体 |
| 数值为 0 的项不显示 | 0 值归一化后体型为最小 | 可对 0 值做保底偏移 |
| 初始化时报找不到容器 | container 传成了字符串而非 DOM | 改为 document.getElementById |
| 与前端框架配合异常 | 框架虚拟 DOM 在渲染后重建节点 | 在生命周期的最晚阶段初始化 |
我遇到最多的是第一项：设计稿里有个全屏大图看板，Caveman 画布撑到 1920 宽，还渲染了 12 个洞穴人。开启动画后，低端办公笔记本上能明显感觉到绘制延迟。解决办法是砍掉动画、缩小画布，把视觉重心放在洞穴人群像的排列上，而不是动态过程。
5.2 一个值得跨项目复用的小技巧
Caveman 默认的海绵状岩石纹理和圆形小人，在整体视觉里会显得有点“喧宾夺主”。我调整视觉风格的核心技巧是：改 colors 配置和背景，而不要试图去改它内部的人物结构算法——改结构代码意味着你脱离了库的维护线，后续升级很麻烦。
我把默认配色从棕黄色调改成灰蓝色调之后，整个图的气质立刻从“搞笑洞穴”变成了“高级复古插画”。方法很简单，配置 colors 数组时，用灰度+低饱和度颜色替换明快的黄褐色，同时把 background 从纹理改成接近米白的纯色，壁画感保留但不再抢页面焦点。
如果你拿到一套品牌 VI 色板，甚至可以按照品牌色把每个洞穴人的“衣服”颜色映射成不同渠道的分类色，这样的图放在官网首页都不掉价。
5.3 为什么要保留“丑”设计
在开发过程中，产品经理一度希望我把洞穴人做得更精致，比如加上眼睛、嘴巴的动作，或者把棍棒换成更有质感的 3D 模型。我劝住了。
Caveman 的“粗糙感”恰恰是它的记忆点。当画面过于精致的时候，它就和常规图标库没有区别了。数据可视化的首要目标是传达信息，其次才是营造美学体验。洞穴人的粗线条和手绘感，天然传递出一种“来自上古时代的朴素智慧”的心理暗示。用户看到它，不会去纠结细节精度，而是直接对数据对比产生直观印象。这个“丑”，是有设计策略的丑。
6. 我觉得值得单独说的几点经验
6.1 封装成独立组件才能长期使用
如果你准备在正式项目里引入 Caveman，强烈建议第一时间把它封装成独立组件，而不是在每个页面里复制粘贴初始化代码。我封装的组件对外只暴露三个参数：data、width、theme。内部处理好适配层、中文标签覆盖层和自定义配色。这样以后任何页面想用洞穴人图表，只需三行代码。封装成本不高，但长远看能省下大量重复沟通时间。
6.2 约定好 0 值和极端值的表现规则
数据可视化项目里最容易被低估的，是边界数据的处理。Caveman 对 0 值会渲染成很小的形体，不是完全消失。但视觉上它很容易被解读为“这个渠道挂了”。我在封装里加了一个规则：如果 values 中存在 0，就在对应洞穴人脚下画一个小问号图标，同时悬浮提示里明确显示“本期无数据”。这种规则要和业务方提前对齐，否则他们会误把 0 当故障。
6.3 适合和普通图表混合使用
不要觉得用了 Caveman 就得把整个报表全部改成洞穴人风格。我的最终方案是：整体看板继续用 ECharts，只在最核心的“渠道贡献对比”区域放一个 Caveman。混合布局之下，核心区域因为风格独特，反而获得了更高的视觉权重。这种“少数派”打法比全盘洞穴化高级得多。
6.4 没事翻翻源码，收获比想象中大
最后提一句，Caveman 的源码并不复杂，一个晚上就能读完。读它的收获不限于会用这个库，你还能学到一套非常直白的 Canvas 动画封装思路：如何在 requestAnimationFrame 循环里做插值、如何用纯几何图形组合出有辨识度的角色、如何用最少的配置项覆盖最多的场景。这些都是可以迁移到其他可视化项目里的底层能力。我后来自己写轻量图表时，不少动画和坐标换算的灵感都来自它。
如果你手头刚好有一个不要求严肃精度的内部项目，不妨拿 Caveman 试试手。把一个平平无奇的指标变成一面画着原始人的墙，打开页面的那一瞬间，整个会议室的气氛都会不一样。
