JSDOM 26.0.0 版本中 CSS 选择器对包含冒号ID的兼容性问题分析

问题背景

在 JSDOM 26.0.0 版本升级后，用户反馈在使用 React Aria 等现代前端库时，遇到了 CSS 选择器语法错误。典型错误表现为当元素 ID 包含冒号（如 id="react-aria-:r6:"）时，查询 button#react-aria-:r6: svg 会抛出 SyntaxError，而该选择器在 25.0.1 版本中可正常工作。

技术原理

选择器规范要求

根据 W3C CSS 选择器规范，ID 选择器中若包含特殊字符（如冒号），需要进行 CSS 转义。例如：

• 原始ID：:r3:
• 合法选择器应写作：#\:r3\:

JSDOM 26.0.0 的变化

新版本加强了对选择器合法性的校验，这与浏览器行为保持一致。问题核心在于：

1. React Aria 等库生成的动态ID包含未转义的冒号
2. 当通过 :scope 伪类派生选择器时，JSDOM 内部未自动处理转义

影响范围

主要影响场景：

1. 使用 React Aria/AriaKit 等生成动态ID的组件库
2. 涉及 :scope 伪类选择器的测试用例
3. 通过 Testing Library 等工具链执行的用户交互模拟

解决方案

临时解决方案

可通过覆盖原生查询方法实现自动转义：

const escapeColonId = (selector) => 
  selector.replace(/#:([^:]+):/g, '#\\:$1\\:');

Element.prototype.querySelector = function(selector) {
  try {
    return originalQuerySelector.call(this, selector);
  } catch (e) {
    if (e.message.includes("not a valid selector")) {
      return originalQuerySelector.call(this, escapeColonId(selector));
    }
    throw e;
  }
};

长期建议

1. 组件库层面：建议 React Aria 等库生成符合CSS规范的ID
2. 测试代码层面：
   • 优先使用 data-testid 属性选择器
   • 避免直接使用含特殊字符的ID选择器

版本兼容性说明

该变化属于对Web标准的合规性改进，虽然导致部分现有代码需要调整，但有助于：

1. 保持与浏览器行为的一致性
2. 提前暴露潜在的选择器规范问题
3. 提升测试代码的健壮性

建议开发者在测试套件中增加选择器合法性检查，这类问题通常在持续集成阶段即可被发现。对于复杂的动态ID场景，建议采用专门的测试选择器策略，而非依赖实现细节的DOM结构。