遮罩层不能直接用v-if控制显隐，因为v-if会销毁/重建DOM，导致高亮区域定位失效、动画中断及多次getBoundingClientRect计算错误。
遮罩层为什么不能直接用 v-if 控制显隐？
因为 v-if 会销毁/重建 DOM，导致高亮区域定位失效、动画中断、甚至触发多次 getBoundingClientRect 计算——尤其在 ScrollView 或动态列表里，元素位置还没稳定就去取坐标，结果全是 0 或错位。
实操建议：
- 改用 v-show 控制显示，确保 DOM 始终存在
- 首次获取目标元素位置时，加 nextTick 或 setTimeout(..., 0) 等待渲染完成
- 对于异步加载的按钮（比如 tab 切换后才出现的），监听其 ref 的 mounted 或用 MutationObserver 捕获插入
querySelector 选不到目标元素？检查这三处
常见错误现象：控制台没报错，但高亮框始终不出现，或尺寸为 0 —— 八成是选择器没命中。
使用场景：引导步骤配置里写的 selector: '#btn-search'，实际页面可能没 ID，或用了 class 但漏写点号。
实操建议：
- 确保 selector 是唯一可定位的，避免用泛类如 .btn；优先用 id 或带命名空间的 class（如 .user-panel__submit）
- 在 mounted 后手动调用 document.querySelector(selector) 打印验证是否为 null
- 小程序平台需注意：wxml 中的 id 在真机上可能被框架重写，改用 ref + this.$refs.xxx 更可靠
四块遮罩拼接时，为什么边缘有 1px 缝隙或错位？
这是 uni-app 在不同端（尤其是小程序）对 view 盒模型渲染的细微差异导致的：rpx 转 px 时小数截断、border-box 计算偏差、或者父容器未设 overflow: hidden。
性能影响：缝隙本身不卡顿，但若每次 step 都重算四块样式，频繁触发 layout，低端安卓机易掉帧。
实操建议：
- 四块遮罩统一用 position: absolute，top/left/right/bottom 值全部用整数 px（非 rpx），通过 uni.getSystemInfoSync().windowWidth 动态计算
- 高亮区域外层加 overflow: hidden，防止阴影或圆角溢出干扰遮罩边界
- 不要依赖 box-shadow 模拟暗色层，它不参与遮罩逻辑，且 iOS 下常有渲染偏移
localStorage 记录引导状态，为什么有时“又弹了”？
不是代码没存，而是读取时机错了：uni.getStorageSync 在组件 data 初始化前执行，返回 undefined，导致 showGuide = true 被默认赋值。
兼容性影响：H5 端没问题，但微信小程序中，如果用户清过缓存、或用了分包异步加载，getStorageSync 可能返回空字符串而非 null。
实操建议：
- 把状态判断逻辑移到 mounted 或 onLoad 生命周期里，而不是 data() 中直接读
- 判断条件写成 !uni.getStorageSync(stepKey)，别用 == null 或 === undefined
- 若需跨分包记录，改用 uni.setStorageSync + 全局 key 命名规范，例如 guide_home_v2，避免 key 冲突
遮罩的“洞”看起来很准，但用户一滑动或缩放页面，高亮就偏了——这不是 bug，是你没监听 scroll 或 resize。这点在长页面和 iPad 上最容易被忽略。
