在Next.js项目中使用azure-maps-control包出现报错的问题求助

问题根因 #

azure-maps-control 是纯客户端库，强依赖浏览器全局对象 window，Next.js 默认的服务端渲染（SSR）/服务端组件执行阶段没有浏览器环境，直接导入调用就会触发报错。

解决方案 #

适用 Next.js 13+ App Router 场景

1. 所有用到该库的组件顶部标记 'use client'，指定为客户端组件
2. 优先使用动态导入并禁用服务端渲染，或者在客户端生命周期中动态导入
   示例代码：

'use client';
import { useEffect, useRef } from 'react';
// 导入官方样式
import 'azure-maps-control/dist/atlas.min.css';

export default function AzureMap() {
  const mapContainerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!mapContainerRef.current) return;
    // 客户端挂载完成后再导入并初始化地图
    import('azure-maps-control').then((atlas) => {
      const map = new atlas.Map(mapContainerRef.current, {
        view: 'Auto',
        authOptions: {
          authType: 'subscriptionKey',
          subscriptionKey: '你的Azure Maps授权密钥'
        }
      });
      // 组件销毁时释放资源
      return () => map.dispose();
    });
  }, []);

  return <div ref={mapContainerRef} style={{ width: '100%', height: '600px' }} />;
}

适用 Next.js Pages Router 场景

1. 将地图逻辑封装为单独组件，用next/dynamic导入时关闭SSR

// 页面组件中导入地图组件
import dynamic from 'next/dynamic';
const AzureMap = dynamic(() => import('../components/AzureMap'), {
  ssr: false
});

export default function Home() {
  return <AzureMap />;
}

// components/AzureMap.tsx 地图组件逻辑
import { useEffect, useRef } from 'react';
import * as atlas from 'azure-maps-control';
import 'azure-maps-control/dist/atlas.min.css';

export default function AzureMap() {
  const mapRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!mapRef.current) return;
    const map = new atlas.Map(mapRef.current, {
      view: 'Auto',
      authOptions: {
        authType: 'subscriptionKey',
        subscriptionKey: '你的Azure Maps授权密钥'
      }
    });
    return () => map.dispose();
  }, []);

  return <div ref={mapRef} style={{ width: '100%', height: '600px' }} />;
}

注意事项 #

• 所有调用atlas相关API的逻辑必须放在客户端执行的生命周期中，比如useEffect、用户事件回调，禁止在组件顶层同步调用
• TypeScript开发可安装@types/azure-maps-control获得完整类型提示
• 依赖安装命令：npm install azure-maps-control @types/azure-maps-control

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