driver.js 初始化失败主因是目标元素未就绪，需在 dom 渲染后启动；路由切换需重置并重定义步骤；按钮文案须初始化时配置；移动端需校准 viewport 和 touch-action。
Driver.js 初始化失败：找不到目标元素怎么办
Driver.js 启动时提示 Cannot find element，通常不是脚本没加载，而是目标 DOM 还没就绪。页面用 React/Vue 动态渲染、或 JS 延迟挂载的元素，driver.start() 执行时很可能还没出现在 DOM 中。
- 确保在目标元素已渲染后再初始化 Driver，比如 Vue 的
nextTick、React 的useEffect(() => {}, [])或原生DOMContentLoaded后加延时检测 - 不要用
document.querySelector('#step1')直接传入，改用字符串选择器（如'#step1'），Driver.js 内部会重试查找 - 若目标是动态 ID（如
user-form-123），提前把稳定 class 加到元素上，用'.js-onboard-user-form'更可靠
多步引导中跳转后高亮失效或错位
单页应用路由切换后，Driver.js 默认不自动重绑定，旧步骤的 element 引用可能已失效，导致高亮框漂移或空白。
- 每次路由变化后，调用
driver.reset()清除当前状态 - 新页面加载完成再重新定义步骤，不要复用旧的
steps数组（尤其含闭包引用） - 如果步骤涉及 iframe 或 Shadow DOM 内容，Driver.js 默认不支持，需手动用
scrollIntoView: false+ 自定义position计算坐标
自定义按钮文字和事件绑定不生效
Driver.js 的 doneBtnText、closeBtnText 等配置项只在初始化时读取，后续修改对象属性不会触发 UI 更新；点击“下一步”没反应，常因事件监听被框架拦截或冒泡中断。
- 所有按钮文案必须在构造
driver实例时通过配置传入，例如：new Driver({ doneBtnText: '继续' }) - 自定义按钮回调要用
onNext/onPrevious钩子，别直接给按钮加onclick—— Driver.js 会接管事件流 - 若按钮在 Modal 或 Portal 中，确保其 DOM 父容器未设置
pointer-events: none，否则点击穿透导致无响应
移动端适配下遮罩层盖不住内容或触摸失灵
Driver.js 默认用 position: fixed 和 z-index 控制遮罩，但在 iOS Safari 或某些 Android WebView 中，缩放、viewport 设置或 transform 层级会让高亮区域偏移，且 touch 事件可能被父容器阻止。
- 在
中确保有正确 viewport：<meta name="viewport" content="width=device-width, initial-scale=1"> - 初始化时显式关闭平滑滚动：
scrollToElement: false，避免 iOS 上 scrollIntoView 导致布局抖动 - 如遇触摸无响应，检查是否启用了
touch-action: none的祖先元素，临时移除或设为touch-action: auto
实际集成时最容易被忽略的是 Driver.js 和前端框架的生命周期对齐——它不感知组件挂载/卸载，所有步骤定义、启动、销毁都得由你手动协调。没做 cleanup 的话，路由来回几次后可能残留多个 driver 实例，互相干扰。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
