driver.js 周下载破百万，这次刷新改了什么

有些开源库属于"装上就忘了"的那种：你不会天天想起它，但它默默支撑着大量网站的新手引导与功能高亮。driver.js 就是这种库。它是 Web 上最流行的用户引导库之一，作者同时也是开发者学习路线图网站 roadmap.sh 的创始人。不久前，作者宣布 driver.js 的 npm 周下载量突破 100 万，并决定给这个老库做一次刷新（refresh）。本文结合仓库源码与 npm 公开数据，讲清楚三件事：driver.js 是什么，这次刷新改了什么，以及它凭什么能走到百万周下载。

一、driver.js 是什么：页面上的一盏聚光灯

做 Web 产品，十有八九会遇到这些需求：

新手引导：用户第一次进来，一步步带他认识界面，比如"这是搜索框""这里是设置"；
功能高亮：把某个按钮或区域突出出来，吸引用户注意；
焦点转移：把用户的注意力从 A 处引到 B 处；
遮罩聚焦：类似"关灯看视频"的效果，暗化背景，只留一处明亮；
上下文帮助：填表单时弹出带遮罩的提示气泡。

driver.js 干的就是这些事。它的核心能力是在页面上画一盏"聚光灯"：高亮你指定的元素，暗化其余部分，再配一个气泡提示（popover），并把多步串成分步教程（tour）。

readme 里有一句话值得注意："它不只是个 tour 库，tour 只是众多用例之一。"任何需要"页面遮罩加元素聚焦"的场景，它都能派上用场。

它的核心卖点可以概括为：零依赖（纯 vanilla TypeScript，不依赖 jQuery、React 或任何运行时库）、极轻（gzip 后约 5kb，同类库普遍 12kb 以上）、全键盘可控（无障碍友好）、API 与生命周期钩子丰富、跨浏览器表现一致、MIT 协议商用免费。

二、100 万周下载是什么量级

周下载量（weekly downloads）是 npm 生态里衡量包影响力的硬指标。100 万每周，意味着平均每天 14 万次安装，背后是几十万甚至上百万个项目。

放到同行里看更直观。截至 2026 年 10 月初，npm 官方接口显示 driver.js 最近一周下载约 270 万次；同期老牌引导库 intro.js 约 22 万次，shepherd.js 约 40 万次，React 生态的 react-joyride 约 170 万次。作为参照，React 的周下载在亿级，Vue 约 2000 万。在"用户引导"这个细分赛道里，driver.js 已经是断层领先的那一个。

更有意思的是作者分享过的成长曲线：driver.js 曾在 2 万周下载附近徘徊了三年多，然后一路涨到百万。期间没有大重构，也没有营销投放，靠的是产品力和口碑。而突破百万之后选择做刷新，不是因为库坏了，而是里程碑值得庆祝，有些技术债也该还了。

三、刷新改了什么：仓库迁移与架构现代化

以 v1.6.0 的仓库快照为准，这次刷新主要有四块内容。

1. 仓库迁移，npm 包名不变

最显眼的变化是仓库从 kamranahmedse/driver.js 迁到了 nilbuild/driver.js，与作者统一个人品牌与开源组织的动作一致。注意两点：旧的仓库地址仍然有效，历史 star 与 issue 都还在；npm 包名保持 driver.js 不变，依赖它的项目什么都不用改，用户侧零感知。

2. TypeScript 重写，模块化架构

src/ 目录非常干净，10 个 TypeScript 文件加 1 个样式文件，各司其职：

driver.js 的 src 目录：10 个 TypeScript 文件各司其职

文件	职责
driver.ts	主入口，编排一切
overlay.ts	页面遮罩，暗化背景
highlight.ts	元素高亮，聚光灯效果
popover.ts	气泡提示框
position.ts	定位计算，让气泡跟随元素且不溢出屏幕
events.ts	键盘与用户事件处理
emitter.ts	事件发射器，支撑生命周期钩子
state.ts	状态管理，维护 tour 进度
config.ts	配置定义与合并
utils.ts	工具函数
driver.css	遮罩与气泡的默认样式

每个文件一个职责，符合单一职责原则。这种清晰度让日常维护和外部贡献都更容易。

3. 现代化的工具链

package.json 的 devDependencies 基本就是一份 2026 年的"现代 JS 库标配"：测试用 Vitest，配 jsdom 与覆盖率插件；构建用 Vite；类型系统是 TypeScript；发版用 release-it 自动化；还有 @arethetypeswrong/cli 和 @microsoft/api-extractor 把关类型导出与 API 面，防止使用者踩 TS 类型的坑；外加 publint 做包规范检查。

4. Playground 驱动开发

readme 特别提到，playground 是一个 Astro 应用，直接从 src/ 源码导入，改动即刻热重载。每个示例是 playground/src/examples/ 下的一个文件，按 highlight、popover、tour、api 分组，新增示例会自动出现在侧边栏。改一行高亮逻辑，马上就能在浏览器里看到效果。这种"源码即 demo"的开发体验，是如今主流开源库的标配。

四、约 5kb 的 gzip 是怎么做到的

体积是 driver.js 最硬的卖点之一。readme 给出的对比口径是：driver.js gzip 后约 5kb，同类库普遍 12kb 以上。能做到这么小，原因有四个：

零依赖：不引入任何运行时库，没有 lodash，也没有框架适配器；
vanilla 实现：直接操作 DOM，不经过虚拟 DOM 或框架抽象；
单一职责：只做"高亮加引导"，不做动画引擎，也不做模态框系统；
ESM 导出：对 tree-shaking 友好，用不到的能力会被打包工具剔除。

5kb 是什么概念？一张压缩过的 JPEG 缩略图都比它大。对一个要在用户浏览器里跑的库来说，越小意味着加载越快、解析越快、执行越快，对移动端和弱网用户尤其重要。

五、典型用法：两段代码就够

高亮单个元素：

import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver();
driverObj.highlight({
  element: "#my-button",
  popover: {
    title: "点这里开始",
    description: "这是新手第一步"
  }
});

创建分步教程：

const driverObj = driver({
  showProgress: true,
  steps: [
    { element: "#search", popover: { title: "搜索", description: "在这里找任何东西" } },
    { element: "#profile", popover: { title: "个人中心", description: "管理你的账号" } },
    { element: "#settings", popover: { title: "设置", description: "调整偏好" } }
  ]
});

driverObj.drive();  // 开始教程

driver.js 分步引导的用法与执行链路

就这么几行代码，一个完整的新手引导就有了。门槛极低，能力又够用，这正是它能普及到百万下载的原因。

六、和同类库的对比

下表中的下载量为 2026 年 10 月初 npm 官方接口的实测数据：

对比项	driver.js	intro.js	shepherd.js	react-joyride
运行时依赖	零	零	依赖定位库	依赖 React
框架绑定	无	无	无	仅 React
原生 TypeScript	是	否	是	是
gzip 体积	约 5kb	12kb 以上	12kb 以上	12kb 以上
最近一周下载	约 270 万	约 22 万	约 40 万	约 170 万

在"体积、零依赖、原生 TS"三项上，driver.js 全面领先；同为框架无关的引导库，它的周下载已是 intro.js 的十倍以上。即便算上 React 专用的 react-joyride，driver.js 也高出一截，而且不受框架约束。

七、谁适合用，怎么上手

适合你，如果：你在做 Web 产品，需要新手引导、功能高亮或分步教程；你在意包体积，尤其是移动端和性能敏感场景；你不想被某个框架绑死，driver.js 在 React、Vue、Angular 和原生 JS 里都能用；你需要键盘可控的无障碍支持。

上手三步：

bash

npm install driver.js

import { driver } from "driver.js";
import "driver.js/dist/driver.css";

const driverObj = driver({
  showProgress: true,
  steps: [ /* 你的步骤 */ ]
});
driverObj.drive();

完整文档和在线 demo 在 driverjs.com。

八、从 2 万到 100 万：一个老库的维护节奏

这次刷新最值得琢磨的，不是具体改了哪行代码，而是它背后的老库维护哲学。

第一，不为改而改。在 2 万周下载徘徊的三年里，作者没有推倒重来博眼球，而是等它自己长起来。好产品不需要频繁改版来证明存在感。

第二，该还的债要还。百万下载意味着用户基数足够大，技术债的影响被放大，此时做类型重写、工具链升级和仓库整理是顺势而为，不是瞎折腾。

第三，包名稳定是底线。仓库地址可以迁，npm 包名不能动，用户侧零感知是最重要的兼容性承诺。

第四，模块化是长期可维护的基础。10 个各司其职的 TS 文件，让任何一个新贡献者都能快速定位代码，这是百万下载量级的库还能持续维护的根本。

顺带一提，driver.js 的作者同时维护着 roadmap.sh，后者是最受欢迎的开发者学习路线图网站之一。他的项目有个共同点：问题清晰，解法克制。把一个简单的东西做到极致，比堆一堆复杂的功能更有长期价值。

九、小结

driver.js 是 Web 上最流行的用户引导库之一：零依赖，gzip 约 5kb，周下载百万级。这次刷新做了仓库迁移、TypeScript 重写和工具链现代化，但 npm 包名不变，用户无感知。从 2 万到 100 万的曲线说明，把"高亮元素加引导用户"这件简单的事做到极致，时间会给你回报。

任何 Web 产品在上线新功能时，无论是截图标注类工具、AI 应用还是后台系统，都可以用 driver.js 做最轻量的功能引导层。5kb 换一套完整的引导系统，这笔账很划算。

本文基于作者发布的里程碑动态与 driver.js 仓库（github.com/nilbuild/driver.js，v1.6.0）整理，下载数据取自 npm 官方接口 2026 年 10 月初的一周统计。MIT 协议，文档与 demo 见 driverjs.com。

字节笔记本