ObservableHQ Framework 在 Firefox 117.0.1 中的文档交互失效问题解析

问题现象

近期有用户反馈，在使用 Firefox 117.0.1 浏览器访问 ObservableHQ Framework 项目文档时，页面中的交互元素（如代码块、可视化组件等）会持续显示加载状态，无法正常使用。开发者工具控制台显示以下关键错误信息：

Uncaught DOMException: Document.querySelectorAll: '#observablehq-main h1:not(:first-of-type), #observablehq-main h2:not(h1 + h2):has(a.observablehq-header-anchor)' is not a valid selector

技术背景

这个错误源于 CSS 选择器语法兼容性问题。ObservableHQ Framework 在渲染文档时使用了较新的 CSS :has() 伪类选择器，该选择器允许开发者根据子元素的存在来匹配父元素。例如：

/* 匹配包含特定子元素的h2标题 */
h2:has(a.observablehq-header-anchor)

根本原因

Firefox 浏览器对 :has() 选择器的支持情况如下：

• 从 Firefox 121 版本开始原生支持
• 121 版本之前需要通过实验性标志手动启用
• 117.0.1 版本完全不支持该语法

当框架尝试在不支持该选择器的浏览器中执行 DOM 查询时，就会抛出语法错误，导致后续的交互逻辑无法正常初始化。

解决方案

对于不同用户群体，有以下建议：

1. 终端用户解决方案：

   • 升级 Firefox 到 121 或更高版本
   • 临时切换至 Chrome、Edge 或 Safari 等现代浏览器

2. 开发者注意事项：

   • 在使用新 CSS 特性时，应考虑添加特性检测机制
   • 对于关键功能，应提供优雅降级方案
   • 在文档中明确标注浏览器兼容性要求

3. 框架维护建议：

   • 添加浏览器兼容性检测逻辑
   • 对不支持 :has() 的环境提供替代选择器方案
   • 在错误处理中提供更友好的用户提示

技术启示

这个案例展示了现代 Web 开发中常见的浏览器兼容性挑战。随着 CSS Selectors Level 4 规范的逐步实现，开发者在使用新特性时需要特别注意：

1. 渐进增强原则：确保核心功能在不支持新特性的环境中仍能工作
2. 特性检测：使用 CSS.supports() API 检测选择器支持情况
3. 版本管理：保持对主流浏览器版本支持情况的跟踪

ObservableHQ Framework 团队已注意到这个问题，并在后续版本中进行了优化，建议开发者关注项目更新以获取最佳体验。