🧩 fix(core): 增强字幕自动开启的健壮性与配置化
本次重构将原有脆弱的一次性检测逻辑升级为基于 MutationObserver 的渐进式检测机制,
并引入完整的重试策略与集中式配置管理。目标是彻底解决因播放器动态加载导致的字幕开启
失败问题,提升脚本在不同网络环境和页面加载速度下的可靠性。
🧩 实现细节与架构决策:
- 🔄 采用
MutationObserver 监听播放器加载状态:
- 👁️ 实现主动监听替代被动等待,当播放器容器 (
".bpx-player-video-wrap")
出现在 DOM 中时立即触发检测逻辑,完美适配 B 站的动态加载特性。
- 🛡️ 引入执行锁 (
isTryingToEnableSubtitle) 防止在重试间隔内因多次触发
play 事件而导致的重复执行和资源竞争。
- ⚙️ 构建可配置的重试策略与参数中心:
- 📦 将所有魔法数字提炼为
CONFIG 对象,包括最大重试次数、重试间隔和调试开关,
使行为调优无需修改代码逻辑。
- 📈 实现线性递增的重试延迟,每次重试间隔随次数增加而延长,平衡了响应速度与
服务器压力,提高在弱网环境下的成功率。
⚠️ 风险、影响与预案:
- 🔄 检测逻辑的底层变更:
- 🔍 事实变更: 脚本启动逻辑从直接绑定事件改为先监听 DOM 变化。对用户而言,
开启字幕的时机可能更精准,但原理已完全不同。
- 💻 下游影响: 无破坏性变更,所有改进均向后兼容,用户无需任何操作即可享受
更稳定的体验。
🚀 主要收益:
- 🎯 显著提升脚本健壮性与用户体验:
- 💪 从根本上消除了因播放器加载延迟导致的字幕开启失败,用户不再需要手动刷新
或等待二次播放。
- 🔧 配置化的参数管理为未来功能扩展和问题调试提供了极大便利,降低了维护成本。
"Simplicity is the ultimate sophistication."
- Leonardo da Vinci