Next.js项目中Mapbox无法运行，求助解决TypeError问题

你遇到的TypeError: Cannot read properties of undefined (reading 'mark')错误，核心原因有两个：

• 地图初始化时机错误：在React组件外部直接创建mapboxgl.Map实例时，DOM中的#map元素还未被渲染，mapbox-gl无法找到容器元素，进而引发内部错误。
• （若使用Next.js等SSR框架）服务器端渲染冲突：mapbox-gl是浏览器端专属库，在服务器端执行时会因为缺少浏览器环境API而报错。

修正方案 #

1. 调整初始化时机到React生命周期内

使用useEffect钩子，确保DOM元素挂载后再初始化地图，同时添加清理逻辑防止内存泄漏：

import { useEffect, useRef } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

mapboxgl.accessToken = '你的API密钥';

export default function Home() {
  const mapContainerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() => {
    // 容器不存在或地图已初始化则跳过
    if (!mapContainerRef.current || mapRef.current) return;

    // 初始化地图
    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [-74.5, 40],
      zoom: 9,
    });

    // 地图加载完成后的回调（可选）
    mapRef.current.on('load', () => {
      console.log('地图加载完成');
    });

    // 清理函数：组件卸载时销毁地图实例
    return () => {
      if (mapRef.current) {
        mapRef.current.remove();
        mapRef.current = null;
      }
    };
  }, []);

  // 必须给地图容器设置宽高样式
  return (
    <div
      ref={mapContainerRef}
      style={{ width: '100vw', height: '100vh' }}
    />
  );
}

2. 处理Next.js等SSR框架的特殊情况

如果你的项目是Next.js，需要避免在服务器端加载mapbox-gl，可通过动态导入禁用SSR：

import { useEffect, useRef } from 'react';
import dynamic from 'next/dynamic';

// 动态导入mapbox-gl，禁用SSR
const MapboxGl = dynamic(() => import('mapbox-gl'), { ssr: false });

export default function Home() {
  const mapContainerRef = useRef(null);
  const mapRef = useRef(null);

  useEffect(() => {
    if (!mapContainerRef.current || mapRef.current || !MapboxGl) return;

    MapboxGl.accessToken = '你的API密钥';
    mapRef.current = new MapboxGl.Map({
      container: mapContainerRef.current,
      style: 'mapbox://styles/mapbox/streets-v12',
      center: [-74.5, 40],
      zoom: 9,
    });

    return () => {
      if (mapRef.current) {
        mapRef.current.remove();
        mapRef.current = null;
      }
    };
  }, []);

  return (
    <div
      ref={mapContainerRef}
      style={{ width: '100vw', height: '100vh' }}
    />
  );
}

关键注意事项 #

• 必须给地图容器设置明确的宽高样式，否则地图会因容器尺寸为0而无法显示。
• 不要在组件外部或函数顶层直接执行地图初始化，必须等待DOM挂载完成。
• 若之前修改过webpack配置，可先恢复默认配置，新版mapbox-gl已自带worker文件适配逻辑，无需额外配置。

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