安装与样式引入

Driver.js 可以通过包管理器安装，也可以直接用 CDN。现代前端项目建议使用 npm 包，因为这样更方便参与构建、类型提示和版本管理。

使用包管理器安装

根据项目使用的包管理器选择一个命令即可：

bash

npm install driver.js

bash

pnpm add driver.js

bash

yarn add driver.js

安装后，在入口文件或具体页面模块中导入：

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

driver 是创建实例的函数，driver.css 是默认样式。没有引入 CSS 时，遮罩、弹层和按钮可能无法正确显示。

在 HTML 中使用 CDN

如果只是做静态页面示例，可以直接引入 CDN 文件：

html

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@latest/dist/driver.css">
<script src="https://cdn.jsdelivr.net/npm/driver.js@latest/dist/driver.js.iife.js"></script>

<button id="start-tour">开始引导</button>
<button id="create-project">创建项目</button>

<script>
  const driverObj = window.driver.js.driver();

  document.querySelector("#start-tour").addEventListener("click", () => {
    driverObj.highlight({
      element: "#create-project",
      popover: {
        title: "创建项目",
        description: "点击这里创建你的第一个项目。",
      },
    });
  });
</script>

生产项目中不建议长期使用 @latest，因为它会跟随最新版本变化。上线项目应固定版本号，便于排查和回滚。

检查是否安装成功

可以先写一个最小按钮验证：

html

<button id="help-button">帮助</button>

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

const driverObj = driver();

document.querySelector("#help-button").addEventListener("click", () => {
  driverObj.highlight({
    element: "#help-button",
    popover: {
      title: "帮助按钮",
      description: "这个按钮用于打开当前页面的帮助信息。",
    },
  });
});

如果点击后出现遮罩、高亮框和说明弹层，说明安装和样式引入都正常。

常见安装问题

问题	原因	处理方式
弹层没有样式	忘记引入 `driver.css`	在入口或组件中导入 CSS
构建时报找不到包	依赖没有安装到当前项目	确认 `package.json` 和锁文件，重新安装依赖
CDN 示例无法运行	脚本加载失败或全局对象写错	检查网络请求，使用 `window.driver.js.driver()`
页面没有高亮目标	选择器没有匹配元素	确认元素已经渲染，并检查选择器拼写

版本确认

本教程以 Driver.js 1.x API 为主。需要确认当前安装版本时，可以运行：

bash

npm view driver.js version

项目中已安装的版本可以查看：

bash

npm list driver.js