使用googlemaps扩展组件库时遇CustomElementRegistry重复注册等错误求助

问题根源 #

1. CustomElementRegistry重复定义：Google Maps的Web组件在Next.js服务端渲染（SSR）流程中被重复注册，因为框架会在服务端、客户端两次执行组件代码。
2. HTMLDivElement is not defined：服务端环境不存在浏览器的DOM API，这些Web组件依赖浏览器专属的DOM对象，直接在SSR中运行必然报错。

具体解决方案 #

方案1：动态导入组件并禁用SSR #

让Google Maps组件仅在客户端渲染，彻底避开服务端执行逻辑：

import dynamic from 'next/dynamic';

// 动态导入，强制仅客户端加载
const APILoader = dynamic(
  () => import('@googlemaps/extended-component-library').then(mod => mod.APILoader),
  { ssr: false }
);
const PlacePicker = dynamic(
  () => import('@googlemaps/extended-component-library').then(mod => mod.PlacePicker),
  { ssr: false }
);

export default function YourMapComponent() {
  return (
    <APILoader apiKey="你的Google API密钥">
      <PlacePicker />
    </APILoader>
  );
}

方案2：手动控制组件注册时机 #

如果动态导入后仍有重复注册问题，可以在客户端初始化时只注册一次组件：
先在pages/_app.js中添加注册逻辑：

import { useEffect } from 'react';
import { APILoader, PlacePicker } from '@googlemaps/extended-component-library';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    // 仅在客户端执行，且检查组件是否已注册
    if (!customElements.get('gmpx-api-loader')) {
      customElements.define('gmpx-api-loader', APILoader);
      customElements.define('gmpx-place-picker', PlacePicker);
    }
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

然后在业务组件中直接使用自定义元素标签：

export default function YourMapComponent() {
  return (
    <gmpx-api-loader api-key="你的Google API密钥">
      <gmpx-place-picker></gmpx-place-picker>
    </gmpx-api-loader>
  );
}

方案3：用useEffect延迟客户端渲染 #

通过状态判断仅在客户端加载组件：

import { useState, useEffect } from 'react';
import { APILoader, PlacePicker } from '@googlemaps/extended-component-library';

export default function YourMapComponent() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  // 服务端返回空，避免执行浏览器代码
  if (!isClient) return null;

  return (
    <APILoader apiKey="你的Google API密钥">
      <PlacePicker />
    </APILoader>
  );
}

验证方法 #

1. 替换代码中的你的Google API密钥为真实密钥
2. 重启Next.js应用
3. 检查页面是否正常加载、错误是否消失

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