如何检测React页面完成Hydration？Chrome扩展脚本适配问题

核心思路：监听React Hydration相关信号 #

React的Hydration过程会产生可观测的DOM行为，以下是几种可靠的检测方案：

1. DOM突变监听+React根元素标记 #

React根容器通常带有特定属性标记（比如data-react-root，不同版本可能略有差异），结合MutationObserver监听根元素的变化，当连续短时间内无DOM更新时，判定Hydration完成：

function waitForHydrationComplete(rootSelector = '[data-react-root]') {
  return new Promise((resolve) => {
    const root = document.querySelector(rootSelector);
    if (!root) {
      // 先等待根元素出现
      const rootObserver = new MutationObserver((mutations) => {
        const foundRoot = document.querySelector(rootSelector);
        if (foundRoot) {
          rootObserver.disconnect();
          watchRootChanges(foundRoot, resolve);
        }
      });
      rootObserver.observe(document.body, { childList: true, subtree: true });
      return;
    }
    watchRootChanges(root, resolve);
  });
}

function watchRootChanges(root, resolve) {
  let idleTimeout;
  const changeObserver = new MutationObserver(() => {
    clearTimeout(idleTimeout);
    // 短超时确保最后一次Hydration操作完成
    idleTimeout = setTimeout(() => {
      changeObserver.disconnect();
      resolve();
    }, 100);
  });
  changeObserver.observe(root, { childList: true, subtree: true });
}

// 使用示例
waitForHydrationComplete().then(() => {
  // 在这里执行DOM修改操作
  console.log('Hydration完成，可安全修改页面');
});

该方案不依赖React内部API，兼容性强，适用于绝大多数React版本。

2. React 18+ 内部事件监听（补充方案） #

如果目标页面使用React 18+，可监听非官方但实用的react-hydration事件，注意该方式依赖内部实现，未来可能变动：

function waitForHydration() {
  return new Promise((resolve) => {
    if (document.querySelector('script[src*="react"]')) {
      document.addEventListener('react-hydration', resolve, { once: true });
    } else {
      // 回退到DOM监听方案
      waitForHydrationComplete().then(resolve);
    }
  });
}

3. 自定义元素访问问题说明 #

你遇到的customElements未定义问题，是因为Chrome扩展内容脚本运行在隔离世界，无法直接访问页面上下文的API。需通过注入页面脚本的方式实现：

// 内容脚本中注入页面脚本
const pageScript = document.createElement('script');
pageScript.textContent = `
  customElements.whenDefined('target-element').then(() => {
    window.postMessage({ type: 'HYDRATION_FINISHED' }, '*');
  });
`;
document.head.appendChild(pageScript);

// 内容脚本监听页面消息
window.addEventListener('message', (event) => {
  if (event.data.type === 'HYDRATION_FINISHED') {
    // 执行你的DOM修改逻辑
  }
});

总结 #

优先选择DOM突变监听+根元素标记方案，稳定性最高；若需访问页面上下文API，必须通过注入页面脚本突破隔离世界限制。

内容的提问来源于stack exchange，提问作者amkhrjee