driver.js 按钮定位失败主因是节点未挂载，需在 mounted/useeffect 中初始化、用字符串选择器、加稳定 class；高亮异常需调优 z-index 和 pointer-events；移动端需检查 viewport、scrolltoelement 和 touch-action；单步操作需手动管理按钮激活态并及时清理。
目标按钮找不到或高亮错位
Driver.js 启动时提示 Cannot find element，大概率不是选择器写错了，而是按钮还没挂载到 DOM。尤其在 Vue/React 中，#submit-btn 这类 ID 选择器若出现在条件渲染区块（比如 v-if="showForm"），driver.start() 执行时该节点可能根本不存在。
解决方法很简单：
- 用字符串选择器（如
'#submit-btn'），别传document.querySelector('#submit-btn')返回的节点 - 确保在组件 mounted 或
useEffect(() => {}, [])中初始化 driver，而不是在全局 script 标签里直接 new - 给按钮加稳定 class，比如
class="js-onboard-submit"，比依赖动态 ID 更可靠 - 如果按钮初始是
display: none或被overflow: hidden父容器裁剪，Driver.js 仍会尝试定位——但高亮框会偏移或消失，控制台却不报错
高亮后点击无响应或按钮被遮挡
常见现象是：高亮框显示正常，但点“下一步”没反应；或者点了按钮却触发不了绑定事件。本质是遮罩层和高亮层的层级、事件捕获逻辑没理清。
关键配置项必须显式设置：
- 遮罩层需设
pointer-events: none，否则会拦截所有底层点击（移动端尤其明显） - 高亮框（即抠图区域）z-index 至少要比遮罩层高一级，推荐
z-index: 10000 - 按钮本身不要设
z-index，否则容易被遮罩压住；如有必要，提升其父容器层级或临时加isolation: isolate - 若按钮在 Modal 或 Portal 中，检查其父容器是否设置了
pointer-events: none或transform，这会导致事件穿透失效
移动端触摸失灵或高亮偏移
iOS Safari 和部分 Android WebView 下，高亮框常出现位置漂移、touch 事件不触发，根源不在 Driver.js 本身，而在页面基础环境。
必须检查并修正以下三点：
-
<meta name="viewport" content="width=device-width, initial-scale=1">是否存在且未被覆盖 - 初始化 driver 时显式关闭滚动行为：
scrollToElement: false，避免scrollIntoView在 iOS 上引发布局抖动 - 排查祖先元素是否设置了
touch-action: none—— 只要任一父级有它，整个区域的 touch 就会被禁用，临时改为touch-action: auto即可验证
单步中按钮需保持高亮态直到用户操作
Driver.js 默认只做“视觉聚焦”，不接管按钮状态。如果引导要求用户点击该按钮才算完成当前步（比如“点击【开始】进入主界面”），不能只靠高亮，还得同步管理按钮的激活态。
典型做法是监听步骤进入和退出：
- 在
onHighlighted回调里给按钮加class="is-guided-active" - 在
onDeselected或onReset里移除该 class - 配合 CSS 实现持久高亮：
.is-guided-active { box-shadow: 0 0 0 3px #4d90fe; } - 注意：不要在
popover的title或description里直接写onclick行内脚本，XSS 风险高，也难维护
真正容易被忽略的是：Driver.js 不感知组件生命周期。按钮被销毁（比如路由跳转卸载组件）后，若没调用 driver.reset()，残留的事件监听或 class 可能导致后续异常。每次离开引导上下文，都得手动清理。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
