# 安装与样式引入

URL: https://caijiao.org/driver-js/01-intro/02-installation
Source: docs/driver-js/01-intro/02-installation.md
Description: 讲解如何通过 npm、pnpm、yarn 或 CDN 安装 Driver.js，并说明默认 CSS、模块导入和本地页面测试方式。

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

## 使用包管理器安装

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

```bash
npm install driver.js
```

```bash
pnpm add driver.js
```

```bash
yarn add driver.js
```

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

```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>
```

```js
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
```