Astro项目组件hydrate后hCaptcha无法渲染问题求助

问题现象 #

在Astro项目中集成hCaptcha时，刷新页面验证码字段会短暂显示后消失，浏览器控制台出现以下错误：

Warning: Did not expect server HTML to contain a <iframe> in <div>.
Warning: An error occurred during hydration. The server HTML was replaced with client content in <astro-island>.
Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.

移除client:load指令后验证码能渲染，但组件未完成Hydration导致无法正常交互；切换SSG/SSR模式也无改善。

解决方案 #

1. 改用client:only跳过服务器端渲染 #

将组件调用的client:load替换为client:only="react"，让组件完全在客户端渲染，从根源避免服务器与客户端内容不匹配的Hydration错误：

---
import Hcaptcha from "../components/hcaptcha.jsx";
---

<!doctype html>
<html lang="en">
  <head>
  </head>
  <body>
    <Hcaptcha client:only="react" />
  </body>
</html>

2. 手动控制hCaptcha初始化时机 #

修改React组件，通过useEffect监听hCaptcha脚本加载状态，手动调用初始化方法，避免自动渲染导致的时机问题：

import React, { useEffect, useRef } from 'react';

const Hcaptcha = () => {
  const captchaRef = useRef(null);

  useEffect(() => {
    const initCaptcha = () => {
      if (window.hcaptcha && captchaRef.current) {
        window.hcaptcha.render(captchaRef.current, {
          sitekey: import.meta.env.PUBLIC_MY_KEY,
          size: 'normal',
          theme: 'dark',
        });
      }
    };

    // 检查脚本是否已加载，未加载则动态插入
    if (window.hcaptcha) {
      initCaptcha();
    } else {
      const script = document.createElement('script');
      script.src = 'https://js.hcaptcha.com/1/api.js';
      script.async = true;
      script.defer = true;
      script.onload = initCaptcha;
      document.head.appendChild(script);
    }

    // 组件卸载时清理验证码实例
    return () => {
      if (window.hcaptcha) {
        window.hcaptcha.reset(captchaRef.current);
      }
    };
  }, []);

  return (
    <section className="websiteTitle__captcha">
      <div ref={captchaRef} id="signupCaptcha"></div>
    </section>
  );
};

export default Hcaptcha;

问题原因 #

核心问题是Hydration不匹配：服务器端渲染时仅输出空的<div>容器，但客户端加载hCaptcha脚本后会自动插入<iframe>，导致React在Hydration阶段检测到服务器与客户端DOM结构不一致，触发错误并替换整个组件内容，最终表现为验证码短暂显示后消失。

使用client:only指令跳过服务器端渲染，结合手动初始化hCaptcha，既能避免Hydration错误，又能保证组件正常交互。

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