Next.js中使用@mapbox/search-js-react报document未定义错误求助

核心原因 #

Next.js的服务端渲染(SSR)环境中不存在document对象，仅用typeof window !== "undefined"判断组件渲染时机，无法阻止组件导入时其依赖的Mapbox包代码在服务端执行，从而触发错误。

解决方案 #

1. 动态导入组件并禁用SSR #

使用Next.js的dynamic函数导入组件，强制组件仅在客户端加载，避免服务端执行相关代码：

import dynamic from 'next/dynamic';

// 动态导入你的PlacesSuggest组件，禁用SSR
const PlacesSuggest = dynamic(() => import('./PlacesSuggest'), {
  ssr: false,
});

// 在页面中直接使用组件，无需额外判断
export default function SearchPage() {
  return (
    <div>
      <PlacesSuggest />
    </div>
  );
}

2. 调整组件内部代码 #

如果组件内部直接在顶层调用了依赖document/window的Mapbox API，需将这些代码移至useEffect钩子中（仅在客户端执行），或用环境判断包裹：

import { useEffect, useState } from 'react';
import { usePlacesSearch } from '@mapbox/search-js-react';

function PlacesSuggest() {
  const [search, setSearch] = useState(null);

  useEffect(() => {
    // 仅在客户端初始化搜索实例
    const searchInstance = usePlacesSearch({
      accessToken: '你的Mapbox令牌'
    });
    setSearch(searchInstance);
  }, []);

  return (
    <div>
      {/* 组件内容 */}
    </div>
  );
}

export default PlacesSuggest;

3. 客户端初始化Mapbox配置 #

若在全局设置Mapbox令牌等配置，需将初始化代码放在客户端环境中（比如_app.js的useEffect里）：

import { useEffect } from 'react';
import { setAccessToken } from '@mapbox/search-js-react';

export default function MyApp({ Component, pageProps }) {
  useEffect(() => {
    // 仅在客户端设置令牌
    setAccessToken('你的Mapbox令牌');
  }, []);

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

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