使用SvelteKit创建Mapbox地图时出现500内部错误求助

问题根源 #

SvelteKit默认采用服务端渲染（SSR），而Mapbox GL依赖浏览器环境（如window对象、DOM元素），服务端执行时无法获取这些环境变量，直接初始化地图会触发500内部错误；同时你的组件缺少Mapbox所需的DOM容器元素，也是潜在问题。

修复步骤 #

1. 仅在浏览器端初始化地图 #

使用Svelte的onMount生命周期钩子，该钩子仅在组件挂载到浏览器DOM后执行，避开服务端渲染阶段。

2. 添加地图容器元素 #

必须提供一个带有指定ID的DOM元素作为地图容器，并设置明确的宽高。

3. 可选：禁用组件的SSR #

如果不需要该组件在服务端渲染，可以直接禁用组件的SSR，确保所有代码仅在客户端执行。

修改后的组件代码 #

src/lib/mapboxmap.svelte：

<!-- 可选：禁用组件SSR，彻底避免服务端执行Mapbox代码 -->
<script context="module">
    export const ssr = false;
</script>

<script>
    import { onMount } from 'svelte';
    import mapboxgl from 'mapbox-gl';
    import 'mapbox-gl/dist/mapbox-gl.css';

    mapboxgl.accessToken = 'pk.eyJ1Ijoicm9iaW5rb2hycyIsImEiOiJjanU5am95bm4xZnZ6NDNrOTRyYTYwdzJzIn0.iMFQgQIlhz36wB3819Xftw';
    let map;

    onMount(() => {
        // 仅在浏览器环境初始化地图
        map = new mapboxgl.Map({
            container: 'map',
            style: 'mapbox://styles/examples/cjgioozof002u2sr5k7t14dim',
            center: [-96, 37.8], // 设置默认地图中心
            zoom: 3 // 设置默认缩放级别
        });

        console.log('map: ', map);

        // 组件销毁时清理地图实例，避免内存泄漏
        return () => {
            map?.remove();
        };
    });
</script>

<!-- 地图容器，必须设置宽高才能显示 -->
<div id="map" style="width: 100%; height: 400px;"></div>

路由页面代码（无需修改） #

src/routes/+page.svelte：

<script>
    import Mapboxmap from '../lib/mapboxmap.svelte';
</script>

<Mapboxmap />

关键说明 #

• onMount确保地图初始化逻辑仅在浏览器环境执行，避免服务端因缺少浏览器API报错。
• 地图容器必须设置明确的宽高，否则地图会因尺寸为0而无法正常显示。
• 禁用SSR（export const ssr = false）是可选方案，但能彻底规避服务端执行Mapbox相关代码的问题。

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